Configuration Authentication Cookies

Contract and Sources

Portal cookie statements are collected in caddyfile_authn.go. The thin translation in caddyfile_authn_cookie.go preserves legacy Caddy spellings; pkg/authn/cookie/parser.NewCookieConfigFromDirectives in the AuthCrunch version selected by go.mod owns grammar, normalization, duplicates, and validation. PortalConfig.ConfigureCookies installs one complete validated snapshot. It replaces previous cookie settings, rather than merging individual lines. Portal construction wires the final access name into its grantor and validator.

Portal wiring belongs to configuration-authentication and policy behavior to configuration-authorization. Upstream source is read-only.

Set Every Default Name with One Prefix

authentication portal myportal {
    enable identity store localdb
    set cookie name prefix PORTAL
}

That one statement covers all ten roles:

set cookie name prefix portal preserves the legacy uppercasing behavior. The shared spelling cookie prefix PORTAL preserves the supplied case. With neither statement, every role uses the same suffix with AUTHP_. For initialized Go configs, call SetCookieNamePrefix; assigning CookieNamePrefix directly does not rename already initialized fields.

The SAML session cookie binds a SAML login to its initiating browser. It uses host-only scope, path /, Secure, HttpOnly, SameSite=None and a 300-second lifetime. Its name participates in shared prefix, override and collision checks; changing its name does not weaken SAML state or assertion validation.

The cross-device cookie role is supplied by the v1.3.11 shared parser and uses cookie cross-device session id name <name>. It participates in prefix, uniqueness and runtime resolution just like the other names. Naming this cookie does not enable cross-device login. Use configuration-authentication-cross-device to enable the optional flow and review its browser-binding lifetime and scope. Its Secure/HttpOnly/host-only, mount-scoped, SameSite=None binding uses a 300-second Max-Age independently of ordinary cookie options. __Host- requires a root mount; a nested mount fails closed.

Explicit Names and Precedence

Explicit names are complete, literal cookie names. No prefix is added to them. Keep the naming convention consistent in examples:

authentication portal myportal {
    enable identity store localdb
    cookie session id name AUTHP_SESSION_ID
    cookie access token name AUTHP_LOGIN_ACCESS
    cookie oidc session id name AUTHP_LOGIN_SESSION
    cookie oidc request id name AUTHP_LOGIN_REQUEST
    cookie saml session id name AUTHP_LOGIN_SAML
    cookie cross-device session id name AUTHP_LOGIN_TRANSFER
    cookie refresh token name AUTHP_LOGIN_REFRESH
    cookie referer name AUTHP_LOGIN_REDIRECT
    cookie sandbox id name AUTHP_LOGIN_SANDBOX
    cookie identity token name AUTHP_LOGIN_IDENTITY
}

An explicit name wins independently of statement order, including one equal to an old default. For example, cookie session id name AUTHP_SESSION_ID plus set cookie name prefix PORTAL leaves that session name unchanged and sets all nine omitted names to PORTAL_<SUFFIX>. cookie access token name LOGIN_ACCESS is also valid and stays exactly LOGIN_ACCESS; use AUTHP_LOGIN_ACCESS when the intended convention is AUTHP.

redirect url aliases referer; id token aliases identity token. Legacy set <role> cookie name <name> supports session_id, redirect_url, sandbox_id, id_token, access_token, and refresh_token.

Each prefix, name (including aliases), and attribute per scope may be set once. Duplicate statements are errors even when the values agree. Final names must be valid HTTP cookie names and distinct across all ten roles. Names may be explicitly unprefixed. __Host- and __Secure- remain optional compatibility cases; a name alone does not establish the required attributes.

For enabled portal token refresh, an explicit token refresh { cookie name ... } overrides the shared refresh name before shared-parser collision checks and cookie factory construction. An override may free the old name for another role; duplicate shared settings still fail. Deferred refresh also defers cookie parsing, even for literal cookies. Without that override, the shared name/prefix wins. Disabled refresh does not rename cookies. Active refresh cookies use the configured portal mount with host-only, Secure, HttpOnly, SameSite=Lax attributes; the legacy refresh subpath below only describes retired-cookie cleanup.

Reserved-Prefix Compatibility

AuthCrunch v1.3.3 preserves Secure, HttpOnly, SameSite, domain, and path on matching deletion cookies, with a past expiry and Max-Age=0. __Secure- names require secure cookies. __Host- additionally requires no Domain and Path=/; a configured access path or domain must respect that scope. Prefix checks are case-insensitive.

Access and session cookies can use explicit __Host- names with a portal mounted at /auth, because their configured/default paths can remain /:

cookie session id name __Host-SESSION
cookie access token name __Host-ACCESS
cookie path /

A common __Host- prefix also names referer and sandbox cookies, so that portal must be mounted at /. Its identity-cookie role needs a compatible override because identity cookies use the /whoami subpath:

cookie prefix __Host-PORTAL
cookie identity token name __Secure-PORTAL_ID_TOKEN

Static incompatibilities fail configuration. A dynamically inferred non-root mount with host-prefixed referer/sandbox cookies fails the request with HTTP 500 before issuing portal cookies. The retired refresh-cookie subpath cannot carry a __Host- cookie; upstream omits that legacy tombstone and leaves active refresh cleanup to its feature runtime. These examples do not enable OIDC or refresh.

Attributes and Domains

cookie path /app
cookie lifetime 3600
cookie same site lax
cookie insecure disabled
cookie guess domain disabled
cookie strip domain enabled

cookie domain example.com
cookie domain example.com path /app
cookie domain example.com lifetime 600
cookie domain example.com same site strict
cookie domain example.com insecure disabled
cookie domain example.com strip domain enabled

same site/samesite accepts lax, strict, or none, normalized by the shared validator. Lifetime is an integer interpreted by the issuing runtime; use positive seconds for an expiring access cookie. Global and domain settings are separate scopes. Domain guess domain is unsupported. Legacy forms remain:

cookie guess domain
cookie strip domain
cookie insecure off
cookie example.com path /app
cookie example.com lifetime 600
cookie example.com samesite strict
cookie example.com insecure off
cookie example.com strip domain

Legacy insecure also accepts on/off, yes/no, true/false, and 1/0. Domain insecure no longer mutates global or unrelated domain settings. An explicit domain defaults to secure cookies; global insecure enabled alone does not make an explicit domain insecure. Do not rely on the old parser's order-dependent propagation of insecure across domains.

Domain names are lowercased and a leading dot is removed. Attributes can create a domain entry without a separate declaration. The first occurrence sets its sequence; subsequent attributes do not move it. Runtime matching prefers an exact host, otherwise the last matching suffix in declaration order. Choose overlapping domains deliberately; this is not automatic longest-suffix selection. Duplicate normalized domain declarations/settings are rejected.

Host-only cookies are the default. guess domain omits public suffixes such as fly.dev. Domain-level strip domain enabled keeps the selected domain's attributes while emitting a host-only cookie.

Access cookies use domain/global path, lifetime, and SameSite settings. Session cookies use /. Referer and sandbox cookies use the portal base path; identity-token cookies use <base>/whoami; legacy refresh cookies use <base>/api/refresh_token. These roles do not all inherit the access path. OIDC and refresh features own additional, stricter issuance requirements.

Placeholders and JSON

Caddy {$ENV} expansion happens before adaptation. Empty and whitespace-only arguments are rejected before cfgutil.EncodeArgs, which trims trailing empties. Quoted values retain token boundaries; replacements cannot inject statements.

If any portal cookie statement contains a runtime placeholder or secret lookup, the entire collection is retained as security.portal_cookie_directives, keyed by portal name. Provisioning expands each argument, translates legacy syntax, and parses/applies the complete snapshot once. All cookie statements for that portal are deferred together, so duplicate aliases, colliding resolved names, and domains that resolve to the same value are checked together. Deferred validation happens during provisioning; adaptation alone cannot validate it.

Preserve argument values through every encode/decode step, including trailing tabs and Unicode whitespace. The shared CSV codec trims record-edge whitespace; use the lossless directive encoder so an invalid cookie name cannot become valid before validation or be hidden by an enabled refresh-name override. Resolve into tokens and translate legacy syntax before re-encoding, with no lossy intermediate statement. Reject CR/LF in saved statements before decoding: the decoder consumes one record and would otherwise ignore subsequent settings. Replacements must also reject empty, multiline, NUL and invalid UTF-8 arguments before encoding.

The deferred snapshot replaces any typed cookie_config supplied for that portal in JSON. Unknown or ambiguous portal references fail. Literal-only Caddyfiles emit typed cookie_config directly. JSON roundtrips preserve both forms. Existing typed JSON supports runtime replacement of path/domain fields; use the deferred statement collection for runtime names and prefixes. Resolved path values remain literal, including braces or spaces, in both legacy and shared syntax. Typed JSON domain maps are rebuilt once; two entries resolving to the same key fail instead of silently replacing one domain's settings.

Coordinate Gatekeepers Explicitly

For the prefix-only portal above:

authorization policy app_policy {
    crypto key verify {env.JWT_SHARED_KEY}
    set session_id cookie name PORTAL_SESSION_ID
    set access_token cookie name PORTAL_ACCESS_TOKEN
    set token sources cookie
    allow roles authp/user
}

Use compatible portal signing keys. For the AUTHP explicit-name example, use:

set session_id cookie name AUTHP_SESSION_ID
set access_token cookie name AUTHP_LOGIN_ACCESS

The Caddy policy parser maps these to PolicyConfig.SessionIDCookieName and AccessTokenCookieNames. The session name carries correlation information; it is not an access credential. Multiple access names can be intentionally listed on one statement. Explicit access lists replace defaults.

During runtime resolution, absent policy cookie settings become AUTHP_SESSION_ID and [AUTHP_ACCESS_TOKEN, access_token, jwt_access_token]. This prevents AuthCrunch's server-wide portal-name discovery. Custom portal names are never implicitly shared across policies, including portals in one security app. Deployments that relied on automatic discovery must add explicit policy names. Equal names and signing keys still share credentials by design; cookie names alone do not isolate trust.

Naming does not enable bearer, Basic, API-key, refresh, or identity-token credentials. Existing token source settings still apply. AuthCrunch also adds explicit access names, lowercased, to its named header/query lookup lists; use set token sources cookie when only cookie transport should be accepted. Policy cookie names can use Caddy {$ENV} expansion; typed policy names are not runtime-replaced.

OAuth IdentityTokenCookieName belongs to the upstream identity provider, which can be shared by portals. A portal prefix never rewrites it. Configure that provider explicitly when changing its ID-token cookie name; the portal's identity-cookie role is not an override of the shared provider.

Validation

• caddyfile_authn_cookie_test.go: grammar, legacy translation, all nine prefix defaults, order independence, domains, quoted/empty values, duplicates, malformed input, runtime replacement, and typed/deferred JSON roundtrips.
• cookie_policy_test.go: defaults/overrides, session ID consumption, shared provider ownership, and malformed policy settings.
• cookie_e2e_test.go: real TLS Caddy login, protected resources, and logout; public-suffix-aware jars, host/path boundaries, matching deletion, negative credential transports, cross-portal names, literal resolved paths, and rejected reloads. Includes explicit secure-prefixed cookies and root-mounted host-prefixed cookies, with issuance/deletion checks for Secure, HttpOnly, SameSite, domain, path, Max-Age, and expiry. Certificate verification is enabled. These are HTTP attribute assertions and jar tests; the jar does not enforce a browser's SameSite or reserved-prefix rules.
• testdata/caddyfile_adapt/testcase_authenticate_with_cookie_parser.* covers complete explicit grammar, set cookie name prefix PORTAL alone, reserved prefixes, and legacy runtime paths containing literal braces. Domain/credentials fixtures retain runtime placeholders and resolved snapshots.

Run focused checks with:

go test -mod=readonly -race -count=1 -run 'TestPortalCookie|TestPolicyCookie|TestAppCookie|TestCaddyCookiesE2E|TestCaddyfileAdaptAuthenticationToJSON|TestResolveRuntimeAppConfig' .

TestCaddyTokenRefreshE2E and TestCaddyOIDCProviderE2E exercise the stricter refresh/OP cookie scopes, origin checks, rotation, and logout requirements. The refresh E2E also rejects malformed shared-cookie names and saved multiline statements during reload, then rotates the original session to verify that the failed candidate preserved its store. The registered testcase_authenticate_with_token_refresh_cookie_whitespace fixture covers literal whitespace rejection before a refresh-name override.