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 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 local realms, transports, bounded lifetimes and stores, cookies, placeholders and TLS validation.
• 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, and System API system keys.
• 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-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, 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 authcrunch config. A user registration <name> block names its target identity store; authcrunch validates that store, marks it registration-enabled, and attaches the registry to any portal that has that identity store enabled. Do not generate an enable user registration <name> portal line: the current enable parser does not accept it.