Example configs

Self-contained, copy-pasteable YAML for each IIIF Auth 2.0 interaction pattern × access-service backend combination iiiris supports. Drop one into your iiirisd config (or include it as a partial alongside the rest of your YAML), edit the rule prefixes and credentials, restart, and iiiris will gate identifiers accordingly.

For the full schema and field-by-field reference, see ../configuration.md. For the design rationale and the four-pattern × four-backend matrix, see ../iiif-auth.md.

Pick by pattern

File	Pattern	Backend	Use when
auth-clickthrough.yaml	clickthrough	builtin	The viewer asserts something (terms of use, content warning) before getting access. No user identity captured.
auth-active-htpasswd.yaml	active	builtin (htpasswd file)	Username/password login against an htpasswd file on disk. Mtime-watched; add/remove users without restart. The right choice for most "active" deployments.
auth-active-inline.yaml	active	builtin (inline YAML)	Same as above but credentials inlined in YAML. For a handful of staff accounts; changes require a config reload.
auth-kiosk.yaml	kiosk	builtin	Automatic, no-UI access for clients whose IP is on an allowlist. Reading rooms, managed kiosks, conference networks.
auth-header.yaml	external	header	A reverse proxy (oauth2-proxy, Pomerium, Authelia, Cloudflare Access, Tailscale) has already authenticated the user and forwards the identity as a header.
auth-external.yaml	external	external	An operator-hosted auth service redirects back to iiiris with an HMAC-signed query string. The custom-logic path.
auth-oidc.yaml	external	oidc	A first-class OpenID Connect client. Okta, Auth0, Keycloak, Authentik, your campus IdP — anything OIDC-compliant.

Pick by deployment shape

• Single-instance, persistent sessions: any of the above works. For session persistence across restarts, add auth.session.backend: filesystem (or s3) — see ../iiif-auth.md.
• Multi-replica: use auth.session.backend: redis. None of these examples set the session backend (they default to heap, in-memory); add the Redis block when you go horizontal.
• Mixed: nothing stops you from defining multiple profiles in one config and binding different identifier prefixes to each. See tools/iiif-auth-conformance/config.yaml for a four-profile example used by CI.

Things every example assumes you'll change

• server.addr / sources.filesystem.root — set to whatever your deployment actually uses.
• Rule prefixes (restricted/*, staff/*, etc.) — match your identifier scheme.
• cors.token_origins — list the viewer origins that legitimately request tokens. Leaving this empty breaks the cross-origin viewer flow.
• Any _env references (e.g. callback_secret_env, client_secret_env) — make sure the named env vars are set in the iiirisd process environment. Empty env vars are a build error.

Where these are tested

The four interactive patterns (clickthrough, active, kiosk, header) are exercised end-to-end by tools/iiif-auth-conformance in CI — see the harness's README. external (signed callback) and oidc are covered by unit and integration tests in internal/auth/service/; CI doesn't drive them end-to-end because each needs an operator-hosted upstream.