Skip to content

MS_OIDCUserInfoClaims

Jump to bottom
nishi_74322014 edited this page Sep 1, 2026 · 1 revision

OpenID Connect - ユーザー属性クレーム関連

概要

Final を参照して記述。

補足（ID トークンとユーザー属性の役割分担）: ID トークンは
**「いつ・誰が・どう認証されたか」**を伝えるもので、
本ページで扱うユーザー属性クレーム（プロフィール・メール・住所など）は
**「その人はどういう属性を持つか」**を伝えるものである。
後者は UserInfo エンドポイントから取るのが基本だが、
claims パラメタで ID トークン側に載せることもできる。

Standardクレーム

JWT のクレームを除く（sub だけ重複）。

グループ名

クレーム名

Standardクレームの一覧

項番 グループ名 / クレーム名 意味
1 sub ユーザーの一意識別子
2 profile プロフィール
2-1 　・ name フルネーム
2-2 　・ given_name 名
2-3 　・ family_name 姓
2-4 　・ middle_name ミドルネーム
2-5 　・ nickname ニックネーム
2-6 　・ preferred_username 好みのユーザー名
2-7 　・ profile プロフィールページの URL
2-8 　・ picture プロフィール画像の URL
2-9 　・ website Web サイトやブログの URL
2-10 　・ gender 性別。female と male が定義済み。
2-11 　・ birthdate 誕生日。YYYY-MM-DD。
2-12 　・ zoneinfo タイムゾーン。Europe/Paris など。
2-13 　・ locale ロケール。en-US など。
2-14 　・ updated_at 情報最終更新日。Unix エポックからの経過秒数。
3 email 電子メール
3-1 　・ email 電子メールアドレス
3-2 　・ email_verified 電子メールアドレスが検証済みか否かの真偽値
4 phone 電話
4-1 　・ phone_number 電話番号
4-2 　・ phone_number_verified 電話番号が検証済みか否かの真偽値
5 address 住所 JSON object。書式は「5.1.1. Address クレーム」に記載。
5-1 　・ formatted フォーマットされたフル住所、表示用・郵送用に使用
5-2 　・ street_address 通り・番地、号室、私書箱、複数行の拡張された住所情報。
5-3 　・ locality City or locality
5-4 　・ region State, province, prefecture, or region.
5-5 　・ postal_code Zip code or postal code
5-6 　・ country Country name

移行メモ（正誤・体裁）: 5-1 formatted の説明が
「フォーマットされたフルメールアドレス」となっていたが、
address の下位項目なので「フル住所」の誤りと判断して修正した。
また、元ページの表はセル結合でグループ名とクレーム名を
2 列に分けていたが、GitHub の Markdown はセル結合に対応していないため、
項番と 　・ のインデントで階層を表す形に整理した。

補足（*_verified は「本人のものと確認済み」の意）: email_verified /
phone_number_verified は、OP がそのアドレス／番号の到達確認を行い、
本人のものだと確認したことを示す。
RP がアカウント突き合わせ（名寄せ）にメール アドレスを使う場合、
email だけでなく email_verified を必ず見る必要がある。
未検証のアドレスで名寄せすると、
他人のアカウントに繋がる恐れがある。

格納要求

scopeパラメタによる格納要求

scope パラメタによってユーザー属性クレーム群の格納要求を行うことができる。

scopeに指定するグループ名

前述のグループ名（profile, email, phone, address）を
scope 値に指定可能。

格納部位

  • UserInfo エンドポイントから UserInfo レスポンス（JSON オブジェクト）として返される。

  • response_type 値が id_token の場合、

    • この場合、Access Token が発行されない。
    • ユーザー属性クレーム群は ID Token で返却される。

claimsパラメタによる詳細な格納要求

claims パラメタによって、scope パラメタより
詳細なユーザー属性クレーム群の格納要求を行うことができる。

トップレベルメンバ

個別のクレームの名前をメンバー名とする JSON オブジェクト

  • userinfo メンバ (OPTIONAL)
    UserInfo エンドポイントへ返却を要求する個々のクレームのリスト。

    • 当メンバが存在した場合、

      • scope パラメタで要求されたクレームに加え、
      • 当メンバでリストされたクレームも返却される。

    • 当メンバが存在しなかった場合、

      • scope パラメタで要求されたクレームのみが返却される。
      • userinfo メンバを指定する際は、UserInfo Endpoint を使用するために、
        response_type に対し, Access Token を Client に発行するタイプの値を
        指定しなければならない。

  • id_token メンバ (OPTIONAL)
    ID トークン内に格納して返却を要求する個々のクレームのリストを示す。

    • 当メンバが存在した場合、

      • デフォルトのクレームに加え
      • 当メンバでリストされたクレームも返却される。

    • 当メンバが存在しなかった場合、

      • デフォルトのクレームのみが返却される。

個別のクレーム値

  • null 値
    デフォルトの形式

  • JSON 値

    • essential
      Essential(必須) or Voluntary(任意)

      {"essential": true}

    • value
      指定の値を返す（固定値だが、用途不明確）

      {"value": "248289761001"}

    • values
      優先順に指定の値を返す（許容できる値の範囲）

      "acr": {"essential": true,
        "values": ["urn:mace:incommon:iap:silver",
                   "urn:mace:incommon:iap:bronze"]}

補足（value の用途）: 「固定値だが、用途不明確」とされている value は、
「この値であることを確認したい」ときに使うものである。
例えば "sub": {"value": "248289761001"} とすれば、
「今ログインしているのがこの利用者であること」を OP に確認させられる
（別人であればエラーになる）。
アカウント連携の再確認や、
ACR の特定値の要求などで使う。

クレーム要求JSONの例

クレーム要求 JSON の例を以下に示す:

{
 "userinfo":
  {
   "given_name": {"essential": true},
   "nickname": null,
   "email": {"essential": true},
   "email_verified": {"essential": true},
   "picture": null,
   "http://example.info/claims/groups": null
  },
 "id_token":
  {
   "auth_time": {"essential": true},
   "acr": {"values": ["urn:mace:incommon:iap:silver"] }
  }
}

エンドポイント

  • OAuth 2.0 の Resource Server の WebAPI
  • HTTP 的には、HTTPS 必須

Request

  • HTTP の GET と POST メソッドをサポートする。

  • UserInfo リクエストの一例を示す:

GET /userinfo HTTP/1.1
Host: server.exampletechinfoofmicrosofttech.osscons.jp
Authorization: Bearer ・・・・・

Response

  • UserInfo レスポンスは JSON オブジェクトとして返される。

    • UserInfo クレームは JSON オブジェクトのメンバとして返される。
    • UserInfo レスポンスのクレームセットには、必ず sub (subject) クレームを含める。
    • ユーザー属性クレーム群に加え、
      そこに明記されていないクレームも返却可能。
    • IdP（OP）は要求されたクレームの値を、必ずしも返さなくてもよい。
    • クレームが返されない場合、null や空文字列ではなく、
      JSON オブジェクトのメンバから除かれるべき。

  • JWT による署名 or 暗号化、若しくは、署名 and 暗号化を行う場合

    • クレームは JWT で返されるため、Content-Type は application/jwt とする。
    • 署名する場合、sub に加え、iss (issuer) クレームと aud (audience) クレームを含むべき。
    • 暗号化のアルゴリズムは Registration による
      userinfo_encrypted_response_alg で指定する。
    • 署名と暗号化の両方が要求された場合、レスポンスは JWT で定義されているように、
      結果はネストされた JWT となり、署名した後に暗号化しなければならない。

  • クライアントによる UserInfo レスポンスの検証

    • TLS サーバー証明書チェックを通じて IdP（OP）を検証する。
    • UserInfo レスポンスが JWT の場合、署名検証や復号化を行う。
    • ID トークンと UserInfo クレームの sub が一致することを検証する必要がある。

補足（sub の一致確認は必須）: UserInfo エンドポイントは
Access Token だけで呼べるため、これ単体では
「今ログインした利用者の情報か」が保証されない。
ID トークンの sub と突き合わせることで初めて、
取得した属性が認証済みの利用者のものだと確認できる
（Token Substitution 攻撃への対策）。

Request & Responseの例

以下に UserInfo レスポンスの一例を示す。

  • 成功
HTTP/1.1 200 OK
Content-Type: application/json
{
  "sub": "ユーザID 的 な情報",
  "name": "Jane Doe",
  "given_name": "Jane",
  "family_name": "Doe",
  "preferred_username": "j.doe",
  "email": "janedoe@techinfoofmicrosofttech.osscons.jp",
  "picture": "http://techinfoofmicrosofttech.osscons.jp/janedoe/me.jpg"
}
  • 失敗
HTTP/1.1 401 Unauthorized
WWW-Authenticate: error="invalid_token",
  error_description="The Access Token expired"

Discovery、Dynamic Client Registrationとの関連

設定によって、ID トークン相当の情報が、

  • JWT 形式もしくは JSON 形式で返される。
  • JWT の署名アルゴリズムも影響を受ける。

（OpenID Connect - Discovery、
OpenID Connect - Dynamic Client Registrationを参照）

クレーム・タイプ

補足（3 つの違い）:

種類 クレームの出どころ OP が返すもの
Normal OP 自身 値そのもの
Aggregated 別の Claims Provider その Provider が署名した JWT（値入り）
Distributed 別の Claims Provider 取りに行くための endpoint と access_token

Aggregated は値を OP 経由で運ぶのに対し、
Distributed はRP が自分で取りに行く。
銀行の残高や信用スコアのように、
OP に見せたくない／鮮度が要る情報は Distributed が向く。

Normalクレーム

  • OpenID Provider によって直接アサートされたクレーム。
  • JSON オブジェクトの中にメンバとして表記される。
{
 "name": "Jane Doe",
 "given_name": "Jane",
 "family_name": "Doe",
 "email": "janedoe@example.com",
 "picture": "http://example.com/janedoe/me.jpg"
}

Aggregatedクレーム

Aggregatedクレームの概要

  • OpenID Provider 以外の Claims Provider によってアサートされたクレームであるが,
    OpenID Provider から返却されるクレーム。
  • JSON オブジェクト中で, _claim_names および _claim_sources という
    特殊なメンバを用いて表記される。
    • _claim_names
      _claim_sources メンバーの中にあるメンバー名への参照
    • _claim_sources
      JWT を値として持つ JSON オブジェクト（sub クレームを含まない）

Aggregatedクレームの例

  • Aggregated クレーム本体
    以下を jwt_header.jwt_part2.jwt_part3 と JWT 化する。
{
 "address": {
   "street_address": "1234 Hollywood Blvd.",
   "locality": "Los Angeles",
   "region": "CA",
   "postal_code": "90210",
   "country": "US"},
 "phone_number": "+1 (310) 123-4567"
}
  • Aggregated クレームを含むクレームセット
{
 "name": "Jane Doe",
 "given_name": "Jane",
 "family_name": "Doe",
 "birthdate": "0000-03-22",
 "eye_color": "blue",
 "email": "janedoe@example.com",
 "_claim_names": {
   "address": "src1",
   "phone_number": "src1"
 },
 "_claim_sources": {
   "src1": {"JWT": "jwt_header.jwt_part2.jwt_part3"}
 }
}

Distributedクレーム

Distributedクレームの概要

  • OpenID Provider 以外の Claims Provider によってアサートされたクレームであり,
    OpenID Provider からはその参照だけが返却されるクレーム。
  • JSON オブジェクト中で, _claim_names および _claim_sources という
    特殊なメンバを用いて表記される。
    • _claim_names
      _claim_sources メンバーの中にあるメンバー名への参照
    • _claim_sources
      endpoint、access_token のメンバと値を含む JSON オブジェクト
      • endpoint (REQUIRED):
        JWT 形式の Distributed クレームセットを提供するエンドポイントの URL
      • access_token (OPTIONAL):
        endpoint（Resource Server）を利用するための access_token

Distributedクレームの例

  • Distributed クレーム本体
    以下を jwt_header.jwt_part2.jwt_part3 と JWT 化して、
    エンドポイントからレスポンスする。

    • その１
{
 "shipping_address": {
   "street_address": "1234 Hollywood Blvd.",
   "locality": "Los Angeles",
   "region": "CA",
   "postal_code": "90210",
   "country": "US"},
 "payment_info": "Some_Card 1234 5678 9012 3456",
 "phone_number": "+1 (310) 123-4567"
}
  • その２
{
 "credit_score": 650
}
  • Distributed クレームを含むクレームセット
{
 "name": "Jane Doe",
 "given_name": "Jane",
 "family_name": "Doe",
 "email": "janedoe@example.com",
 "birthdate": "0000-03-22",
 "eye_color": "blue",
 "_claim_names": {
   "payment_info": "src1",
   "shipping_address": "src1",
   "credit_score": "src2"
  },
 "_claim_sources": {
   "src1": {"endpoint":
              "https://bank.example.com/claim_source"},
   "src2": {"endpoint":
              "https://creditagency.example.com/claims_here",
            "access_token": "ksj3n283dke"}
 }
}

その他

多言語化

  • クレームによっては多言語化可能
  • クレーム名に続いて #ja-Kana-JP などの言語タグを付与する。
  • 言語タグとしては、BCP47 [RFC5646] 言語タグを使用。

参考

本 Wiki 内

Tags: IT国際標準, 認証基盤, クレームベース認証, OAuth

このWikiは「Open棟梁Project」,「OSSコンソーシアム 開発基盤部会」によって運営されています。

NetDevInfraWiki

マイクロソフト系技術情報 Wiki
Open 棟梁 Wiki

（未着手）

開発基盤部会 Wiki

移行管理: DONE ／ TODO

Clone this wiki locally