Configuration Authentication Cookies

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.