Configuration Authentication

Purpose

Use this skill to configure authentication portal <name> blocks and the route-level authenticate with <portal> handler.

Use configuration-http-integrations 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 for readable portal refresh configuration, explicit eligible realms, transports, bounded lifetimes and stores, cookies, placeholders and TLS validation. Read named refresh storage for explicit SQLite selection, private file ownership, root-state generations and commit recovery.
• caddyfile_authn_documents.go and Documents configuration 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 to enable QR/link login, explicit approval, browser binding, cancellation and volatile request lifecycle through the existing portal route.
• Use configuration-oauth-applications to configure portal oidc provider blocks, named client selection, private registrations, and dedicated provider signing keys. Its provider reference 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 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 to configure cookie directives and token-cookie naming.
• Use configuration-authentication-ui to configure ui blocks, templates, static assets, custom CSS/JS/HTML, themes, languages, logos, and private links.
• Use configuration-authentication-user-transforms 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.
• Use configuration-ticket-providers to enable trusted application ticket login and its browser-binding provider.
• Use configuration-saml-providers to configure saml identity provider <name> login providers enabled by the portal.
• Use authentication-portal-api to build or troubleshoot JSON login, /whoami, /beacon, refresh token, Documents, and admin/server API interactions.

Shape

{
	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:

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 for the different confirmation and account-activation policies.

Common Portal Options

Use crypto keys for token signing and verification:

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:

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 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:

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.