次の方法で共有


ID トークンの要求のリファレンス

ID トークンは JSON Web トークン (JWT) です。 v1.0 と v2.0 の ID トークンは、含まれる情報に違いがあります。 バージョンは、要求元のエンドポイントに基づきます。 既存のアプリケーションでは Azure AD v1.0 エンドポイントを使用する場合が多いですが、新しいアプリケーションでは v2.0 エンドポイントを使用する必要があります。

  • v1.0: https://login.microsoftonline.com/common/oauth2/authorize
  • v2.0: https://login.microsoftonline.com/common/oauth2/v2.0/authorize

次のセクションに示す JWT 要求はすべて、特に明記されていない限り、v1.0 と v2.0 のトークンの両方に表示されます。 ID トークンは、ヘッダー、ペイロード、署名で構成されます。 ヘッダーと署名は、トークンの信頼性を確認するために使用されます。ペイロードには、クライアントによって要求されたユーザーの情報が含まれます。

ヘッダーのクレーム

次の表は、ID トークンに存在するヘッダーの要求をまとめたものです。

要求 フォーマット 説明
typ 文字列 - 常に "JWT" トークンが JWT トークンであることを示します。
alg String トークンの署名に使用されたアルゴリズムを示します。 例: "RS256"
kid 文字列 トークンの署名を検証するために使用できる公開キーの拇印を指定します。 v1.0 と v2.0 のどちらの ID トークンでも生成されます。
x5t String kid と同様に機能します (使用方法も値も同じ)。 x5t は、互換性を目的として v1.0 ID トークンでのみ生成されるレガシ クレームです。

ペイロードのクレーム

次の表は、(明記されている場合を除き) 既定でほとんどの ID トークンに含まれる要求をまとめたものです。 ただし、アプリは、省略可能なクレームを使用して、ID トークンで追加のクレームを要求することができます。 省略可能なクレームは、groups 要求から、ユーザーの名前に関する情報にまで及ぶ場合があります。

要求 フォーマット 説明
aud 文字列、アプリケーション ID GUID トークンの受信者を示します。 id_tokensでは、対象の受信者は Azure portal でアプリに割り当てられたアプリのアプリケーション ID です。 この値は検証する必要があります。 アプリのアプリケーション ID と一致しない場合は、トークンを拒否する必要があります。
iss 文字列、発行者 URI トークンを作成して返す発行者、つまり "承認サーバー" を特定します。 また、ユーザーが認証されたテナントも識別します。 トークンが v2.0 エンドポイントによって発行された場合、URI の末尾は /v2.0 になります。 ユーザーが Microsoft アカウントを持つコンシューマー ユーザーであることを示す GUID は 9188040d-6c67-4c5b-b112-36a304b66dad です。 要求の GUID 部分を使用して、アプリにサインインできるテナントのセットを制限します (該当する場合)。
iat int、Unix タイムスタンプ トークンの認証がいつ行われたのかを示します。
idp 文字列 (通常は STS URI) トークンのサブジェクトを認証した ID プロバイダーを記録します。 この値は、発行者とテナントが異なるユーザー アカウント (たとえばゲスト) の場合を除いて、発行者要求の値と同じです。 クレームが存在しない場合は、代わりに iss の値を使用できることを示しています。 個人用アカウントが組織のコンテキストで使用されている場合 (たとえば、個人用アカウントがテナントに招待された場合)、idp 要求は "live.com" または Microsoft アカウント テナント 9188040d-6c67-4c5b-b112-36a304b66dad を含む STS URI である可能性があります。
nbf int、Unix タイムスタンプ JWT が有効になる日時を示します。これ以前にその JWT を受け入れて処理することはできません。
exp int、Unix タイムスタンプ それ以降 JWT の処理を受け入れることができなくなる時刻を示します。 特定の状況下では、この時点より前にリソースによってトークンが拒否される可能性があります。 たとえば、認証の変更が必要な場合や、トークンの失効が検出された場合などです。
c_hash String コード ハッシュは、ID トークンが OAuth 2.0 認証コードと共に発行される場合にのみ、ID トークンに含まれます。 これを使用して、認証コードの信頼性を検証できます。 この検証を実行する方法については、OpenID Connect の仕様を参照してください。 この要求は、/token エンドポイントからの ID トークンでは返されません。
at_hash String アクセス トークン ハッシュは、ID トークンが /authorize エンドポイントから OAuth 2.0 アクセス トークンと共に発行される場合にのみ、ID トークンに含まれます。 これを使用して、アクセス トークンの信頼性を検証できます。 この検証を実行する方法については、OpenID Connect の仕様を参照してください。 この要求は、/token エンドポイントからの ID トークンでは返されません。
aio あいまいな文字列 トークン再利用のためにデータの記録に使用される内部要求。 無視してください。
preferred_username String ユーザーを表すプライマリ ユーザー名です。 電子メール アドレス、電話番号、または指定された書式のない一般的なユーザー名を指定できます。 その値は、変更可能であり、時間の経過と共に変化することがあります。 これは変更可能であるため、この値は承認の決定には使用できません。 これは、ユーザー名のヒントとして使用することや、人間が判読できる UI でユーザー名として使用することができます。 この要求を受け取るには profile スコープが必要です。 v2.0 トークンにのみ存在します。
email String メールアドレスを持つゲスト アカウントに対して既定で使用されます。 アプリでは、オプションの要求である email を使用して、管理対象ユーザー (リソースと同じテナントのユーザー) の電子メール要求を要求できます。 この値は正しいとは限りません。また、時間の経過と共に変化する場合があります。 認可に使用したり、ユーザーのデータを保存したりすることはできません。 アプリでアドレス指定可能なメール アドレスが必要な場合は、この要求を提案として使用するか、UX に事前に入力して、このデータをユーザーに直接要求します。 v2.0 エンドポイントでは、アプリで email OpenID Connect スコープを要求することもできます (要求を取得するためにオプション要求とスコープの両方を要求する必要はありません)。
name String name要求は、トークンのサブジェクトを識別する、人が認識できる値を示します。 この値は一意であるとは限らず、変更可能であり、表示目的でのみ使用する必要があります。 この要求を受け取るには profile スコープが必要です。
nonce String nonce は、IDP に対する元の承認要求に含まれるパラメーターと一致します。 一致しない場合は、アプリケーションによってトークンが拒否されます。
oid 文字列、GUID オブジェクト (ここではユーザー アカウント) に対する変更不可の識別子です。 この ID によって、複数のアプリケーションでユーザーが一意に識別されます。同じユーザーにサインインする 2 つの異なるアプリケーションは oid 要求で同じ値を受け取ります。 Microsoft Graph は、この ID をユーザー アカウントの id プロパティとして返します。 oid では複数のアプリがユーザーを関連付けることができるため、この要求を受け取るには profile スコープが必要です。 1 人のユーザーが複数のテナントに存在する場合、そのユーザーのオブジェクト ID はテナントごとに異なります。つまり、そのユーザーが同じ資格情報で各アカウントにログインしても、それぞれ異なるアカウントと見なされます。 oid 要求は GUID であり、再利用することはできません。
roles 文字列の配列 ログインしているユーザーに割り当てられた一連のロール。
rh 不透明な文字列 トークンの再検証に使用される内部要求。 無視してください。
sub String トークン内の情報のサブジェクト。 たとえば、アプリのユーザーです。 この値は変更不可で、再割り当ても再利用もできません。 サブジェクトはペアワイズ識別子で、アプリケーション ID に一意です。 1 人のユーザーが 2 つの異なるクライアント ID を使用して 2 つの異なるアプリにサインインすると、そのアプリは、サブジェクト要求に対して 2 つの異なる値を受け取ることになります。 2 つの値が必要かどうかは、アーキテクチャやプライバシーの要件によって異なります。
tid 文字列、GUID ユーザーがサインインしているテナントを表します。 職場または学校アカウントの場合、GUID はユーザーがサインインしている組織の不変のテナント ID です。 個人用 Microsoft アカウント テナント (Xbox、Teams for Life、Outlook のようなサービス) へのサインインの場合、値は 9188040d-6c67-4c5b-b112-36a304b66dad です。
unique_name String v1.0 トークンにのみ存在します。 トークンのサブジェクトを識別する、人が判読できる値を提供します。 この値は、テナント内で一意であることが保証されているわけではなく、表示目的でのみ使用する必要があります。
uti String トークン識別子要求。JWT 仕様の jti と同等です。 大文字と小文字を区別する一意のトークンごとの識別子。
ver 文字列、1.0 または 2.0 ID トークンのバージョンを示します。
hasgroups Boolean 存在する場合、常に true であり、ユーザーが 1 つ以上のグループに属していることを示します。 クライアントが Microsoft Graph API を使用して、ユーザーのグループを決定する必要があることを示します (https://graph.microsoft.com/v1.0/users/{userID}/getMemberObjects)。
groups:src1 JSON オブジェクト 長さは制限されていない (hasgroups を参照) が、まだトークンには大きすぎるトークン要求の場合は、そのユーザーの完全なグループ リストへのリンクが含まれます。 SAML では groups 要求の代わりに新しい要求として、JWT では分散要求として使用されます。

JWT 値の例:
"groups":"src1"
"_claim_sources: "src1" : { "endpoint" : "https://graph.microsoft.com/v1.0/users/{userID}/getMemberObjects" }

詳細については、「グループ超過要求」を参照してください。

要求を使用してユーザーを確実に識別する

ユーザーを識別する場合は、時間が経過しても一定で一意の情報を使用することが重要です。 レガシ アプリケーションでは、メールアドレス、電話番号、UPN などのフィールドが使われることがあります。 これらのフィールドはすべて時間の経過と共に変わることがあり、時間の経過と共に再利用されることもあります。 たとえば、従業員の名前が変わったり、または従業員に以前の存在しなくなった従業員のメール アドレスに一致するアドレスが与えられたりする場合などです。 アプリケーションでユーザーを識別するために、人間が判読できるデータを使用してはなりません。人間が判読可能であるとは、一般にだれかがそれを読むことができ、変更したくなることを意味します。 代わりに、OIDC 標準によって提供される要求、または Microsoft によって提供される拡張要求 (sub および oid 要求) を使用します。

ユーザーごとに情報を正しく格納するには、sub または oid を単独で使用し (GUID は一意であるため)、必要に応じて tid をルーティングまたはシャーディングに使用します。 サービス間でデータを共有する必要がある場合は、すべてのアプリで、テナントで活動するユーザーに対して同じ oidtid 要求が取得されるため、oidtid が最適です。 sub 要求は、一意のペアワイズ値です。 値は、トークンの受信者、テナント、ユーザーの組み合わせに基づきます。 ユーザーに対して ID トークンを要求する 2 つのアプリは、sub 要求は異なっていても、そのユーザーに対して同じ oid 要求を受け取ることになります。

注意

テナント間でユーザーを関連付けようとして、idp 要求を使用して、ユーザーに関する情報を格納しないでください。 これは機能しません。ユーザーの oid および sub 要求は、設計によってテナント間で変わり、アプリケーションで、テナントを越えてユーザーを追跡できないようにしているためです。

ユーザーが 1 つのテナントに所属し、別のテナントで認証するゲスト シナリオでは、ユーザーがサービスに対して新しいユーザーであるかのように、ユーザーを処理する必要があります。 あるテナントのドキュメントと特権は、別のテナントには適用できません。 この制限は、テナント間での偶発的なデータ漏えいを防ぎ、データのライフサイクルを実施するために重要です。 テナントからゲストを退去させると、そのテナントで作成したデータへのゲストのアクセスも削除されます。

グループ超過要求

トークンのサイズが HTTP ヘッダー サイズの上限を超えないよう、groups 要求に含まれるオブジェクト ID の数は制限されています。 超過制限 (SAML トークンの場合は 150、JWT トークンの場合は 200) を超えるグループのメンバーにユーザーがなっている場合、グループ要求はトークンに出力されません。 代わりに、Microsoft Graph API に照会してユーザーのグループ メンバーシップを取得するようアプリケーションに指示する超過要求がトークンに追加されます。

{
  ...
  "_claim_names": {
   "groups": "src1"
    },
    {
  "_claim_sources": {
    "src1": {
        "endpoint":"[Url to get this user's group membership from]"
        }
       }
     }
  ...
}

次のステップ