go-oidc-provider

日本語

English

日本語

English

Appearance

Options 索引 ​

op.New に渡せる公開オプションを、触る対象のレイヤごとに分類しました。先頭の 4 つは構築時に必須で、それ以外はデフォルトを上書きする任意オプションです。

このページの読み方

オプション名のリンクから詳細ページに飛べます。「セクション」列は、そのオプションが動かす discovery / endpoint の表面です。「デフォルト」が空欄のオプションは組み込みの初期値を持っておらず、明示的に渡したときだけ機能が有効になります。

どのオプションが必要か ​

このページは、op.New に渡せる公開オプションを並べた索引です。70 以上のオプションがあるため、目的が決まった状態で表を眺めると目当てが探しにくいことがあります。下の決定木で関連するエリアを当てたうえで、表の対応セクションに飛んでください。

  • これから新規に OP を立ち上げる → まず必須の 4 つ: WithIssuer、WithStore、WithKeyset、WithCookieKeys。詳しくは必須オプション と最小 OP の組み立て。
  • FAPI 2.0 を 1 行で有効にしたい → WithProfile(profile.FAPI2Baseline)(または profile.FAPI2MessageSigning、profile.FAPICIBA)。プロファイルは mTLS が明示されていなければ DPoP を既定選択します。profile.IGovHigh は予約値で、現時点では拒否されます。ユースケース: FAPI 2.0 Baseline、ガイド: FAPI を参照。
  • プロファイル全体ではなく、機能を 1 つだけ有効にしたい → WithFeature(feature.PAR) / JAR / JARM / DPoP / MTLS / Introspect / Revoke。PKCE は標準で有効です。Dynamic Registration、RAR、Grant Management は追加設定が必要なので、それぞれ専用オプションから有効化します。
  • /token で受け付ける grant の集合を絞りたい → WithGrants(grant.AuthorizationCode, grant.RefreshToken, grant.ClientCredentials, grant.DeviceCode, grant.CIBA)。WithDeviceCodeGrant() / WithCIBA(...) / WithCustomGrant(...) / RegisterTokenExchange(...) は、それぞれ追加で必要なエンドポイントもまとめてマウントします。
  • 送信者制約付きのアクセストークンにしたい → DPoP 系: WithFeature(feature.DPoP) + 必要に応じて WithDPoPNonceSource(op.NewInMemoryDPoPNonceSource(...))。mTLS 系: WithFeature(feature.MTLS) + 必要に応じて WithMTLSProxy(headerName, trustedCIDRs)。詳しくはガイド: 送信者制約付きトークン、DPoP、mTLS、ユースケース: DPoP nonce。
  • アクセストークンを JWT / opaque で切り替えたい → OP 全体の既定は WithAccessTokenFormat(...)、RFC 8707 リソースごとに分けたいときは WithAccessTokenFormatPerAudience(...)。ガイド: アクセストークンの形式 を参照。
  • sector ごとに pairwise sub にしたい → WithPairwiseSubject(salt)(32 byte 以上の salt)。ユースケース: pairwise subject を参照。
  • 起動時にクライアントを静的に投入したい → WithStaticClients(op.PublicClient(...), op.ConfidentialClient(...), op.PrivateKeyJWTClient(...))。ガイド: クライアントの種類 を参照。
  • Dynamic Client Registration を使いたい → WithDynamicRegistration(...)。ユースケース: Dynamic Client Registration を参照。
  • introspection / revocation エンドポイントを公開したい → WithFeature(feature.Introspect) および / または WithFeature(feature.Revoke)。細かな調整は下の「プロファイル / feature / grant」表を参照。
  • scope カタログを拡張したい → discovery に出す scope は WithScope(op.PublicScope("name", "label"))、内部用は WithScope(op.InternalScope("name"))。ガイド: scope と claim、ユースケース: scope を参照。
  • 独自の grant_type を生やしたい → WithCustomGrant(handler)。ユースケース: custom grant を参照。
  • i18n(国際化)対応をしたい → WithDefaultLocale(...)、WithLocale(bundle)、WithPreferredLocaleStore(...)。ユースケース: i18n を参照。
  • id_token / userinfo / JARM / introspection を JWE で暗号化したい → WithEncryptionKeyset(...) と、必要なら既定許可リストを狭める WithSupportedEncryptionAlgs(algs, encs)。ユースケース: JWE 暗号化 を参照。
  • SPA クライアント向けに CORS を開けたい → WithCORSOrigins(...)。ユースケース: SPA 向け CORS を参照。
  • Prometheus メトリクスを出したい → WithPrometheus(registry)。ライブラリは /metrics をマウントしないため、ハンドラの公開はルーター側で行います。ユースケース: Prometheus メトリクス を参照。
  • 監査ログをアプリログとは別の sink に流したい → WithAuditLogger(*slog.Logger)。Audit イベントカタログ を参照。
  • SPA 向けに対話レイヤをまるごと差し替えたい → WithInteractionDriver(interaction.Driver)。ユースケース: SPA 向け対話のカスタマイズ を参照。

必須(op.New がこの 4 つ無しでは起動を拒否します) ​

Option値セクションデフォルト
WithIssuerstringdiscovery issuer / JWT iss / cookie scope—
WithStoreop.Storeすべての永続サブストア—
WithKeysetop.Keyset(P-256 / ES256)JWKS / JWS 署名—
WithCookieKeys32 byte の鍵session / CSRF cookie の AES-256-GCM—

プロファイル / feature / grant ​

Option値セクションデフォルト
WithProfileprofile.Profileセキュリティプロファイルを 1 行で有効化(FAPI 2.0 Baseline / Message Signing / FAPI-CIBA)。プロファイルが DPoP-or-mTLS を要求し、mTLS が明示されていなければ DPoP を既定の送信者制約方式として選択。profile.IGovHigh は v2+ 向けの予約で、ランタイム制約が未着地のため op.New が拒否。なし
WithFeaturefeature.Flag(1 呼び出しで 1 つ、繰り返し可)PAR / DPoP / mTLS / JAR / JARM / introspect / revoke を個別に有効化控えめなデフォルト
WithGrants...grant.Type(可変長)/token で受け付ける grant を限定authorization_code、refresh_token
WithScopeop.Scope(1 呼び出しで 1 つ。op.PublicScope / op.InternalScope コンストラクタを利用)scope カタログを拡張openid、profile、email、address、phone、offline_access
WithOpenIDScopeOptional(引数なし)OAuth 2.0 単独(scope に openid を含まない)を許容openid 必須
WithStrictOfflineAccess(引数なし)refresh_token の発行を offline_access の同意取得時に限定緩い既定(openid が付与されれば発行)

クライアント / 登録 ​

Option値セクションデフォルト
WithStaticClients...op.ClientSeed(op.PublicClient / op.ConfidentialClient / op.PrivateKeyJWTClient を渡す)起動時にクライアントレジストリを初期投入空
WithFirstPartyClients...string(client ID)ファーストパーティ同意スキップの対象なし
WithDynamicRegistrationop.RegistrationOption/register をマウント(RFC 7591 / 7592)無効

認証 / LoginFlow ​

Option値セクションデフォルト
WithLoginFlowop.LoginFlowStep + Rule の宣言的 DAG(推奨)なし
WithAuthenticators...op.Authenticator(可変長)低レイヤ API(WithLoginFlow とは排他)なし
WithInteractionDriverinteraction.Driver対話レイヤのトランスポート全体を差し替え(HTML ドライバ / SPA ドライバ / 独自実装)同梱の HTML ドライバ
WithInteractions...op.Interaction(可変長)ドライバの上に重ねる非クレデンシャルプロンプト(T&C、KYC など)consent のみ
WithCaptchaVerifierop.CaptchaVerifierStepCaptcha の上流 captcha プロバイダなし
WithRiskAssessorop.RiskAssessorRuleRisk と LoginContext.RiskScore の供給元なし
WithLoginAttemptObserverop.LoginAttemptObserverRuleAfterFailedAttempts 用の失敗回数集計なし
WithMFAEncryptionKeys32 byte の鍵TOTP シークレットを AES-256-GCM で保存時暗号化なし
WithAuthnLockoutStoreop.AuthnLockoutStoreRuleAfterFailedAttempts が参照する subject 単位の失敗回数を永続化in-memory
WithACRPolicyop.ACRPolicy(interface)ステップアップの acr / aal マッピングidentity

UI ​

Option値セクションデフォルト
WithSPAUIop.SPAUI(構造体: LoginMount / ConsentMount / LogoutMount / StaticDir)SPA の入口と静的アセット一式を OP 側でマウントし、interaction の状態も JSON で提供無効
WithConsentUIop.ConsentUI(*html/template.Template をラップ)同意画面を組み込み側テンプレートで描画。state / CSRF / 永続化は OP が担当同梱テンプレート
WithChooserUIop.ChooserUI(*html/template.Template をラップ)prompt=select_account を組み込み側テンプレートで描画同梱テンプレート
WithCORSOrigins...string厳格 CORS の許可リスト(未指定なら redirect URI から自動導出)自動導出
WithDefaultLocaleop.Locale(BCP 47 タグ)ui_locales が無いリクエスト時の既定ロケール"en"
WithLocaleop.LocaleBundle(1 呼び出しで 1 つ、繰り返し可)同梱 HTML ドライバ用のロケール別メッセージバンドルを登録英語 + 日本語の初期バンドル
WithPreferredLocaleStoreop.PreferredLocaleStore§L.2 優先順序の先頭で参照されるユーザ単位ロケール上書きなし

WithSPAUI と WithConsentUI は相互排他です。どちらも同意画面の描画を受け持つためです。WithChooserUI は WithSPAUI と同時指定できますが、SPA モードではアカウント選択も JSON の状態取得を通じて SPA が描画します。そのため chooser テンプレートは使われず、op.New が構造化された警告を出します。詳細は カスタムアカウントチューザ UI を参照してください。

トークン ​

Option値セクションデフォルト
WithAccessTokenFormatop.AccessTokenFormat(AccessTokenFormatJWT / AccessTokenFormatOpaque)OP 全体で JWT / opaque を選択JWT
WithAccessTokenFormatPerAudiencemap[string]op.AccessTokenFormat(RFC 8707 リソース → 形式)audience ごとに形式を切り替えOP 全体の値
WithAccessTokenRevocationStrategyop.AccessTokenRevocationStrategy(RevocationStrategyGrantTombstone / RevocationStrategyJTIRegistry / RevocationStrategyNone)発行済 JWT アクセストークンの失効ポリシー。既定の GrantTombstone は Store.GrantRevocations()、JTIRegistry は Store.AccessTokens() を必須とし、いずれも op.New で検査されるgrant tombstone
WithAccessTokenTTLtime.Durationアクセストークンの寿命5 分
WithRefreshTokenTTLtime.Duration通常のリフレッシュトークンの寿命30 日
WithRefreshTokenOfflineTTLtime.Durationoffline_access が付与されたときのリフレッシュトークンの寿命WithRefreshTokenTTL を継承(ゼロ値で延長しない)
WithRefreshGracePeriodtime.Duration(0 で無効化、負値は拒否)ローテーション後の猶予期間60 秒
WithDPoPNonceSourceop.DPoPNonceSource(interface)サーバ供給の DPoP nonce ストア(op.NewInMemoryDPoPNonceSource が同梱実装)なし

WithInMemoryDPoPNonceLogger は op.New ではなく op.NewInMemoryDPoPNonceSource に渡す補助オプションです。同梱の in-memory nonce source を使う場合だけ指定します。

Discovery / endpoint ​

Option値セクションデフォルト
WithEndpointsop.Endpoints(構造体: 各エンドポイントのパス上書き)各エンドポイントのパスを上書き仕様の既定
WithMountPrefixstring(/ で始める。ルートに置くなら /)issuer 直下にプリフィックスを設けてマウント/oidc
WithClaimsSupported...string(可変長)discovery の claims_supported を埋める省略
WithClaimsParameterSupportedboolclaims_parameter_supported を切り替える。false の場合、authorize / PAR は malformed JSON の拒否後に claims payload を無視するtrue
WithACRValuesSupported...string(可変長)acr_values_supported を公開。FAPI / eIDAS / NIST 800-63 のように特定の ACR 値を扱うデプロイが広告するために使う空(discovery に出ない)
WithDiscoveryMetadataop.DiscoveryMetadata(typed な service_documentation / policy / TOS / UI locale / mTLS alias フィールド + Extra map[string]any)OP が所有しない RFC 8414 / OIDC Discovery metadata を discovery 文書に追加。UILocalesSupported は非空時に自動導出された locale list を上書きし、OP 管理フィールドと衝突する Extra key は拒否なし
WithJWKSRotationActivefunc() boolローテーション期間中だけ JWKS の Cache-Control を短期キャッシュに切り替える述語常に長期キャッシュ

subject 戦略 ​

Option値セクションデフォルト
WithSubjectGeneratorop.SubjectGenerator(interface)sub claim の導出を上書き。同梱の op/subject.UUIDv7 がデフォルトUUIDv7 通し
WithPairwiseSubject[]byte salt(32 byte 以上)OIDC Core §8.1 の sector ごと pairwise sub 導出を有効化。途中で戦略を切り替えると op.New が拒否するpublic(UUIDv7)

詳細は ユースケース: pairwise subject。

grant — Device Code / CIBA / Custom / Token Exchange ​

Option値セクションデフォルト
WithDeviceCodeGrant(引数なし)RFC 8628 device-authorization grant を有効化。/device_authorization をマウントし /token に URN を登録無効
WithDeviceVerificationURIstring(絶対 URL)デバイス画面に表示する verification URI を上書き(既定は <issuer>/device)自動導出
WithCIBA...op.CIBAOptionCIBA poll mode を有効化。/bc-authorize をマウントし CIBA URN を登録。サブオプション: WithCIBAHintResolver(必須)、WithCIBADefaultExpiresIn、WithCIBAMaxExpiresIn、WithCIBAPollInterval、WithCIBAMaxPollViolations無効
WithCustomGrantop.CustomGrantHandler組み込み側が定義する grant_type URN を /token に登録。handler はアクセストークンをそのまま返すか、BoundAccessToken 要求として返して OP に署名させるなし
RegisterTokenExchangeop.TokenExchangePolicyRFC 8693 token-exchange grant を有効化。ポリシーがリクエスト単位で受理可否(admission)を判断し、OP の既定値をさらに狭めることもできる無効

詳細は ユースケース: device code、CIBA、Custom grant、Token exchange。

認可機能 — RAR / Grant Management / Protected Resource Metadata ​

オプション値説明既定
WithAuthorizationDetailTypes...op.AuthorizationDetailTypeRFC 9396 Rich Authorization Requests を有効化。受理する type を validator とともに登録する。authorization_details は /authorize、/par、/token で検証され、grant に永続化され、JWT アクセストークンと introspection に反映され、discovery で公開される。nil の Validate は op.New で拒否される無効
WithGrantManagement(actions []op.GrantManagementAction, actionRequired bool)OAuth 2.0 Grant Management draft を有効化。grant_management_action / grant_id を処理し、query / revoke エンドポイントをマウントし、token 応答に grant_id を載せ、設定した action 集合を discovery で公開する。Experimental（IETF draft 追跡）無効
WithProtectedResources...op.ProtectedResource登録した各リソースについて RFC 9728 protected-resource metadata を /.well-known/oauth-protected-resource とリソース path の接尾辞で公開し、authorization_servers に issuer を載せるなし

op.StepUpChallenge(realm, acrValues, maxAge) は op.New のオプションではなく独立したヘルパで、組み込み側のリソースサーバが返す RFC 9470 の WWW-Authenticate: Bearer challenge を組み立てます。OP 自身はこれを発行しません。

詳細は Rich authorization requests、Grant management、Protected resource metadata、MFA / ステップアップ。

暗号化(JWE) ​

Option値セクションデフォルト
WithEncryptionKeysetop.EncryptionKeyset(RSA 2048 bit 以上 / EC P-256/384/521 の秘密鍵、use=enc)暗号化用 JWK を公開。inbound JWE request_object と outbound JWE 応答(id_token / userinfo / JARM / introspection)に必要なし
WithSupportedEncryptionAlgs(algs []string, encs []string)既定の許可リスト(RSA-OAEP-256 / ECDH-ES{,+A128KW,+A256KW} × A{128,256}GCM)を 狭める だけ。広げることはできない既定の許可リスト全体

詳細は ユースケース: JWE 暗号化。

mTLS / プロキシ / ネットワーク ​

Option値セクションデフォルト
WithMTLSProxy(headerName string, trustedCIDRs []string)エッジでヘッダ経由の mTLS を終端なし
WithTrustedProxies...string(CIDR)X-Forwarded-* / Forwarded から実クライアント IP を解決なし
WithTrustedProxyHosts...string(hostname)trusted proxy CIDR が設定されている場合に、正規の issuer host 以外の X-Forwarded-Host 許可リストを追加issuer host のみ
WithAllowLocalhostLoopback(引数なし)開発 / native app デモ用に RFC 8252 の loopback 緩和へ文字列 localhost を追加。literal 127.0.0.1 / [::1] は厳格既定のままliteral loopback のみ
WithAllowPrivateNetworkJWKS(引数なし)RFC 1918 上の client JWKS を許容(テスト専用)拒否
WithAllowPrivateNetworkJAR(引数なし)RFC 1918 上の request_uri を許容(テスト専用)拒否
WithAllowPrivateNetworkSector(引数なし)dynamic registration 時の sector_identifier_uri が RFC 1918 上にあることを許容(テスト / private RP network 専用)拒否
WithJWKSHTTPTransporthttp.RoundTripperJAR と private_key_jwt が使う RP 管理 JWKS 取得の transport を差し替える。接続時の SSRF 判定は維持されるシステム trust の transport
WithBackchannelAllowPrivateNetworkboolRFC 1918 上の backchannel_logout_uri を許容(テスト専用)false
WithAllowInsecureBackchannelLogoutForDev(引数なし)dev / CI fixture 用に plain-HTTP loopback の backchannel_logout_uri と配送を許容拒否
WithBackchannelLogoutHTTPClient*http.ClientBack-Channel ログアウト用の HTTP クライアントデフォルト
WithBackchannelLogoutTimeouttime.DurationRP ごとの fan-out タイムアウト5 秒

観測 ​

Option値セクションデフォルト
WithLogger*slog.Logger構造化された運用ログ(handler は redaction ミドルウェアで包まれる)discard
WithAuditLogger*slog.Logger監査イベント専用のロガーWithLogger を継承
WithPrometheus*prometheus.RegistryOP のカウンタを呼び出し側のレジストリに登録(/metrics はマウントしない)なし

運用方針 ​

Option値セクションデフォルト
WithSessionDurabilityPostureop.SessionDurabilityPostureback-channel logout の監査ログに方針を注釈付け(SOC 用途)volatile
WithClockop.Clock時刻ソース(テスト用に注入)time.Now

ここでは設定しないもの ​

意図的にオプションにしていない項目です。理由は各リンク先の設計判断を参照してください。

  • JOSE 検証用の許可リスト — client assertion、JAR request object、DPoP proof など入力側の署名検証では RS256 / PS256 / ES256 / EdDSA の固定集合を使います。OP が発行する JWT の署名は ES256 のみです。どちらの面も広げるフラグはありません。セキュリティ方針 §2 を参照。
  • PKCE method — S256 のみ。plain は構造的に拒否されます。
  • Cookie scheme — __Host- プリフィックス、AES-256-GCM、double-submit CSRF が常に有効です。必須オプション § WithCookieKeys を参照。
  • 乱数源 — crypto/rand のみ。math/rand は lint で禁止しています。
  • /metrics のマウント — ライブラリではなくルーター側の責務です。ユースケース: Prometheus を参照。

このリストの裏取り ​

カタログはライブラリ本体から grep で生成しています。自分で監査するには:

sh
git clone https://github.com/libraz/go-oidc-provider.git
cd go-oidc-provider
grep -rhE '^func With[A-Z]|^func RegisterTokenExchange' \
  op/options.go op/options_authn.go op/options_clients.go \
  op/options_ciba.go op/options_customgrant.go op/options_devicecode.go \
  op/options_discovery.go op/options_encryption.go op/options_features.go \
  op/options_fapi_proxy.go op/options_protocol.go op/options_session.go \
  op/options_subject.go op/access_token_revocation.go op/i18n.go \
  op/registration.go op/authorization_details.go op/grant_management.go \
  op/protected_resource.go \
  | sort -u

関数名と受け取る型のシグネチャが正典であり、各関数の godoc コメントが契約の正本です。