configuration-authentication-cookies

Configuration Authentication Cookies

Purpose

Use this skill for cookie directives and token-cookie naming inside authentication portal <name> blocks.

Read these files when details matter:

• caddyfile_authn_cookie.go for accepted Caddyfile cookie syntax.
• caddyfile_authn_misc.go for set <token> cookie name and cookie prefix directives.
• ../go-authcrunch/pkg/authn/cookie/ for cookie defaults, domain matching, SameSite validation, and emitted attributes.
• ../go-authcrunch/pkg/authn/portal.go for how access-token cookie names feed the portal validator and grantor.

Use configuration-authentication for the surrounding portal and authenticate handler wiring.

Cookie Directives

Configure global cookie settings with two-argument forms:

authentication portal myportal {
	cookie domain example.com
	cookie path /
	cookie lifetime 86400
	cookie samesite lax
	cookie insecure off
	cookie guess domain
	cookie strip domain
}

cookie domain <name> creates a domain-specific entry. cookie guess domain derives a cookie domain from the request host and omits the domain when the derived value is a public suffix. cookie strip domain forces host-only cookies.

Configure domain-specific overrides with cookie <domain> <key> <value>:

cookie example.com path /
cookie example.com lifetime 3600
cookie example.com samesite strict
cookie example.com strip domain

Supported keys are domain, path, guess, lifetime, samesite, insecure, and strip domain; guess only affects the global two-argument form. lifetime must be a positive integer. samesite is validated by authcrunch and accepts lax, strict, or none.

Cookie Names

Authcrunch defaults use the AUTHP prefix:

• AUTHP_SESSION_ID
• AUTHP_REDIRECT_URL
• AUTHP_SANDBOX_ID
• AUTHP_ID_TOKEN
• AUTHP_ACCESS_TOKEN
• AUTHP_REFRESH_TOKEN

Use set <token> cookie name <name> for individual cookie names:

set session_id cookie name AUTHP_SESSION_ID
set redirect_url cookie name AUTHP_REDIRECT_URL
set sandbox_id cookie name AUTHP_SANDBOX_ID
set id_token cookie name AUTHP_ID_TOKEN
set access_token cookie name AUTHP_ACCESS_TOKEN
set refresh_token cookie name AUTHP_REFRESH_TOKEN

Setting access_token also updates the portal token grantor and validator cookie names. Use set cookie name prefix <prefix> to uppercase the prefix and rebuild all default cookie names:

set cookie name prefix AUTHP

Effective Scope

Cookie domain and path behavior is often the cause of successful login followed by protected-route redirects. By default, cookies are host-only unless cookie domain <domain> or cookie guess domain sets a Domain attribute. Do not add a leading dot to cookie domains.

Common default portal cookie paths:

• Session and access-token cookies are broad and normally use /.
• Redirect and sandbox cookies are portal-base scoped, such as /auth/.
• ID-token cookies are scoped to the portal identity endpoint, commonly <base>/whoami.
• Refresh-token cookies are scoped to the refresh-token API path, commonly <base>/api/refresh_token.

When authenticate and authorize run on separate Caddy instances, mirror custom access-token and session cookie names in the authorization policy:

authorization policy app_policy {
	set session_id cookie name CONTOSO_SESSION_ID
	set access_token cookie name CONTOSO_ACCESS_TOKEN
}

When the portal and policy are in the same provisioned security app, authcrunch can discover the portal access-token cookie name for local gatekeepers, but cross-instance deployments cannot rely on that shared runtime state.

Fixtures

Use these fixtures as examples:

• testdata/caddyfile_adapt/testcase_authenticate_with_cookie_domain.Caddyfile
• testdata/caddyfile_adapt/testcase_authenticate_with_cookie_guess.Caddyfile
• testdata/caddyfile_adapt/testcase_authenticate_with_ui.Caddyfile