Authorization policy syntax

Define a policy inside global security, then attach it to a site route with authorize with POLICY. The tables target the released Caddy bundle. Angle-bracket alternatives below describe grammar; they are not literal values to paste.

**Configuration declarations become active only through routes.** Global security contains named components. A site route selects a policy with authorize and places the application handler behind it. Adaptation validates configuration structure, provisioning resolves named components, and live requests exercise actual access decisions. The stages are different kinds of evidence.

Start with a complete boundary

{
    security {
        authorization policy apppolicy {
            set auth url https://auth.example.com/auth/
            crypto key verify from env AUTHCRUNCH_SIGNING_KEY
            allow roles app/member
        }
    }
}

app.example.com {
    route {
        authorize with apppolicy
        reverse_proxy 127.0.0.1:8080
    }
}

Configure the matching signer and portal separately, or use the complete first-app example. A policy requires at least one access rule; a verification key alone does not define who is allowed.

Credentials and verification

Directive	Meaning
`crypto key [ID] verify from env NAME`	HMAC secret in an environment variable
`crypto key [ID] verify from file PATH`	Supported public/private key file
`crypto key [ID] verify from directory PATH`	Key directory
`crypto key [ID] verify from env NAME as file`	Environment value names a key file
`crypto key [ID] verify from env NAME as directory`	Environment value names a key directory
`set token sources cookie header`	Allowed source order; values are cookie/header/query
`set access_token cookie name NAME [NAME...]`	Explicit accepted access cookie names
`set session_id cookie name NAME`	One session cookie name
`validate bearer header`	Recognize Bearer in the header source
`validate source address`	Require token/source address equality
`validate method path`	Evaluate method/path rules against checked request paths
`validate path acl`	Also check token-carried path grants

A System key uses crypto key ID system from file PATH for remote credential validation. It does not verify ordinary access JWTs. Keystore directives also support token name/lifetime configuration; match actual issued credentials and use the dedicated cookie/source settings for gatekeeper discovery.

Access rules

validate method path
acl rule {
    comment Members may read report paths
    match roles app/member
    match method GET
    prefix match path /reports/
    allow stop log debug
}

Form	Contract
`allow FIELD VALUES [with METHOD] [to PATH]`	Compact rule; path is substring matching
`deny FIELD VALUES [with METHOD] [to PATH]`	Compact deny
`[no] [exact	partial
`field FIELD [not] exists`	Presence/absence condition
`allow	deny [any] [stop] [counter] [log LEVEL] [tag VALUE]`
`acl default allow	deny`

Built-in matching fields are roles, amr, github_id, github_orgs, email, origin, name, realm, aud, scopes, org, jti, iss, sub, addr, method, and path. Aliases include role/group/groups, subject, issuer, audience, scope, organization, and address/ip/ipv4.

See ACL semantics, especially AND/OR, stop, duplicate fields, and the v1.3.8 match any/default-action limitation. Arbitrary typed custom fields are a newer feature, not released Caddy syntax.

Redirects and forwarding

Directive	Meaning
`set auth url URL`	Login destination
`set forbidden url URL`	303 destination for a denied authenticated identity
`disable auth redirect`	Refuse missing authentication with 401
`disable auth redirect query`	Omit return URL
`set redirect query parameter NAME`	Return-parameter name
`set redirect status CODE`	Accepted range 300–308; choose appropriate semantics
`enable js redirect`	Browser script redirect
`enable login hint [with VALIDATORS...]`	Forward a validated identifier hint
`enable additional scopes`	Forward client-selected OAuth scopes
`inject headers with claims`	Standard trusted identity headers
`inject header HEADER from FIELD`	Custom claim header; nested fields use `
`enable strip token`	Remove accepted credential from forwarded request
`set user identity email	subject
`bypass uri exact	partial

Other authentication modes

with basic auth portal myportal realm local
with api key auth portal myportal realm local
with api key header name X-Service-Key
with auth realm header name X-Account-Realm

A remote portal URL requires System keys. For a provider-backed opaque browser session, see the separate direct OAuth policy. These modes still require a deliberate application allow rule and do not automatically satisfy interactive MFA.

Agentic Prompts

Copy a prompt into your LLM to explore this topic. Each prompt prioritizes upstream repository guidance and code over this page, and asks for version-aware reasoning.

Read a policy from outside in

Help me understand Authorization policy syntax.

Primary authorities (take precedence over website documentation):
https://github.com/greenpau/caddy-security/blob/main/AGENTS.md
https://github.com/greenpau/caddy-security/tree/main/.codex/skills
https://github.com/greenpau/go-authcrunch/blob/main/AGENTS.md
https://github.com/greenpau/go-authcrunch/tree/main/.codex/skills
Read each repository's root AGENTS.md first, then any scoped AGENTS.md that
applies to inspected paths. Read the relevant SKILL.md files and follow their
implementation and test references.

Relevant skills to locate: configuration-authorization,
authorization-policy-acl.

Secondary reference:
https://docs.authcrunch.com/docs/authorize/syntax

If a source is inaccessible, ask me to paste its relevant text. Identify the
versions your answer applies to; main may be newer than my release. Resolve
disagreements using code and tests, and flag unverified claims. Use synthetic
credentials and redacted examples; explain proposed checks before any changes.

Explain the relationship between the global security block, a named policy,
and authorize on a route. Annotate a small existing policy and separate
grammar acceptance, provisioning, authentication, and access decisions. Ask
for my installed versions before selecting syntax.

Review rule grammar

Help me understand Authorization policy syntax.

Primary authorities (take precedence over website documentation):
https://github.com/greenpau/caddy-security/blob/main/AGENTS.md
https://github.com/greenpau/caddy-security/tree/main/.codex/skills
https://github.com/greenpau/go-authcrunch/blob/main/AGENTS.md
https://github.com/greenpau/go-authcrunch/tree/main/.codex/skills
Read each repository's root AGENTS.md first, then any scoped AGENTS.md that
applies to inspected paths. Read the relevant SKILL.md files and follow their
implementation and test references.

Relevant skills to locate: configuration-authorization,
authorization-policy-acl.

Secondary reference:
https://docs.authcrunch.com/docs/authorize/syntax

If a source is inaccessible, ask me to paste its relevant text. Identify the
versions your answer applies to; main may be newer than my release. Resolve
disagreements using code and tests, and flag unverified claims. Use synthetic
credentials and redacted examples; explain proposed checks before any changes.

Help me read compact and full ACL rules. Use synthetic roles and compare
exact/prefix matching with shortcut path matching. Explain action arguments,
condition combination, and stop behavior. Identify syntax or semantics that
differ between the downloadable bundle and newer source.

Diagnose adaptation versus runtime failure

Help me understand Authorization policy syntax.

Primary authorities (take precedence over website documentation):
https://github.com/greenpau/caddy-security/blob/main/AGENTS.md
https://github.com/greenpau/caddy-security/tree/main/.codex/skills
https://github.com/greenpau/go-authcrunch/blob/main/AGENTS.md
https://github.com/greenpau/go-authcrunch/tree/main/.codex/skills
Read each repository's root AGENTS.md first, then any scoped AGENTS.md that
applies to inspected paths. Read the relevant SKILL.md files and follow their
implementation and test references.

Relevant skills to locate: configuration-authorization,
authorization-policy-acl.

Secondary reference:
https://docs.authcrunch.com/docs/authorize/syntax

If a source is inaccessible, ask me to paste its relevant text. Identify the
versions your answer applies to; main may be newer than my release. Resolve
disagreements using code and tests, and flag unverified claims. Use synthetic
credentials and redacted examples; explain proposed checks before any changes.

Give me a staged diagnosis for a policy that adapts successfully but refuses
access. Separate missing access rules, wrong keys, credential sources, role
mismatch, and route mounting. Ask for redacted configuration and observed
status; do not infer login success from parser acceptance.

Design a policy test table

Help me understand Authorization policy syntax.

Primary authorities (take precedence over website documentation):
https://github.com/greenpau/caddy-security/blob/main/AGENTS.md
https://github.com/greenpau/caddy-security/tree/main/.codex/skills
https://github.com/greenpau/go-authcrunch/blob/main/AGENTS.md
https://github.com/greenpau/go-authcrunch/tree/main/.codex/skills
Read each repository's root AGENTS.md first, then any scoped AGENTS.md that
applies to inspected paths. Read the relevant SKILL.md files and follow their
implementation and test references.

Relevant skills to locate: configuration-authorization,
authorization-policy-acl.

Secondary reference:
https://docs.authcrunch.com/docs/authorize/syntax

If a source is inaccessible, ask me to paste its relevant text. Identify the
versions your answer applies to; main may be newer than my release. Resolve
disagreements using code and tests, and flag unverified claims. Use synthetic
credentials and redacted examples; explain proposed checks before any changes.

Build a test table for a read-only reports policy: allowed member GET,
nonmember, missing token, expired token, sibling path, and wrong method. For
each, identify the layer being tested and observable outcome. Keep
configuration checks separate from live requests.

Practice syntax review

Help me understand Authorization policy syntax.

Primary authorities (take precedence over website documentation):
https://github.com/greenpau/caddy-security/blob/main/AGENTS.md
https://github.com/greenpau/caddy-security/tree/main/.codex/skills
https://github.com/greenpau/go-authcrunch/blob/main/AGENTS.md
https://github.com/greenpau/go-authcrunch/tree/main/.codex/skills
Read each repository's root AGENTS.md first, then any scoped AGENTS.md that
applies to inspected paths. Read the relevant SKILL.md files and follow their
implementation and test references.

Relevant skills to locate: configuration-authorization,
authorization-policy-acl.

Secondary reference:
https://docs.authcrunch.com/docs/authorize/syntax

If a source is inaccessible, ask me to paste its relevant text. Identify the
versions your answer applies to; main may be newer than my release. Resolve
disagreements using code and tests, and flag unverified claims. Use synthetic
credentials and redacted examples; explain proposed checks before any changes.

Quiz me with five short policy fragments, one at a time. Include an action
with wrong arity, a broad shortcut path, misplaced proxy header, unsupported
custom field on an older release, and a missing allow rule. Wait for my
reasoning before explaining each correction.

Source Code References

Start with the code search, then follow the parser, runtime, and tests relevant to this topic. These links target main; use GitHub's branch/tag selector to compare them with your installed release.

Search this topic in both repositories — searches topic-specific symbols and paths across both codebases.
caddy-security: caddyfile_authz.go — dispatches authorization-policy subdirectives into library configuration.
caddy-security: caddyfile_authz_misc.go — parses source selection, validation, identity, and redirect options.
caddy-security: caddyfile_authz_acl.go — adapts full ACL rules, actions, defaults, and field declarations.
go-authcrunch: pkg/authz/config.go — defines and validates authorization-policy settings.
caddy-security: caddyfile_authz_test.go — checks policy grammar and adapted ACL/credential settings.

Start with a complete boundary​

Credentials and verification​

Access rules​

Redirects and forwarding​

Other authentication modes​

Agentic Prompts​

Source Code References​