Start here
AuthCrunch adds authentication and authorization to Caddy through the
caddy-security module. It can give users a place to sign in and check whether
their identity allows them to reach an application.
Authentication answers “Who is this user?” Authorization answers “May this user access this resource?” A successful login does not automatically grant access to every application.
Build your first setup
Start with two local users and a protected page. You do not need a domain, an external identity provider, or another application server. By the end, you will have tested a successful login, allowed access, denied access, and logout.
- Install and verify. Get a Caddy build that includes AuthCrunch.
- Protect your first app. Run a local portal and connect it to an access policy.
- Verify access. Check both users, then narrow the policy to test denied access.
- Choose your next step. Connect a provider or prepare a deployment.
The walkthrough uses the published AuthCrunch v1.5.0 distribution, containing caddy-security v1.5.0 and go-authcrunch v1.4.1. The distribution combines the Caddy security app and associated plugins into a ready-to-run executable. The library and integration have separate versions. See the distribution release and backend/module choices.
Understand the moving parts
| Part | What it does | Name in the walkthrough |
|---|---|---|
security | Defines the stores, portals, and policies in Caddy's global options | One shared block |
| Identity store | Holds users and checks their credentials | localdb |
| Authentication portal | Provides login pages and issues an access token | myportal at /auth/ |
| Authorization policy | Verifies the token and evaluates access rules | apppolicy |
| Protected route | Runs the policy before serving the application | / and its application paths |
An external identity provider can replace the local login source. The application still needs an authorization decision before its response reaches the user.
Choose a login model
Use the portal model for the learning path. The other models serve different integration needs; their session and configuration settings are not interchangeable.
| Model | Use it when… | How access works |
|---|---|---|
| Portal and token policy | You want a login portal, local users, or portal MFA and profile pages | The portal issues a token; a policy checks the token on the protected route |
| Direct OAuth policy | You want an application's policy to send users directly to an external provider | The policy handles the provider callback and creates its own session; portal user transforms do not apply |
| AuthCrunch as an OIDC provider | Your application is an OIDC client and needs AuthCrunch to supply identity | The application participates in an OIDC authorization flow; this is a separate integration from putting a policy in front of a route |
Begin with Install and verify. If you already have a working deployment, browse the guides by topic or go to the reference.