v0.11.0 影響確認 — verified_claims の OIDC4IDA 準拠化・配信・移行
本ドキュメントは v0.11.0 に含まれる verified_claims(身元確認済みクレーム)関連の変更と、その利用者側(RP / テナント運用者)への影響をまとめる。
Issue #1435 / PR #1514 対応: 身元確認済みクレーム(verified_claims)の Access Token 出力構造を OIDC4IDA 準拠のネスト構造に修正し、UserInfo エンドポイントでの返却に対応した。
Issue #1628 追加対応: UserInfo を claims パラメータ(OIDC4IDA 標準の要求方式)経由でも返せるようにし、verified_claims の §5.7「要求より少なく返す」挙動を仕様精査に基づいて見直した(claims が空でも verification は返す)。あわせて「何のクレームに同意したか」の記録を grant に自己完結保存する内部変更を行った。
影響まとめ
| 変更 | 種別 | 対象 |
|---|---|---|
Access Token の verified_claims がフラット → ネスト構造(verification + claims)になる | 🔴 破壊的 | access_token_selective_verified_claims を有効にしているテナントと、その Access Token を消費する RP / リソースサーバー |
UserInfo が verified_claims を返すようになる(スコープ経由) | 🟢 追加 | access_token_selective_verified_claims + verified_claims:* スコー プを使うテナント |
UserInfo が claims パラメータ(OIDC4IDA 標準)経由でも verified_claims を返す(フラグ不要) | 🟢 追加 | claims パラメータで userinfo.verified_claims を要求する RP(#1628) |
要求クレームが全て利用不可/不一致でも verification + 空 claims を返す(従来の「全体省略」を見直し) | 🟡 挙動変更 | verified_claims を消費する RP(§5.7 / #1512 の挙動見直し) |
claims パラメータの value / values 制約が verified_claims 要求でも適用される(従来は無視) | 🟡 挙動変更 | claims で value/values 制約付き verified_claims を要求する RP(#1624) |
verified_claims:* スコープ・access_token_selective_verified_claims フラグの設定追従 | 🟡 設定 | eKYC / 身元確認を提供するテナント |
Discovery に OIDC4IDA §8 メタデータ(verified_claims_supported 等)を広告+ evidence/trust_frameworks の supported 値を 1.0 正規値へ | 🟢 追加 / 🟡 挙動変更 | テナントの Discovery を読む RP(#1513 / #1651) |
verified_claims 要求(同意内容)を grant に sentinel 形式で自己完結保存(ID Token 側も対象) | ⚙️ 内部/運用 | テナント運用者(ローリングデプロイ / 同意レコード) |
| 身元確認申込みのステータス遷移を状態機械化(前進のみ・終端吸収・hard error 非遷移) | 🟡 挙動変更 | eKYC / 身元確認を提供するテナント(承認 → verified_claims 付与の前提となるライフサイクル, #1617) |
承認時に標準クレーム・custom_properties・ユーザーステータスも更新可能に(user_claims_mapping_rules / custom_properties_mapping_rules / user_status) | 🟢 追加 | eKYC / 身元確認を提供するテナント(承認時のユーザー属性更新, #1582) |
verified_claims / custom_properties の更新ポリシー(*_update_policy)を追加 | 🟢 追加 / 🟡 設定 | 段階的KYC・属性同期を行うテナント(#1584) |
承認時に実際適用した user_claims / custom_properties / user_status を結果レコードに記録(applied_user_claims カラム追加) | 🟢 追加 | eKYC / 身元確認を提供するテナント(承認時のユーザー属性変更の監査・トレーサビリティ, #1607) |
1. Access Token の構造変更(破壊的)
Before(フラット展開)
{
"verified_claims": {
"given_name": "Taro",
"family_name": "Yamada"
}
}
After(OIDC4IDA 準拠のネスト構造)
{
"verified_claims": {
"verification": {
"trust_framework": "eidas"
},
"claims": {
"given_name": "Taro",
"family_name": "Yamada"
}
}
}
verification(検証プロセスのメタデータ)と claims(検証済みクレーム値)が分離される。これは OpenID Connect for Identity Assurance 1.0 の verified_claims 構造に準拠する。
Access Token でも正規構造を使う根拠: OIDC4IDA §4.7 は Access Token での
verified_claims利用を「可能」と述べるのみで構造を規定しない。この穴を RFC 9068 §2.2.2(IANA 登録済みクレームは登録名・定義に従って encode すべき(SHOULD))が補完する。verified_claimsは IANA JWT Claims Registry 登録済みで、参照先が OpenID Identity Assurance Schema Definition 1.0 §5。その §5.2 / §5.4.2 がverification(必須)+claims(必須)のネスト構造とverification.trust_framework必須を定める。したがって Access Token・ID Token・UserInfo の全配信先で同一の正規構造を用い、AT だけフラット/独自形にはしない。
RP / リソースサーバー側の対応
クレーム値の参照パスを変更する。
| Before | After |
|---|---|
verified_claims.given_name | verified_claims.claims.given_name |
(verification は存在しなかった) | verified_claims.verification.trust_framework 等が参照可能に |
Access Token の
verified_claims出力は選択モード(access_token_selective_verified_claims)に一本化されている(旧・全量モードaccess_token_verified_claimsは #1603 で廃止)。
移行手順(破壊的変更の安全なロールアウト)
サーバーは新旧構造を同時には出力しない(ネスト構造へ一括切替)。RP(クライアント / リソースサーバー)が旧構造前提のままサーバーを更新すると壊れるため、RP を先に両対応させてから切り替える。
-
RP を新旧両対応にする(先行リリース) RP のパースをフラット(旧)・ネスト(新)の両 方を受理するよう更新してデプロイする。
- 新(優先):
verified_claims.claims.<claim> - 旧(フォールバック):
verified_claims.<claim>
この時点ではサーバーは旧構造のまま。両対応にしてあるので RP は壊れない。
- 新(優先):
-
新バージョンをリリース サーバーを更新し、
verified_claimsをネスト構造で出力する。RP は既に両対応済みのため無停止で切り替わる。 -
RP のフラット(旧構造)フォールバックを削除 全サーバーが新バージョンに切り替わったことを確認後、手順1で RP に追加したフラット構造のフォールバック処理を削除する。これで RP はネスト構造のみを扱う実装に整理される。
「RP 両対応 → サーバー新バージョンリリース → フォールバック削除」の順を守ること。サーバー先行で切り替えると、未対応の RP で
verified_claims参照が壊れる。
2. UserInfo での verified_claims 返却(追加)
これまで UserInfo は verified_claims を返さなかったが、本変更で返却するようになった。Access Token / ID Token と同じネスト構造(verification + claims)で返る。
// GET /v1/userinfo の応答(抜粋)
{
"sub": "...",
"verified_claims": {
"verification": { "trust_framework": "eidas" },
"claims": { "given_name": "Taro", "family_name": "Yamada" }
}
}
2.1 2つの要求方式
| 方式 | 要求方法 | フラグ | 位置づけ |
|---|---|---|---|
verified_claims:* スコープ | Access Token のスコープ | access_token_selective_verified_claims: true が必要 | idp-server 独自拡張。要素単位の選択は 3.1 |
claims パラメータ(#1628) | 認可リクエストの claims の userinfo.verified_claims メンバ | 不要 | OIDC4IDA 標準。value / values 制約や §5.7 の選択的省略が適用される |
スコープ経由は
access_token_selective_verified_claimsフラグに依存するが、claimsパラメータ経由はフラグ非依存で動作する(標準の要求メカニズムのため)。スコープ経由で返るclaimsは Access Token が持つverified_claims:<claim>スコープに対応するものに限られ、verificationの任意要素はverified_claims:verification:<element>スコープで選択する(3.1)。