Configuration

Purpose

Use this skill as the entry point for generating caddy-security Caddyfile configuration. Keep the parent skill as a router: load only the domain skills needed for the requested configuration.

The repository scope applies to every configuration domain. Upstream paths in these skills are read-only implementation references. Keep Caddyfiles, fixtures, custom assets, and local validation changes here; missing upstream behavior is separate work, not a reason to edit or run tests in ../go-authcrunch.

The parser entry point is caddyfile.go. Put security { ... } inside Caddy's outer global options block, { ... }. Route-level HTTP integrations reference configured objects with authenticate with <portal> and authorize with <policy>. Define the global security option once; duplicate blocks fail instead of silently replacing the previous app. Collect declarations inside that one block.

Do not generate global Caddy directive-order overrides for caddy-security by default. authenticate and authorize register their own order in plugin_authn.go and plugin_authz.go. Only add global order directives when debugging a proven directive-order conflict with another third-party plugin, and explain why.

Syntax Currency

Use Syntax maintenance when auditing syntax, changing directives, or consuming a Caddy/go-authcrunch dependency update. The AuthCrunch compatibility map tracks changed upstream surfaces, Caddy ownership and validation. The Caddy wrappers and the selected upstream parsers jointly define the syntax. Maintain Go syntax comments, standalone Caddyfiles, fixtures, and domain skills together, including grammar delegated to upstream libraries or external modules.

Keep recognized-but-restricted forms visible with their validation status. For example, document logout_url <logout_url> and the shared OAuth validator's rejection; do not erase it or silently filter it from input. Upstream typed fields alone do not establish Caddyfile support.

Examples containing only inner blocks or individual directives are fragments for the enclosing scope described by the domain skill. Complete configurations need the outer global block and site routes. <value> denotes a required value, <a|b> a required choice, [value] an optional argument, and ... repetition; syntax catalogues with these placeholders are not runnable examples.

Workflow

1. Identify the requested auth flow: local login, LDAP, OAuth/OIDC, SAML, API keys, basic auth, registration, SSO app, or policy-only authorization.
2. Follow only the matching Domain Map routes before drafting the Caddyfile. HTTP handler placement includes the HTTP integration route; external SAML login follows the SAML provider route, separately from portal SSO apps. Authentication's narrower routes cover portal sub-blocks. HTTP client/API contracts belong to authentication-portal-api.
3. Start from the smallest valid security app block, then add route handlers that reference the configured portal or policy by name.
4. Prefer environment placeholders or secret lookups for passwords, API keys, client secrets, signing keys, and private material.
5. Check generated syntax against the local wrappers, selected upstream grammar and validators, and the fixtures under testdata/caddyfile_adapt/. Test and fixture changes follow the testing contract.

Common Shape

{
	security {
		local identity store localdb {
			realm local
			path assets/config/users.json
		}

		authentication portal myportal {
			crypto key sign-verify {env.JWT_SHARED_KEY}
			enable identity store localdb
		}

		authorization policy app_policy {
			crypto key verify {env.JWT_SHARED_KEY}
			set auth url /auth
			allow roles authp/admin authp/user
		}
	}
}

example.com {
	@portal path /auth /auth/*
	route @portal {
		authenticate with myportal
	}

	route /app* {
		authorize with app_policy
		reverse_proxy 127.0.0.1:8080
	}
}

Use the optional matcher forms only when needed:

@portal path /auth /auth/*
authenticate @portal with myportal
authorize /api/* with api_policy

Domain Map

• Use configuration-logging to configure diagnostic skip rules, parsed by caddyfile_logging.go. AuthCrunch component filtering is supported; Caddy's independent authentication middleware logger needs an upstream hook.
• Use configuration-state to configure persistent runtime state, parsed by caddyfile_state.go. Stop/start persistence also supports policy-only OAuth.
• Use configuration-http-integrations to place authenticate and authorize HTTP routes, parsed by plugin_authn.go and plugin_authz.go.
• Use configuration-authentication to configure authentication portals, parsed by caddyfile_authn.go and caddyfile_authn_*.go. Its routes own cookies, UI, transforms, cross-device login, and Portal APIs.
• Use configuration-authorization to configure authorization policies, parsed by caddyfile_authz.go and caddyfile_authz_*.go.
• Use configuration-crypto to configure crypto directives and token or System API keys, parsed by caddyfile_authn_crypto.go and caddyfile_authz_crypto.go, implemented by go-authcrunch/pkg/kms, and resolved by caddyfile_resolve.go.
• Use configuration-credentials to configure reusable generic credentials, parsed by caddyfile_credentials.go.
• Use configuration-identity-stores to configure local and LDAP stores, parsed by caddyfile_identity.go and caddyfile_identity_store.go.
• Use configuration-messaging to configure messaging providers, parsed by caddyfile_messaging.go.
• Use configuration-oauth-providers to configure external OAuth/OIDC identity providers, parsed by caddyfile_identity.go, caddyfile_identity_provider.go, and caddyfile_identity_provider_oauth.go, delegated to go-authcrunch/pkg/idp/parser and pkg/idp/oauth/parser.
• Use configuration-oauth-applications to register named OAuth clients, configure private registration storage and portal oidc provider blocks, or provision credentials through the CLI. caddyfile_oauth_application.go delegates client parsing to go-authcrunch/pkg/oidc/parser and Config.AddOAuthApplication. Clients have explicit or persisted credentials. caddyfile_oauth_registration_store.go parses oauth registration store; app JSON uses oauth_registration_store. This holds application credentials and provider keys independently of user registration and sessions.
• Use configuration-saml-providers to configure SAML login identity providers, parsed by caddyfile_identity.go and caddyfile_identity_provider.go, implemented by go-authcrunch/pkg/idp/saml.
• Use configuration-registrations to configure user registrations, parsed by caddyfile_user.go and caddyfile_user_registration.go.
• Use configuration-runtime-resolution to configure runtime placeholder and secret resolution, applied by caddyfile_resolve.go.
• Use configuration-secrets to configure secrets managers and secret lookups, parsed by caddyfile_secrets.go and resolved by caddyfile_resolve.go.
• Use configuration-sso-app to configure SSO app providers, parsed by caddyfile_sso_provider.go.

Portal JSON/admin API contracts belong to authentication-portal-api, routed from configuration-authentication. The upstream go-authcrunch/pkg/authn/handle_* handlers implement them; authentication portal options enable them in Caddyfile.

Keep this map and its intermediate authentication routes synchronized with every directory matching .codex/skills/configuration-*.

SAML identity-provider blocks are distinct from SSO app providers: the SAML provider route configures external login, while the SSO app route configures portal-provided SAML app endpoints.

Fixtures

Use qualified operator examples for complete outer Caddyfiles and their generated, tested native JSON: legacy access, local token refresh, Ed25519 upstream OAuth, named applications, two OPs with refresh, and explicit administrative private export. It covers private setup, exact provisioning commands, realm/token/cookie boundaries and replacement limits.

Use these examples for orientation:

• testdata/caddyfile_adapt/testcase_security_authentication_portal.Caddyfile for local users, portal crypto, cookies, UI links, and transforms.
• testdata/caddyfile_adapt/testcase_authenticate_with_oauth.Caddyfile for OAuth plus authorization policy wiring.
• testdata/caddyfile_adapt/testcase_authenticate_with_registration.Caddyfile for registration, messaging, local users, and portal wiring.
• testdata/caddyfile_adapt/testcase_security_with_secrets.Caddyfile for secrets manager values consumed by users and crypto keys.

Acceptance criteria

• A requested login/provider combination has one owning route; external SAML login, SAML SSO apps, external OAuth login, and portal OIDC clients remain distinct.
• Complete examples include global security declarations, matching portal/policy names, and exact portal mounts. Fragments state the enclosing scope and missing wiring; successful adaptation alone is not reported as successful login.
• Runtime values are checked against the fields that actually resolve. Missing plugins or unsupported upstream behavior remain explicit qualification limits.