--- name: configuration-authorization description: "Configure authorization policies, ACLs, bypasses, identity headers, JWT verification, remote Basic/API-key auth, and direct OAuth without a portal." --- # Configuration Authorization ## Purpose Use this skill to configure `authorization policy ` blocks and the route-level `authorize [] with ` handler. Use [configuration-http-integrations](../configuration-http-integrations/SKILL.md) to place protected routes, select matchers, wire same-host or split-host applications, and check directive ordering. Use [configuration-crypto](../configuration-crypto/SKILL.md) to configure JWT verification material, token names/lifetimes, generated or secret-backed keys, and System API `system` keys for remote Basic or API-key authentication. Read these files when details matter: - `caddyfile_authz.go` for the policy block. - `caddyfile_authz_acl.go` and `caddyfile_authz_acl_shortcuts.go` for ACLs. - `caddyfile_authz_bypass.go` for bypass rules. - `caddyfile_authz_crypto.go` for token verification keys. - `caddyfile_authz_inject.go` for claim header injection. - `caddyfile_authz_misc.go` for `enable`, `disable`, `validate`, `set`, and `with`. - `plugin_authz.go` for route-level `authorize` syntax. - `../go-authcrunch/pkg/authz/config.go` and `gatekeeper.go` for policy defaults and runtime wiring. - `../go-authcrunch/pkg/authz/validator/` for token source, bearer, method/path, path-ACL, source-address, Basic, and API-key behavior. - `../go-authcrunch/pkg/acl/` for ACL fields, aliases, match strategies, and action semantics. ## Shape ```caddyfile { security { authorization policy app_policy { crypto key verify {env.JWT_SHARED_KEY} set auth url /auth allow roles authp/admin authp/user } } } example.com { route /app* { authorize with app_policy reverse_proxy 127.0.0.1:8080 } } ``` The policy name must match the `authorize with ` reference. The policy requires a block with unquoted opening and closing braces; quoted brace tokens must not terminate or open a policy. Put auth proxy settings inside the policy block, not inside a block under the route-level `authorize` directive. The current route parser only reads the directive arguments. ## Runtime Defaults A JWT-mode authorization policy must have a name and at least one ACL rule. When no `crypto key ...` entries are present, go-authcrunch auto-generates an ES512 `sign-verify` key with token name `access_token` and lifetime `900`; for real portal-issued tokens, configure compatible verification material explicitly. When explicit key entries are present, at least one key must be `verify` or `sign-verify`. These defaults apply to JWT policies; direct OAuth policies have their own configuration and reject JWT crypto settings. Defaults applied by `PolicyConfig.Validate()` and `Gatekeeper.configure()`: - auth URL: `/auth` - auth redirect query parameter: `redirect_url` - auth redirect status: `302` - token source priority: `cookie`, `header`, `query` - session cookie: `AUTHP_SESSION_ID` - access cookies: `AUTHP_ACCESS_TOKEN`, `access_token`, `jwt_access_token` - named auth headers and query params retain the AuthCrunch defaults; explicit access cookie names also enter those lists in lowercase - API key header: `X-Api-Key` - auth realm header: `X-Auth-Realm` Use `set token sources` only with `cookie`, `header`, and `query`; the order is the lookup priority. `validate bearer header` enables `Authorization: Bearer ` parsing but is not itself a token source name. ## ACLs Read [typed custom ACL fields](references/typed-acl-fields.md) for `acl field` declarations, literal claim keys, typed JSON, adapter ownership and Caddy TLS qualification, including the unconditional default-action fix in v1.3.11. Prefer concise shortcuts for common role, origin, issuer, method, and path matches: ```caddyfile allow roles authp/admin authp/user allow roles authp/guest with get to /public deny iss untrusted ``` Shortcut behavior is not just syntax sugar: - `allow ` becomes `allow log debug`; it does not stop later rules. - `deny ` becomes `deny stop log warn`. - ` any` or ` *` becomes `field exists`. - `with to ` uppercases the method, adds a `partial match path` condition, and enables method/path validation. Use explicit ACL rules when comments, actions, or multiple conditions matter: ```caddyfile acl rule { comment allow users match role authp/user allow stop log info } acl default deny ``` Explicit rule conditions use go-authcrunch ACL grammar: ```caddyfile match any match roles authp/admin authp/user partial match email @example.com no regex match issuer ^https://untrusted field origin exists field picture not exists ``` Supported match strategies are `exact` (default), `partial`, `prefix`, `suffix`, and `regex`; prefix with `no` for negative matches. Field aliases include `role`, `group`, and `groups` for `roles`; `issuer` for `iss`; `subject` for `sub`; `mail` for `email`; `scope` for `scopes`; `organization` for `org`; `address`, `ip`, and `ipv4` for `addr`; `http_method` for `method`; and `http_path` for `path`. Explicit actions must start with `allow` or `deny`, and may include `any`, `stop`, `log [debug|info|warn|error]`, `counter`, and `tag `. With multiple conditions, the default is match-all; add `any` to the action for match-any. A matched deny denies immediately. A matched allow grants access only if no later matching deny overrides it, unless `stop` is used. Selected v1.3.11 evaluates `acl default`/`match any` even when normalized user data omits `exp`. The typed-field reference owns the default-rule ordering regressions. Use `amr` to require verified methods, for example inside a policy: ```caddyfile acl rule { match role authp/user match amr hwk allow stop } ``` AMR is a list: `pwd` records password proof, `otp` records TOTP, and `hwk` records WebAuthn/U2F. `allow amr otp` is also a valid shortcut. Credential inventory and transform-added claims are not evidence that a factor was completed. The library stamps authoritative evidence after login; the Caddy challenge E2E verifies that forged transform AMR cannot satisfy a policy. Direct Basic/API-key proxy authentication also observes current portal/user challenge requirements. ## Policy Options Use `set auth url` for the login redirect target and `set forbidden url` for authorization failures: ```caddyfile set auth url /auth set forbidden url /forbidden set redirect query parameter redirect_url set redirect status 302 set user identity id set token sources header query cookie set session_id cookie name AUTHP_SESSION_ID set access_token cookie name AUTHP_ACCESS_TOKEN ALT_ACCESS_TOKEN ``` Cookie name settings map to `PolicyConfig.SessionIDCookieName` and `AccessTokenCookieNames`. Explicit access lists replace defaults. Caddy pins absent settings during runtime resolution so AuthCrunch cannot discover custom names from unrelated portals. Coordinate both names explicitly when a portal uses `set cookie name prefix PORTAL`; see [portal cookie precedence and policy coordination](../configuration-authentication-cookies/SKILL.md#coordinate-gatekeepers-explicitly). Session IDs are correlation values, not access credentials. Multiple access names belong on one line; empty names, duplicate names, repeated settings, and extra session-name arguments are rejected. `set auth url` must match where the referenced authentication portal is served. Use the same-host portal path such as `/auth` or `/xauth`, or the full URL for a split-host or root-mounted dedicated auth host. The HTTP integration route above owns mount selection and auth URL alignment. go-authcrunch v1.3.6 preserves the full application return URL over HTTP/1.1, HTTP/2 and HTTP/3, including authority/port, escaped path and raw query. The configured auth URL remains the outer destination, including direct portal OAuth callback URLs. Decode `redirect_url` once to inspect the return URL. An authority-looking path such as `//other.example/private` stays on the application origin. JavaScript redirects also preserve the browser fragment. The library classifies `RequestURI`, since HTTP/3 can populate an absolute `r.URL` for an origin-form request target. Keep this logic in AuthCrunch; do not rewrite Caddy request fields, build another redirect, or disable HTTP/3. Split-host completion still requires compatible access-token keys, cookie domain/path and an explicit trusted application return destination. A correct redirect does not relax the portal allowlist. Forwarded origin selection follows [Caddy edge trust](../configuration-http-integrations/references/edge-trust.md); separate forwarded port/prefix hints remain stripped. `set redirect status` accepts only 300 through 308. When `set forbidden url` is present, access-denied decisions redirect with status `303`; `{uri}`, `{http.request.uri}`, and `{url}` placeholders are replaced at request time. Use validation and behavior toggles deliberately: ```caddyfile validate bearer header validate method path validate path acl validate source address enable js redirect enable strip token enable login hint enable login hint with email phone enable additional scopes disable auth redirect query disable auth redirect ``` `validate method path` enables policy method/path evaluation without requiring a token path claim. `validate path acl` additionally requires token path claims. Token path claims use exact matching or `*` and `**` wildcards, not regular expressions. `*` matches one or more ASCII letters, digits, underscores, dots, tildes or hyphens; `**` also spans slashes. Punctuation is literal: `/tenant.v1/**` cannot grant `/tenantXv1/file`, and parentheses or `|` cannot expand a token's authority. This differs from explicit `regex match path` policy conditions. `validate source address` compares the token address claim to the request source address. `enable strip token` removes the accepted credential from its actual source: bearer/named header, Basic/API-key header, query or cookie. Unrelated request headers, query arguments and cookies remain. Token sources and validation still determine which credential can authorize the request. The selected go-authcrunch v1.3.6 checks every original, decoded and cleaned path interpretation whenever method/path or token path-claim validation is enabled. Every interpretation must satisfy the policy and any required claim; this also applies to cached identities. Cleaning must not turn `/admin/../public/file` into a new grant. Repeated encoding cannot hide a protected intermediate path before ending at an allowed path. The library considers cleaning before and after decoding, preserves trailing slashes, and allows at most four additional decoding passes after Go's initial URL parsing. Remaining encoded bytes at that limit, mixed valid/invalid escapes, invalid UTF-8 and initially encoded slashes fail closed. Encoded slashes are ambiguous because routers disagree about whether they delimit segments. Literal percent text such as `/public/100%25` remains usable when every interpretation is allowed. Query strings do not participate in path checks. These checks leave the request URL unchanged for downstream handlers. Keep `authorize` ahead of application rewrites or prefix stripping so it sees the original target; the library cannot recover a path that earlier middleware already discarded. Ordinary role-only policies do not enable path validation. For API key or basic auth proxying, configure a portal and realm: ```caddyfile with basic auth portal myportal realm local with api key auth portal myportal realm local with api key header name X-Api-Key with auth realm header name X-Auth-Realm ``` Basic/API-key auth is consulted after normal token sources fail. The request realm must match `with auth realm header name`, defaulting to `X-Auth-Realm`; failed Basic or API-key auth returns `401`. Client checks for Basic and API-key auth: ```bash curl -H 'X-Auth-Realm: local' --user 'jsmith:My@Password123' https://app.example.com/api/foo curl -H 'X-Auth-Realm: local' -H 'X-Api-Key: ' https://app.example.com/api/foo ``` If clients cannot send `X-Auth-Realm`, set a default before `authorize` with Caddy's `request_header` directive: ```caddyfile route /api/* { request_header +X-Auth-Realm "local" authorize with api_policy } ``` A malformed API key or failed Basic credential should return `401`. If the API key header name is wrong or absent, the policy may treat the request like an unauthenticated browser request and redirect to the auth URL unless `disable auth redirect` is set. For multiple realms, configure one `with basic auth portal ... realm ...` or `with api key auth portal ... realm ...` line per accepted realm and require clients to send the matching realm header. Bypass authorization only for paths that do not need authenticated user metadata: ```caddyfile bypass uri exact /healthz bypass uri prefix /assets/ bypass uri regex ^/public/.* ``` Bypass match types are `exact`, `partial`, `prefix`, `suffix`, and `regex`. The same decoding/cleaning checks above apply even without path-validation options: each interpretation must match some configured bypass rule. An ambiguous target receives normal authentication/authorization instead of a bypass. A bypass grants no authenticated identity or claim metadata. Inject claims only when an upstream explicitly expects them: ```caddyfile inject headers with claims inject header "X-User-Email" from email ``` `inject headers with claims` sets default `X-Token-*` headers for name, email, roles, and subject. Custom `inject header` entries map a header name to a claim field and are applied only after a user is authorized. Configured destination headers are cleared before authentication, including deny and bypass paths, so client-supplied identity values cannot survive as trusted claims. ## Direct OAuth Without a Portal A policy can own the external OAuth login/session flow without a portal, local store, or JWT key. It rejects JWT crypto and conflicting auth mechanisms. Read [direct OAuth configuration](references/direct-oauth.md) for provider selection, callback/logout routing, cookies, capacity, claims, and persistence. All callbacks and handled responses stay with the authorization handler; unauthenticated requests must not reach the protected upstream. ## Fixtures Use these examples: - `caddyfile_authz_test.go` for detailed ACL and misc behavior. - `testdata/caddyfile_adapt/testcase_authorize_ok.Caddyfile`. - `testdata/caddyfile_adapt/testcase_authenticate_with_oauth.Caddyfile`. `TestAuthzPathDelegation` checks the Caddy authentication provider's decisions, identity metadata and preservation of the original URL. `TestCaddyAuthorizationPathE2E` adapts policies and exercises real Caddy TLS over HTTP/1.1 and HTTP/2: bypasses, method/path rules, token path claims, cached identities, encoded traversal, invalid UTF-8 and concurrent literal wildcard grants. Denials assert that the downstream handler was never reached; successful requests retain their URI. `TestAuthzRedirectRequestTargets` exercises the actual authorization wrapper with origin-form, absolute-form and HTTP/3 request representations, both renderers and unchanged downstream request fields. `TestCaddyAuthorizationRedirectE2E` checks separate app/portal hosts over verified HTTP/1.1, HTTP/2 and UDP/QUIC HTTP/3, HEAD/GET redirects, local password and synthetic OAuth login, shared cookies and final resource authorization. Its Chrome journeys assert the negotiated protocol and execute JavaScript fragment redirects. The suite also retains untrusted-return rejection, custom/disabled queries, status selection and proxy trust. See [redirect qualification](../testing-and-ci/references/test-surfaces.md#authorization-login-redirects). ## Acceptance criteria - A valid token with the intended role reaches the protected handler; an invalid, expired, wrong-purpose, or denied token does not. Verify response behavior and downstream call counts, not just returned errors. - Path grants are checked before and after identity caching without rewriting the upstream request URI. `TestAuthzPathDelegation` and `TestCaddyAuthorizationPathE2E` cover this boundary. - A direct OAuth policy completes its callback through the same handler and rejects a replay or incompatible JWT setting. Session restart persistence is qualified separately under explicit root state, never inferred from a redirect.