Authentication portal overview

An AuthCrunch portal signs people in and issues tokens describing their identity and roles. An authorization policy checks those tokens before a request reaches your application. A successful login establishes an identity; your policy decides whether that identity may use a particular application.

For a first working installation, follow the learning path. For the browser experience, see Using the portal.

How a request reaches your application

1. A browser requests a route protected by authorize with apppolicy.
2. The policy looks for a valid token. Without one, it sends the browser to its configured authentication URL.
3. The portal identifies the user through an attached store or provider, applies transforms, and completes the required login challenges.
4. The portal issues a signed access token, normally delivered in a browser cookie.
5. The browser requests the app again. The policy verifies the token and evaluates its access rules. Only an allowed request continues to the application's response or reverse proxy.

The first-app example makes this distinction visible: Alice and Bob can both sign in, but only Alice has the app/member role needed by the app. Bob receives 403.

Choose an identity source

Declare sources inside the global security block, then attach their names to an authentication portal. A source's realm identifies its login domain and appears in the resulting identity. A store name and a realm are different settings, even when you give them the same value.

Source	Credentials are checked by	Start here
Local store	AuthCrunch, using a file-backed user database	Local users
LDAP store	Your directory, including Active Directory	LDAP
OAuth / OpenID Connect provider	An external provider's sign-in flow	OAuth and OIDC
SAML provider	An external identity provider's SAML response	SAML

A portal can attach several sources. Require MFA for local accounts with portal challenges; configure upstream MFA at your external identity provider for federated accounts. Portal profile features such as local password and authenticator management do not change an external provider's account.

Connect configuration to routes

The global block defines named objects. Site handlers select those objects:

route {
    authenticate /auth/* with myportal

    @app path /app /app/*
    route @app {
        authorize with apppolicy
        reverse_proxy 127.0.0.1:8080
    }
}

This is a routing fragment: define myportal and apppolicy in the global security block, as the complete example demonstrates. The access check must run before the upstream handler. The app's own network address should not provide another public path around that check.

For a portal mounted at /auth/, its browser login is /auth/login, its applications page is /auth/portal, and its identity view is /auth/whoami. Provider callback URLs and cookie paths must match that mount.

Plan the session boundary

The portal's access token has its own lifetime and signing key; it is separate from an OAuth provider's token. A cookie must reach the protected host and path, and the policy must trust the portal's key. A role change does not rewrite an already issued token. Logout clears the portal browser session; upstream SSO and copies of a token require separate consideration.

For local accounts, optional refresh sessions can renew short-lived access tokens. Use trusted redirects to control where users return after login. Consult Troubleshoot when a successful login still leads to a loop or denied access.