---
name: configuration-authentication
description: "Configure authentication portals, backend selection, redirect trust, refresh, and portal wiring. Delegates cookies, UI, transforms, crypto, and OIDC provider details to focused skills."
---

# Configuration Authentication

## Purpose

Use this skill to configure `authentication portal <name>` blocks and the
route-level `authenticate with <portal>` handler.

Use [configuration-http-integrations](../configuration-http-integrations/SKILL.md)
to place portal routes, select matchers, wire same-host or split-host portals,
separate portal/protected routes, and check directive ordering.

Read these files when details matter:

- `caddyfile_authn.go` for the portal block.
- `caddyfile_authn_token_refresh.go` and [token refresh](references/token-refresh.md)
  for readable portal refresh configuration, explicit local realms, transports,
  bounded lifetimes and stores, cookies, placeholders and TLS validation.
- `caddyfile_authn_crypto.go` for crypto key directives.
- `caddyfile_authn_misc.go` for `enable`, `validate`, and `trust`.
- `caddyfile_authn_admin_api.go` and selected upstream
  `pkg/authn/admin_api/parser` for the independent admin/API key-export switches.
- `plugin_authn.go` for route-level `authenticate` syntax.
- `../go-authcrunch/config.go` for portal
  validation, default backend attachment, and user registration wiring.
- `../go-authcrunch/pkg/authn/config.go` and
  `../go-authcrunch/pkg/authn/portal.go` for
  portal defaults and runtime behavior.

Use focused repo-local skills for specialized portal sub-blocks:

- Use [configuration-authentication-cross-device](../configuration-authentication-cross-device/SKILL.md)
  to enable QR/link login, explicit approval, browser binding, cancellation and
  volatile request lifecycle through the existing portal route.
- Use [configuration-oauth-applications](../configuration-oauth-applications/SKILL.md)
  to configure portal `oidc provider` blocks, named client selection, private
  registrations, and dedicated provider signing keys.
  Its [provider reference](../configuration-oauth-applications/references/oidc-provider.md)
  covers explicit realm participation and separate issuers/cookie scopes across
  portals; attaching a store for portal login does not enable its realm for OIDC.
- Use [configuration-crypto](../configuration-crypto/SKILL.md) to configure
  portal `crypto` defaults, JWT signing keys, auto-generated keys, token names
  and lifetimes, secret-backed key material, and System API `system` keys.
- Use [configuration-authentication-cookies](../configuration-authentication-cookies/SKILL.md)
  to configure `cookie` directives and token-cookie naming.
- Use [configuration-authentication-ui](../configuration-authentication-ui/SKILL.md)
  to configure `ui` blocks, templates, static assets, custom CSS/JS/HTML, themes,
  languages, logos, and private links.
- Use [configuration-authentication-user-transforms](../configuration-authentication-user-transforms/SKILL.md)
  to configure `transform user` blocks, ACL matchers, typed claims, conditional
  challenge selection, additive legacy requirements, claim replacements, and
  transform UI links. Persisted local-user challenge rules belong to
  [configuration-users](../configuration-users/SKILL.md).
- Use [configuration-saml-providers](../configuration-saml-providers/SKILL.md)
  to configure `saml identity provider <name>` login providers enabled by the portal.
- Use [authentication-portal-api](../authentication-portal-api/SKILL.md) to build
  or troubleshoot JSON login, `/whoami`, `/beacon`, refresh token, and admin/server
  API interactions.

## Shape

```caddyfile
{
	security {
		local identity store localdb {
			realm local
			path assets/config/users.json
		}

		authentication portal myportal {
			crypto default token lifetime 3600
			crypto key sign-verify {env.JWT_SHARED_KEY}
			enable identity store localdb
		}
	}
}

example.com {
	@portal path /auth /auth/*
	route @portal {
		authenticate with myportal
	}
}
```

The portal name must match the `authenticate with <portal>` reference.
Route-level syntax also allows a matcher: `authenticate @matcher with
<portal>`.

Use `myportal` or a descriptive name such as `employee_portal` in examples,
fixtures, and tests. Avoid naming a portal `portal`: the repeated words in
`authentication portal portal` are confusing. Keep references consistent, for
example `authentication portal myportal` and `authenticate with myportal`.

## Portal Wiring

Add only the backends the portal should use:

```caddyfile
enable identity store localdb
enable identity provider github azure
enable sso provider aws
```

Define those stores, identity providers, or SSO app providers with the matching
domain skills before enabling them. `enable identity provider <name>` references
`oauth identity provider <name>` or `saml identity provider <name>` blocks;
`enable sso provider <name>` references `sso provider <name>` SSO app blocks.
Identity stores and identity providers can take multiple names on one line.

If a portal has no explicit identity stores and no explicit identity providers,
authcrunch currently attaches all configured identity stores and identity
providers during `Config.Validate()`. Prefer explicit `enable` lines in new
examples. After defaults and disabled-backend filtering, a portal must have at
least one identity store or identity provider; SSO providers are additional app
providers and do not satisfy the login-backend requirement by themselves.

User registration is global authcrunch config. A `user registration <name>`
block names its target identity store; authcrunch validates that store, marks it
registration-enabled, and attaches the registry to any portal that has that
identity store enabled. Do not generate an `enable user registration <name>`
portal line: the current `enable` parser does not accept it.

## Common Portal Options

Use crypto keys for token signing and verification:

```caddyfile
crypto default token lifetime 3600
crypto key sign-verify {env.JWT_SHARED_KEY}
```

Use both `enable source ip tracking` and `validate source address` when issued
tokens should carry and verify the source address. The first sets authcrunch
token grantor source-address tracking; the second makes the token validator
enforce the source-address claim.

Trusted redirect URI checks support login and logout redirect targets:

```caddyfile
trust login redirect uri domain exact example.com path prefix /app
trust logout redirect uri domain example.com path /
```

The match type is optional and defaults to `exact`; supported match types are
`exact`, `partial`, `prefix`, `suffix`, and `regex`. Both `domain` and `path`
need values. Keep `login`/`logout`, `redirect`, and `uri` as separate header
tokens. Quoted domain/path values remain data even when they contain those
words; they cannot change which redirect trust list receives the rule.

Enable admin/server API endpoints only when they are needed and protected by
an authenticated admin session:

```caddyfile
enable admin api
```

Both `enable` and `disable` are supported for `admin api` and
`admin api private key export`. Each setting occurs at most once in the portal;
both default to disabled. Key export does not implicitly enable the API and
requires both flags plus authenticated admin authorization at runtime.

See `authentication-portal-api` for `/api/server/metadata`,
`/api/server/realms`, `/api/server/info`, JSON login, `/beacon`, and `/whoami`
behavior. Admin API troubleshooting should check the directive, the active
portal session, and whether the user has an admin role before changing route
layout.

Portal access uses built-in role tiers. `authp/admin` grants administrative
portal capabilities, `authp/user` grants normal user settings/profile
capabilities, and `authp/guest` is the fallback portal-only role when neither
admin nor user roles are assigned. When debugging portal UI access, search
debug logs for configured portal access-list rules and inspect transforms that
add or drop `authp/*` roles.

## Fixtures

Use these fixtures as examples:

- `testdata/caddyfile_adapt/testcase_security_authentication_portal.Caddyfile`
- `testdata/caddyfile_adapt/testcase_authenticate_with_registration.Caddyfile`

`TestParseCaddyfileRedirectTrustMalformed` and
`TestParseCaddyfileRedirectTrustValues` cover incomplete selectors and quoted
values. `testcase_authenticate_with_redirect_trust_malformed` must fail adaptation
with a parser error, not a panic. The redirect-trust subtest in
`TestCaddyOAuthE2E` verifies separate login/logout behavior over TLS and confirms
that rejected reconfiguration leaves the running portal usable.

## Acceptance criteria

- A portal with explicitly selected, enabled backends serves login at its exact
  mount; a disabled or unknown backend is rejected rather than silently replaced.
- Trusted redirect rules retain their intended login/logout scope and matcher
  semantics after adaptation and runtime replacement.
- Refresh/OIDC participation is explicit per local realm. A portal-only syntax
  fixture does not qualify renewal, provider exchanges, or durable restart;
  those outcomes use the linked feature's Caddy unit and E2E evidence.