Configuration Authorization

Configuration Authorization

Purpose

Use this skill to configure authorization policy <name> blocks and the route-level authorize [<matcher>] with <policy> handler.

Use configuration-http-integrations to place protected routes, select matchers, wire same-host or split-host applications, and check directive ordering.

Use configuration-crypto 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

{
	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 <policy> 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 <token> parsing but is not itself a token source name.

ACLs

Read typed custom ACL fields 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:

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 <field> <values...> becomes allow log debug; it does not stop later rules.
• deny <field> <values...> becomes deny stop log warn.
• <field> any or <field> * becomes field <field> exists.
• with <method> to <path> 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:

acl rule {
	comment allow users
	match role authp/user
	allow stop log info
}

acl default deny

Explicit rule conditions use go-authcrunch ACL grammar:

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

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:

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

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.