Discoveryを設定配布として使う

OpenID Provider Configurationにはissuer、Authorization/Token/UserInfo/end-session endpoint、JWKS URI、対応response type、Client認証方式、署名algorithmが含まれます。

GET /.well-known/openid-configuration/api/auth

Clientはdocumentを取得しただけで信用せず、response内のissuerが期待したissuerと一致することを確認します。攻撃者のdiscovery documentからToken endpointやJWKS URIを受け入れると、Codeやcredentialを送る先を奪われます。

Better Auth 1.7.1の実測では次を確認できます。

Authorization Codeのみのresponse type
S256 PKCE
EdDSA ID Token signing
UserInfo endpoint
end-session endpoint
Device Authorization endpoint
DPoP ES256

これはProviderの現在のcapabilityであり、OAuth/OIDC仕様が全実装へ同じ値を要求しているという意味ではありません。

UserInfoへAccess Tokenを送る

UserInfoはOIDC Access Tokenで呼びます。

GET /api/auth/oauth2/userinfo
Authorization: Bearer <access-token>

responseのsubは、検証済みID Tokenのsubと必ず一致させます。違う場合、別principalの情報をidentity sessionへ混ぜるため拒否します。

profileやemail scopeを要求していなければ、対応claimが返らないことを正常として扱います。欠けたclaimを別の未検証sourceから補完しません。

claimをいつ使うか

ID TokenはToken発行時点のauthentication statementです。UserInfoはAccess Tokenを提示した時点で取得するclaimです。表示名や画像の新しさが必要ならUserInfoが向きますが、毎requestで呼ぶ必要はありません。

API authorizationにemailを使うことは避けます。emailは変更可能で、再利用される場合もあります。principal keyにはissuerとsubの組を使います。

cacheとkey rotation

DiscoveryとJWKSはcacheできますが、永続固定しません。未知のkidを受けたらJWKSをrefreshし、network failure時に既知keyをどこまで使うかを決めます。

一方、同じJWT verificationのたびにdiscoveryを取得するとAS障害がすべてのrequestへ波及します。metadata cache、JWKS cache、Token寿命を合わせて設計します。

failureを観測する

openidなしのAccess TokenでUserInfo → OIDC用scope不足
ID TokenとUserInfoのsubが違う → Clientがsession確立を拒否
Discovery issuerを改変 → metadataを採用しない
未宣言algorithmのID Token → header段階で拒否

次章ではClient local session、AS session、Tokenの終了を別々に扱います。