configuration-authentication

# Configuration Authentication ## Purpose Use this skill to configure `authentication portal <name>` blocks and the route-level `authenticate with <portal>` handler. Use [configuration-http-integrations](../configuration-http-integrations/SKILL.md) to place portal routes, select matchers, wire same-host or split-host portals, separate portal/protected routes, and check directive ordering. Read these files when details matter: - `caddyfile_authn.go` for the portal block. - `caddyfile_authn_token_refresh.go` and [token refresh](references/token-refresh.md) for readable portal refresh configuration, explicit eligible realms, transports, bounded lifetimes and stores, cookies, placeholders and TLS validation. Read [named refresh storage](references/refresh-storage.md) for explicit SQLite or Consul selection, private file ownership, root-state generations and commit recovery. - `caddyfile_authn_documents.go` and [Documents configuration](references/documents.md) for flat API directives, explicit local realms, private storage, quotas, runtime values and permanent origin/mount bindings. - `caddyfile_authn_crypto.go` for crypto key directives. - `caddyfile_authn_misc.go` for `enable`, `validate`, and `trust`. - `caddyfile_authn_admin_api.go` and selected upstream `pkg/authn/admin_api/parser` for the independent admin/API key-export switches. - `plugin_authn.go` for route-level `authenticate` syntax. - `../go-authcrunch/config.go` for portal validation, default backend attachment, and user registration wiring. - `../go-authcrunch/pkg/authn/config.go` and `../go-authcrunch/pkg/authn/portal.go` for portal defaults and runtime behavior. Use focused repo-local skills for specialized portal sub-blocks: - Use [configuration-authentication-cross-device](../configuration-authentication-cross-device/SKILL.md) to enable QR/link login, explicit approval, browser binding, cancellation and volatile request lifecycle through the existing portal route. - Use [configuration-oauth-applications](../configuration-oauth-applications/SKILL.md) to configure portal `oidc provider` blocks, named client selection, private registrations, and dedicated provider signing keys. Its [provider reference](../configuration-oauth-applications/references/oidc-provider.md) covers explicit realm participation and separate issuers/cookie scopes across portals; attaching a store for portal login does not enable its realm for OIDC. - Use [configuration-crypto](../configuration-crypto/SKILL.md) to configure portal `crypto` defaults, JWT signing keys, auto-generated keys, token names and lifetimes, secret-backed key material, System API `system` keys, and explicitly selected `access signer` and `access token profile` settings. - Use [configuration-authentication-cookies](../configuration-authentication-cookies/SKILL.md) to configure `cookie` directives and token-cookie naming. - Use [configuration-authentication-ui](../configuration-authentication-ui/SKILL.md) to configure `ui` blocks, templates, static assets, custom CSS/JS/HTML, themes, languages, logos, and private links. - Use [configuration-authentication-user-transforms](../configuration-authentication-user-transforms/SKILL.md) to configure `transform user` blocks, ACL matchers, typed claims, conditional challenge selection, additive legacy requirements, claim replacements, and transform UI links. Persisted local-user challenge rules belong to [configuration-users](../configuration-users/SKILL.md). - Use [configuration-ticket-providers](../configuration-ticket-providers/SKILL.md) to enable trusted application ticket login and its browser-binding provider. - Use [configuration-saml-providers](../configuration-saml-providers/SKILL.md) to configure `saml identity provider <name>` login providers enabled by the portal. - Use [authentication-portal-api](../authentication-portal-api/SKILL.md) to build or troubleshoot JSON login, `/whoami`, `/beacon`, refresh token, Documents, and admin/server API interactions. ## Shape ```caddyfile { security { local identity store localdb { realm local path assets/config/users.json } authentication portal myportal { crypto default token lifetime 3600 crypto key sign-verify {env.JWT_SHARED_KEY} enable identity store localdb } } } example.com { @portal path /auth /auth/* route @portal { authenticate with myportal } } ``` The portal name must match the `authenticate with <portal>` reference. Route-level syntax also allows a matcher: `authenticate @matcher with <portal>`. Use `myportal` or a descriptive name such as `employee_portal` in examples, fixtures, and tests. Avoid naming a portal `portal`: the repeated words in `authentication portal portal` are confusing. Keep references consistent, for example `authentication portal myportal` and `authenticate with myportal`. ## Portal Wiring Add only the backends the portal should use: ```caddyfile enable identity store localdb enable identity provider github azure enable sso provider aws ``` Define those stores, identity providers, or SSO app providers with the matching domain skills before enabling them. `enable identity provider <name>` references `oauth identity provider <name>` or `saml identity provider <name>` blocks; `enable sso provider <name>` references `sso provider <name>` SSO app blocks. Identity stores and identity providers can take multiple names on one line. If a portal has no explicit identity stores and no explicit identity providers, authcrunch currently attaches all configured identity stores and identity providers during `Config.Validate()`. Prefer explicit `enable` lines in new examples. After defaults and disabled-backend filtering, a portal must have at least one identity store or identity provider; SSO providers are additional app providers and do not satisfy the login-backend requirement by themselves. User registration is global configuration. `enable user registration <name> [<name>...]` selects named registries whose identity stores must also be enabled in this portal. External SQLite workflows require this explicit selection. Without a nonempty selection, legacy `user registration <name>` blocks attach automatically to eligible stores. Signup visibility belongs to each portal's attached registry metadata. See [registration configuration](../configuration-registrations/SKILL.md) for the different confirmation and account-activation policies. ## Common Portal Options Use crypto keys for token signing and verification: ```caddyfile crypto default token lifetime 3600 crypto key sign-verify {env.JWT_SHARED_KEY} ``` Use both `enable source ip tracking` and `validate source address` when issued tokens should carry and verify the source address. The first sets authcrunch token grantor source-address tracking; the second makes the token validator enforce the source-address claim. Trusted redirect URI checks support login and logout redirect targets: ```caddyfile trust login redirect uri domain exact example.com path prefix /app trust logout redirect uri domain example.com path / ``` The match type is optional and defaults to `exact`; supported match types are `exact`, `partial`, `prefix`, `suffix`, and `regex`. Both `domain` and `path` need values. Keep `login`/`logout`, `redirect`, and `uri` as separate header tokens. Quoted domain/path values remain data even when they contain those words; they cannot change which redirect trust list receives the rule. Login destinations belong to their individual login flows. A rejected, explicitly bound destination returns to `<portal-mount>/portal?redirect_url=`. Preserve the empty marker: it prevents fallback to another tab's return cookie. Legacy local form submissions without a bound destination can still return to `<portal-mount>/portal`. `TestCaddyAuthorizationRedirectE2E` checks untrusted-target rejection through OAuth transactions and legacy local POST/cookie fallback over HTTP/1, HTTP/2, and HTTP/3. The refresh browser E2E checks explicit continuation. Read [login destinations and concurrent tabs](references/login-destinations.md) for bound destination precedence, fresh-login intent, browser proof isolation and the local/provider/Chrome acceptance surfaces. Enable admin/server API endpoints only when they are needed and protected by an authenticated admin session: ```caddyfile enable admin api ``` Both `enable` and `disable` are supported for `admin api` and `admin api private key export`. Each setting occurs at most once in the portal; both default to disabled. Key export does not implicitly enable the API and requires both flags plus authenticated admin authorization at runtime. See `authentication-portal-api` for `/api/server/metadata`, `/api/server/realms`, `/api/server/info`, JSON login, `/beacon`, and `/whoami` behavior. Admin API troubleshooting should check the directive, the active portal session, and whether the user has an admin role before changing route layout. Portal access uses built-in role tiers. `authp/admin` grants administrative portal capabilities, `authp/user` grants normal user settings/profile capabilities, and `authp/guest` is the fallback portal-only role when neither admin nor user roles are assigned. When debugging portal UI access, search debug logs for configured portal access-list rules and inspect transforms that add or drop `authp/*` roles. ## Fixtures Use these fixtures as examples: - `testdata/caddyfile_adapt/testcase_security_authentication_portal.Caddyfile` - `testdata/caddyfile_adapt/testcase_authenticate_with_registration.Caddyfile` `TestParseCaddyfileRedirectTrustMalformed` and `TestParseCaddyfileRedirectTrustValues` cover incomplete selectors and quoted values. `testcase_authenticate_with_redirect_trust_malformed` must fail adaptation with a parser error, not a panic. The redirect-trust subtest in `TestCaddyOAuthE2E` verifies separate login/logout behavior over TLS and confirms that rejected reconfiguration leaves the running portal usable. ## Acceptance criteria - A portal with explicitly selected, enabled backends serves login at its exact mount; a disabled or unknown backend is rejected rather than silently replaced. - Trusted redirect rules retain their intended login/logout scope and matcher semantics after adaptation and runtime replacement. - Refresh/OIDC participation follows each feature's explicit realm eligibility. A portal-only syntax fixture does not qualify renewal, provider exchanges, or durable restart; those outcomes use the linked feature's Caddy unit and E2E evidence.