ユースケース
以下の各ページは、ソースリポジトリの examples/ にある実行可能な例と対応しています。例は example build tag の背後でビルドされるので、go test ./... にも自分の go.sum にも入りません。
sh
(cd examples/01-minimal && GOWORK=off go run -tags example .)多くのページは、その機能が解決する問題から始めます。続けて、複雑さに見合う構成と、標準の仕組みで足りる場合を示します。
初めて読む場合は 最小構成の OP と RP のペア、次に 総合バンドル を確認し、自分の構成にその必要が出てきた段階で下の各ページへ進むのがおすすめです。トピックではなく、作りたいものからページを選ぶ場合はここから始めるを使ってください。
このセクションの読み進め方
リファレンスアプリケーション
番号付きの example は 1 つのオプションを 200 〜 500 行で切り出したものです。sample/ はそれとは別で、example が飛ばしている「アカウントが生まれてから使われるまで」の一連の流れを扱います。op/storeadapter/composite で束ねた MySQL + Redis の上で動き、docker compose up 一発で次の範囲を通しで試せます。
- アプリケーション側が持つサインアップ: アカウントの作成自体はアプリケーションの責務のままで、ライブラリの登録用の接続点(
LoginFlow.Registrationとprompt=create)に組み込みます - Argon2id によるパスワード保管
- アプリケーション自身が実装する
interaction.Driverを通したログインと同意 - アカウント設定画面からの TOTP 登録
- round-trip を完了する RP
sh
docker compose -f sample/compose.yaml up -d --buildCompose ファイルは OP と RP を 127.0.0.1 だけに公開します。サンプルは、アプリケーションが所有する POST 経路を double-submit 方式の CSRF トークンと Origin の確認で保護しています。パスワード変更と TOTP 登録の確定時には、op.VerifyPassword で現在のパスワードも確認します。これらの保護は OP の対話エンドポイントの外側にあり、アプリケーション側が担当します。
同意画面は scope 単位のきめ細かな同意の実装例になっています。これは同梱の HTML driver が意図的に提供していない部分です。ただしテンプレートではなくデモとして扱ってください。スキーマはあくまで一組み込み側のモデルで、署名鍵と cookie 鍵は起動のたびに再生成され、公開ホスティングを想定した作りにもなっていません。
一覧
各 example フォルダはいずれかのページに対応しています。
起動と組み込み
| ユースケース | 例 | ページ |
|---|---|---|
| 最小 OP | 01-minimal | 最小構成の OP と RP のペア |
| 典型的な option をまとめた構成 | 02-bundle | 総合バンドル |
プロファイルとフロー
| ユースケース | 例 | ページ |
|---|---|---|
| OAuth 2.1 または既存 OIDC の姿勢を宣言 | 00-security-profile | セキュリティプロファイルの宣言 |
| OIDC と並走する純粋 OAuth 2.0 | 04-oauth2-only | OAuth 2.0（openid なし） |
| FAPI 2.0 Baseline（ライブラリの PAR + JAR + DPoP 既定値） | 03-fapi2 | FAPI 2.0 Baseline |
| FAPI 2.0 Message Signing（署名付きリクエスト、JARM、署名付き introspection、DPoP nonce source） | 54-fapi2-message-signing。nonce のやり取りは 51-dpop-nonce | FAPI 2.0 Message Signing |
TLS を終端するプロキシの背後で、証明書に結び付いたトークンを使う FAPI 2.0（WithMTLSProxy + WithTrustedProxies） | 55-mtls-proxy | FAPI 2.0 Baseline |
ネイティブアプリ: public クライアント、PKCE、loopback 127.0.0.1 の redirect | 38-native-app | 構成を選ぶ |
| サービス間通信用のトークン | 05-client-credentials | サービス間（client_credentials） |
| 事前登録なしで、HTTPS URL で名乗る MCP クライアントを受け入れる | なし | MCP 認可サーバ |
| DPoP のサーバ nonce フロー | 51-dpop-nonce | DPoP nonce |
OP のトークンで API（op/rs）を守り、ルートごとにマウントする | 36-resource-server | API を守る |
| OP が守る API の protected resource メタデータ（RFC 9728）を公開する | なし | Protected resource メタデータ |
UI
| ユースケース | 例 | ページ |
|---|---|---|
| 組み込み HTML のログイン・同意・アカウント選択 | 19-default-ui | UI の方式を選ぶ |
| SPA から UI を扱う | 16-custom-interaction、10-react-login、17-spa-composite-store | SPA / 対話画面のカスタマイズ |
| カスタム HTML サインイン画面 | 37-custom-login-ui | カスタムログイン UI |
| カスタム HTML 同意画面 | 11-custom-consent-ui | カスタム同意 UI |
| カスタム HTML アカウント選択 | 12-custom-chooser-ui | カスタムアカウント選択 UI |
マルチアカウント選択（prompt=select_account） | 13-multi-account | マルチアカウント選択 |
| クロスオリジン SPA (CORS) | 14-cors-spa | SPA 向け CORS |
| ロケール解決 | 15-i18n-locale | i18n / ロケール |
ストレージ
| ユースケース | 例 | ページ |
|---|---|---|
| 実 DB に永続化 | 06-sql-store、07-mysql-store | SQL ストア |
| DynamoDB に永続化 | 18-dynamodb-store | DynamoDB ストア |
| SQL アダプタのテーブル名を差し替える | 25-byo-table-names | SQL ストア § テーブル名を差し替える |
| ストアをゼロから実装する | 26-byo-store-from-scratch | ストアバックエンドを自前実装する |
| Hot / Cold 分離（Redis 揮発） | 08-composite-hot-cold、09-redis-volatile | Hot / Cold 分離 |
| SQL、DynamoDB、Redis の Hot / Cold 分離、自前ストアから選ぶ | なし | ストレージ構成の選び方 |
スコープ / claim
| ユースケース | 例 | ページ |
|---|---|---|
| Public / Internal スコープ分離 | 60-scopes-public-private | Public / Internal スコープ |
| OIDC §5.5 claims リクエスト | 61-claims-request | Claims リクエスト |
| Rich authorization requests（RFC 9396） | なし | Rich authorization requests |
認証
| ユースケース | 例 | ページ |
|---|---|---|
| MFA、captcha、ステップアップ | 20-mfa-totp、21-risk-based-mfa、22-login-captcha、23-step-up | MFA / ステップアップ |
| MFA 要素を本体と同じ DB に永続化 | 27-durable-mfa-store | MFA / ステップアップ |
| Email OTP、recovery code | 28-email-otp-recovery | MFA / ステップアップ |
| パスワードの代わりに passkey でサインイン | 29-passkey | パスワードレス passkey |
| 既存ユーザストアの投影 | 24-byo-userstore | 既存ユーザストアの投影 |
| bcrypt のパスワードハッシュをログイン時に argon2id へ移行 | 53-production-sql | bcrypt パスワードの移行 |
直近のサインインを要求するアカウントページ（max_age、rs.RequireMaxAge） | なし | アカウントページ |
拡張グラント
| ユースケース | 例 | ページ |
|---|---|---|
| カスタム grant_type URN | 30-custom-grant | カスタム grant |
| Device Code (RFC 8628) | 31-device-code-cli | Device Code |
| CIBA ポーリング方式 | 32-ciba-pos | CIBA |
| トークン交換（RFC 8693） | 33-token-exchange-delegation | トークン交換 |
| 信頼するパートナーの署名付き assertion を access token と引き換える（RFC 7523） | なし | JWT bearer grant |
| 組織をまたぐアイデンティティチェーン: ID-JAG の発行と引き換え（experimental） | なし | ID-JAG |
| クライアントが id で参照・マージ・失効できる長命な grant | なし | Grant management |
暗号と subject
| ユースケース | 例 | ページ |
|---|---|---|
| Pairwise subject（OIDC Core §8.1） | 34-pairwise-saas | Pairwise subject |
| 暗号化 id_token（JWE） | 35-encrypted-id-token | JWE 暗号化 |
ガバナンス
| ユースケース | 例 | ページ |
|---|---|---|
| ファーストパーティ同意スキップ | 40-first-party-skip-consent | ファーストパーティ同意スキップ |
| 動的クライアント登録（RFC 7591） | 41-dynamic-registration | 動的クライアント登録 |
| Back-Channel Logout 1.0 | 42-back-channel-logout | バックチャネルログアウト |
| RP の登録・更新・削除: 静的 seed とコード上の差し込み口 | 53-production-sql | クライアントオンボーディングのパターン |
運用
| ユースケース | 例 | ページ |
|---|---|---|
| Prometheus メトリクス | 52-prometheus-metrics | Prometheus メトリクス |
| FAPI TLS ポリシーと public JWKS の読み込み | 50-fapi-tls-jwks | FAPI 2.0 Baseline |
番号体系
例フォルダは、書かれた順ではなくトピック別に分けています。
| 帯 | トピック |
|---|---|
| 00–09 | 基本構成、コアフロー、プロファイル、ストレージアダプタ |
| 10–19 | UI とブラウザ統合（SPA、同意、アカウント選択、CORS、i18n） |
| 20–29 | MFA、認証ルール、ユーザストアの投影 |
| 30–39 | 拡張グラント、subject mode、暗号化トークン、ID 連携、リソースサーバ。37 は UI のあふれ分 |
| 40–49 | ガバナンス: ファーストパーティ、動的登録、バックチャネルログアウト |
| 50–59 | 運用: FAPI ヘルパ、メトリクス、トレーシング、DPoP nonce |
| 60–69 | scope、claim、適合性に近い example |
ソースリポジトリの README が一次インベントリです。