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 をルーティングまたはシャーディングに使用します。 サービス間でデータを共有する必要がある場合は、すべてのアプリで、テナントで活動するユーザーに対して同じ oid と tid 要求が取得されるため、oid と tid が最適です。 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]"
}
}
}
...
}
次のステップ
- Microsoft Entra ID で使われる ID トークンについて説明します。