Reference
Use these pages when you know which setting or interface you need. For a complete working example, start with Protect your first app.
Navigate by the behavior you need to understand. These are documentation choices rather than a runtime sequence. Start with the task, then follow the linked references on this page. Login sources, application permission, credential lifecycle, management callers, and executable evidence have different owners even when they share one security configuration.
Caddyfile configuration
AuthCrunch's named stores, portals, and policies belong inside the global
security block. The authenticate and authorize handlers connect them to
routes in a site block.
| Area | Reference |
|---|---|
| Portal configuration | First portal configuration |
| Local identities | Identity store and static users |
| OAuth / OIDC identity providers | Provider settings and endpoint configuration |
| Upstream token trust | Issuer/audience, static pins and JWKS rollover |
| SAML login | Browser-bound flow and pinned signing trust |
| Service credentials and delivery | Secret references and messaging limits |
| User mapping | Transforms |
| Login requirements | Authentication challenges |
| Policy syntax | Authorization syntax |
| Access rules | Roles and claims and paths |
| Request identity | Headers and placeholders |
For Caddy itself, use the official Caddyfile concepts
and route reference.
Handler order determines whether an access check runs before the application.
Tokens and cookies
- Cookie settings
- Token discovery
- Token verification
- Generate an ECDSA key
- Logout
- Refresh sessions
- Persistent runtime state
Application sign-in models
- Direct OAuth authorization for provider sign-in without a portal.
- AuthCrunch as an OpenID Provider for relying applications using local accounts.
Use Applications and SSO to distinguish these models from upstream SAML login and the incomplete AWS SAML assertion flow.
APIs
Begin with the API overview, then select the interface that matches your caller:
API permissions and authentication requirements are endpoint-specific. A portal login alone does not establish administrative API access.
Management commands
Use the bundled local management CLI to inspect stores, administer accounts through an enabled Server API, and generate credentials offline. Client YAML and server Caddyfile configuration are separate.
Executable and versions
The bundled executable is named authcrunch; a custom Caddy build may be named
caddy. Use the actual executable path when running these commands:
./bin/authcrunch version
./bin/authcrunch security version
./bin/authcrunch list-modules
./bin/authcrunch security --help
version reports Caddy's version; security version reports the AuthCrunch
library version. The installation guide identifies the
bundle used in the learning path. Check the
release notes before
using configuration from a different version.
See Feature availability and versions for the distinction between the released integration and newer library features, and Authentication logging for diagnostic controls.
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.
Choose the right reference family
Help me understand Reference.
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, configuration-authorization,
authentication-portal-api.
Secondary reference:
https://docs.authcrunch.com/docs/reference
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.
Ask me what I am trying to accomplish, who the caller is, and which executable
versions I run. Map the task to named stores/providers, a portal, an
authorization policy, an application protocol, or a specific API family.
Explain why similar names can describe different directions of trust.
Trace a setting through three layers
Help me understand Reference.
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, configuration-authorization,
authentication-portal-api.
Secondary reference:
https://docs.authcrunch.com/docs/reference
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.
Choose one directive and follow its Caddy adapter, library configuration
validation, runtime consumer, and focused tests. Explain what adaptation
proves, what provisioning proves, and what needs a live request. Compare my
installed tag with main before recommending the setting.
Read a complete configuration graph
Help me understand Reference.
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, configuration-authorization,
authentication-portal-api.
Secondary reference:
https://docs.authcrunch.com/docs/reference
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.
Annotate a synthetic global security block and its site routes. Trace
named-component references, authenticate/authorize handler mounting, and the
application handler order. Identify dangling names and a route that bypasses
the policy without treating a table of settings as a complete working example.
Match an API to its caller
Help me understand Reference.
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, configuration-authorization,
authentication-portal-api.
Secondary reference:
https://docs.authcrunch.com/docs/reference
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.
Compare browser identity probes, Profile operations, Server administration,
encrypted System authentication, the Go client, and downstream OIDC token
endpoints. Explain authentication transport, live-session requirements, and
independent admin/export switches. Do not carry a permission or credential
assumption from one API family to another.
Navigate a thematic investigation
Help me understand Reference.
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, configuration-authorization,
authentication-portal-api.
Secondary reference:
https://docs.authcrunch.com/docs/reference
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.
For an intermittent sign-in problem, guide me through versions,
callback/cookie scope, token discovery, verification, roles, current account
state, logging, and persistence. Ask for one redacted observable at a time.
Provide a short source-backed explanation and a teach-back question instead of
a list of unrelated configuration changes.
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.go — registers global security configuration and route directive adapters.
- caddy-security: caddyfile_adapt_test.go — checks complete Caddyfile fixtures against expected adapted configuration.
- go-authcrunch: config.go — validates the library configuration graph and named components.
- go-authcrunch: server.go — constructs the runtime and delegates named portal and policy requests.
- caddy-security: caddyfile_authn.go — dispatches authentication-portal configuration.
- caddy-security: caddyfile_authz.go — dispatches authorization-policy subdirectives into library configuration.
- go-authcrunch: pkg/authn/respond_api.go — dispatches API routes and enforces admin enablement and role checks.