Use cases

Each card below maps to a runnable example under examples/ in the source repo. Examples build behind the example build tag so they don't bloat your go.sum or get pulled into go test ./...:

(cd examples/01-minimal && go run -tags example .)

Most pages start with the same decision shape:

• What problem this solves. The opening paragraphs explain the pressure that makes the feature useful, not just the option name.
• When to use it. Advanced pages call out the deployment shape where the feature earns its complexity.
• When not to use it. If a simpler built-in path is enough, the page points you there before diving into code.

If you are new to the library, start with Minimal OP, then Comprehensive bundle, and only jump to the pages below when your deployment has that specific need.

The reference application

Each numbered example isolates one option in 200–500 lines. sample/ is the other thing: the arc those examples skip, where an account has to come into existence before it can be used. It covers signup owned by the application, Argon2id password storage, login and consent through an interaction.Driver the application implements itself, TOTP enrolment from an account settings page, and a relying party completing the round-trip — on MySQL plus Redis joined by op/storeadapter/composite, under one docker compose up.

docker compose -f sample/compose.yaml up -d --build

Its consent page is a worked example of granular per-scope consent, which the bundled HTML driver deliberately does not offer. Treat it as a demonstration rather than a template: the schema is one embedder's model, signing and cookie keys are regenerated on every start, and it is not built to be hosted.

Index

Every example folder maps to one of the use-case pages below.

Bootstrap & wiring

Use case	Example	Page
Smallest possible OP	01-minimal	Minimal OP
Comprehensive bundle (every option a typical embedder uses)	02-bundle	Comprehensive bundle

Profile & flow

Use case	Example	Page
Declare OAuth 2.1 or legacy OIDC posture	00-security-profile	Declaring a security profile
Plain OAuth 2.0 alongside OIDC	04-oauth2-only	OAuth 2.0 (no openid)
FAPI 2.0 Baseline (PAR + JAR + DPoP)	03-fapi2	FAPI 2.0 Baseline
Service-to-service tokens	05-client-credentials	client_credentials
DPoP server nonce flow	51-dpop-nonce	DPoP nonce flow

UI

Use case	Example	Page
Drive UI from a SPA	16-custom-interaction, 10-react-login, 17-spa-composite-store	SPA / custom interaction
Custom HTML consent page	11-custom-consent-ui	Custom consent UI
Custom HTML account chooser	12-custom-chooser-ui	Custom chooser UI
Multi-account chooser (prompt=select_account)	13-multi-account	Multi-account chooser
Cross-origin SPA (CORS)	14-cors-spa	CORS for SPA
Locale negotiation	15-i18n-locale	i18n / locale

Storage

Use case	Example	Page
Persist on a real database	06-sql-store, 07-mysql-store	Persistent storage (SQL)
Persist on DynamoDB	18-dynamodb-store	DynamoDB storage
Rename SQL adapter tables	25-byo-table-names	Persistent storage (SQL) § Renaming the tables
Implement a store from scratch	26-byo-store-from-scratch	Bring your own store backend
Hot/cold split (Redis volatile)	08-composite-hot-cold, 09-redis-volatile	Hot/cold + Redis

Scopes & claims

Use case	Example	Page
Public / internal scope split	60-scopes-public-private	Public / internal scopes
OIDC §5.5 claims request parameter	61-claims-request	Claims request

Authentication

Use case	Example	Page
MFA, captcha, step-up	20-mfa-totp, 21-risk-based-mfa, 22-login-captcha, 23-step-up	MFA / step-up
Email OTP, recovery codes, or passkeys	28-email-otp-recovery, 29-passkey	MFA / step-up
Bring your own user store	24-byo-userstore	Bring your own user store

Advanced grants

Use case	Example	Page
Custom grant_type URN	30-custom-grant	Custom Grant
Device code (RFC 8628)	31-device-code-cli	Device Code
CIBA poll mode	32-ciba-pos	CIBA
Token Exchange (RFC 8693)	33-token-exchange-delegation	Token Exchange

Crypto & subjects

Use case	Example	Page
Pairwise subject (OIDC Core §8.1)	34-pairwise-saas	Pairwise subject
Encrypted id_token (JWE)	35-encrypted-id-token	JWE encryption

Governance

Use case	Example	Page
First-party consent skip	40-first-party-skip-consent	First-party consent skip
Dynamic Client Registration (RFC 7591)	41-dynamic-registration	Dynamic Client Registration
Back-Channel Logout 1.0	42-back-channel-logout	Back-Channel Logout

Operations

Use case	Example	Page
Prometheus metrics	52-prometheus-metrics	Prometheus metrics
FAPI TLS policy and public-JWKS loading	50-fapi-tls-jwks	FAPI 2.0 Baseline

Numeric inventory

The example folders are grouped by topic, not by chronology:

Band	Topic
00–09	bootstrap, core flows, profiles, storage adapters
10–19	UI and browser integration (SPA, consent, chooser, CORS, i18n)
20–29	MFA, authentication rules, and user-store projection
30–39	advanced grants, subject modes, encrypted tokens, federation
40–49	governance: first-party, DCR, back-channel logout
50–59	operations: FAPI helpers, metrics, tracing, DPoP nonce
60–69	scopes, claims, and compliance-adjacent examples

The README in the source repo is the authoritative inventory.