アクセス トークン クレームのリファレンス
アクセス トークンは JSON Web トークン (JWT) です。 JWT には、次の要素が含まれます。
- ヘッダー - トークンの種類や署名方法の情報など、トークンの検証方法に関する情報を提供します。
- ペイロード - サービスを呼び出そうとしているユーザーまたはアプリケーションに関する重要なデータがすべて含まれています。
- 署名 - トークンの検証に使用される原材料です。
各部分はピリオド (.) で区切られ、Base64 で個別にエンコードされます。
クレームは、そこに入力される値が存在する場合にのみ存在します。 アプリケーションは要求の存在に依存することはできません。 例として、pwd_exp (すべてのテナントでパスワードを期限切れにする必要があるわけではありません) や、family_name (名前のないアプリケーションに代わって、クライアント資格情報フローが使用されます) などがあります。 アクセス トークンには、アクセス評価のための十分な要求が常に含まれます。
Microsoft ID プラットフォームでは、いくつかの要求を使用して、再利用のためにトークンをセキュリティで保護します。 Opaque の説明では、これらの要求は一般に公開されないものとして示されています。 これらのクレームはトークンに表示される場合とされない場合があり、新しいものが予告なく追加される場合もあります。
ヘッダーのクレーム
| 要求 | フォーマット | 説明 |
|---|---|---|
typ |
文字列 - 常に JWT |
トークンが JWT であることを示します。 |
alg |
String | トークンの署名に使用されたアルゴリズム (RS256 など) を示します。 |
kid |
String | トークンの署名を検証するために使用される公開キーの拇印を指定します。 v1.0 と v2.0 のどちらのアクセス トークンでも生成されます。 |
x5t |
String | kid と同様に機能します (使用方法も値も同じ)。 x5t は、互換性を目的として v1.0 アクセス トークンでのみ生成されるレガシ クレームです。 |
ペイロードのクレーム
| 要求 | フォーマット | 説明 | 認可に関する考慮事項 |
|---|---|---|---|
acrs |
文字列の JSON 配列 | ベアラーで実行できる操作の認証コンテキスト ID を示します。 認証コンテキスト ID を使用して、アプリケーションとサービス内からステップアップ認証の要求をトリガーできます。 多くの場合、xms_cc クレームと共に使用されます。 |
|
aud |
文字列、アプリケーション ID URI、または GUID | トークンの想定されている読者を識別します。 v2.0 トークンでは、この値は常に API のクライアント ID です。 v1.0 トークンでは、これは、クライアント ID、または要求で使用されるリソース URI になります。 値は、クライアントがトークンを要求した方法によって異なります。 | この値は検証の必要があり、値が対象と一致しない場合はトークンを拒否します。 |
iss |
文字列、セキュリティ トークン サービス (STS) URI | トークンを作成して返す STS と、認証されたユーザーの Microsoft Entra テナントを識別します。 発行されたトークンが v2.0 トークンである場合 (ver 要求を参照)、URI は /v2.0 で終了します。 ユーザーが Microsoft アカウントを持つコンシューマー ユーザーであることを示す GUID は 9188040d-6c67-4c5b-b112-36a304b66dad です。 |
アプリケーションでは、要求の GUID 部分を使用して、アプリケーションにサインインできるテナントのセットを制限できます (該当する場合)。 |
idp |
文字列 (通常は STS URI) | トークンのサブジェクトを認証した ID プロバイダーを記録します。 この値は、発行者とテナントが異なるユーザー アカウント (ゲストなど) の場合を除いて、発行者クレームの値と同じです。 要求が存在しない場合は、iss の値を使用します。 個人用アカウントが組織のコンテキストで使用されている場合 (たとえば、個人用アカウントが Microsoft Entra テナントに招待された場合)、idp 要求は "live.com" または Microsoft アカウント テナント 9188040d-6c67-4c5b-b112-36a304b66dad を含む STS URI である可能性があります。 |
|
iat |
int、Unix タイムスタンプ | このトークンの認証がいつ行われたのかを示します。 | |
nbf |
int、Unix タイムスタンプ | JWT を処理できるようになる時間を指定します。 | |
exp |
int、Unix タイムスタンプ | JWT が期限切れになる時間を指定します。この時間より前は、JWT を受け入れて処理できます。 この日時より前でも、リソースがトークンを拒否する場合もありあす。 認証で必要な変更や、トークンが取り消されたときに、拒否が発生する場合があります。 | |
aio |
あいまいな文字列 | Microsoft Entra ID がトークン再利用のためにデータの記録に使用する内部の要求。 リソースでこの要求を使用しないでください。 | |
acr |
文字列、「0」 または 「1」、v1.0 トークンにのみ存在する |
"認証コンテキスト クラス" 要求の値 「0」 は、エンドユーザーの認証が ISO/IEC 29115 の要件を満たしていないことを示します。 |
|
amr |
文字列のJSON配列、v1.0 トークンにのみ存在する | トークンのサブジェクトの認証方法を識別します。 | |
appid |
文字列、GUID、v1.0 トークンにのみ存在する | トークンを使用するクライアントのアプリケーションID。 アプリケーションとして識別することもできますが、アプリケーションを使用しているユーザーとして識別することもできます。 アプリケーション ID は通常、アプリケーション オブジェクトを表しますが、Microsoft Entra ID 内のサービス プリンシパル オブジェクトを表すこともできます。 | appid は認可の決定に使用できます。 |
azp |
文字列、GUID、v2.0 トークンにのみ存在する | appid に代わるものです。 トークンを使用するクライアントのアプリケーションID。 アプリケーションとして識別することもできますが、アプリケーションを使用しているユーザーとして識別することもできます。 アプリケーション ID は通常、アプリケーション オブジェクトを表しますが、Microsoft Entra ID 内のサービス プリンシパル オブジェクトを表すこともできます。 |
azp は認可の決定に使用できます。 |
appidacr |
文字列、「0」、「1」または 「2」、v1.0 トークンにのみ存在する |
クライアントの認証方法を示します。 パブリック クライアントの場合、値は "0" です。 クライアント ID とクライアント シークレットを使用する場合、値は 1 です。 クライアント証明書を認証に使用する場合、値は 2 です。 |
|
azpacr |
文字列、「0」、「1」または 「2」、v2.0 トークンにのみ存在する |
appidacr に代わるものです。 クライアントの認証方法を示します。 パブリック クライアントの場合、値は "0" です。 クライアント ID とクライアント シークレットを使用する場合、値は 1 です。 クライアント証明書を認証に使用する場合、値は 2 です。 |
|
preferred_username |
文字列、v2.0 トークンにのみ存在する | ユーザーを表すプライマリ ユーザー名です。 この値には、電子メール アドレス、電話番号、または指定された書式のない一般的なユーザー名を指定できます。 この値をユーザー名のヒントとして使用したり、人間が判読できる UI でユーザー名として使用します。 この要求を受け取るには profile スコープを使用します。 |
この値は変更可能なため、認可の判断には使用しないでください。 |
name |
String | トークンのサブジェクトを識別する、人間が判読できる値を提供します。 値は変化する場合があり、変更可能であり、表示のみを目的としています。 この要求を受け取るには profile スコープを使用します。 |
この値は認可の判断に使用しないでください。 |
scp |
文字列、スコープのスペース区切りリスト | クライアント アプリケーションが同意を要求し、同意を得た、アプリケーションによって公開されているスコープのセット。 ユーザー トークンにのみ含まれます。 | アプリケーションでは、これらのスコープがアプリケーションによって公開されている有効なスコープであることを確認し、これらのスコープの値に基づいて認可を決定する必要があります。 |
roles |
文字列の配列、アクセス許可の一覧 | 要求元のアプリケーションまたはユーザーに呼び出しのアクセス許可が付与されている、アプリケーションによって公開されているアクセス許可のセット。 アプリケーション トークンで、このアクセス許可のセットはユーザー スコープの代わりにクライアント資格情報フローで使用されます。 ユーザー トークンで、この値のセットにはターゲット アプリケーションのユーザーに割り当てられたロールが含まれます。 | これらの値はアクセスの管理 (リソースへのアクセスに認可を適用するなど) に使用できます。 |
wids |
RoleTemplateID GUID の配列 | Microsoft Entra 組み込みロールに存在するロールのセクションから、このユーザーに割り当てられたテナント全体のロールを示します。 この要求は、アプリケーション マニフェストの groupMembershipClaims プロパティによって、アプリケーションごとに構成されます。 要求を All や DirectoryRole に設定します。 トークンの長さの問題のため、暗黙的フローを介して取得されたトークンには存在しない可能性があります。 |
これらの値はアクセスの管理 (リソースへのアクセスに認可を適用するなど) に使用できます。 |
groups |
GUID の JSON 配列 | サブジェクトのグループ メンバーシップを表すオブジェクト ID です。 このグループ要求は、アプリケーション マニフェストの groupMembershipClaims プロパティによって、アプリケーションごとに構成されます。 値が null の場合はすべてのグループが除外され、値が SecurityGroup の場合は Active Directory セキュリティ グループのメンバーシップのみが含まれ、値が All の場合はセキュリティ グループと Microsoft 365 配布リストの両方が含まれます。 暗黙的な許可での groups 要求の使用の詳細については、hasgroups 要求を参照してください。 他のフローでは、ユーザーが属するグループの数が SAML の場合は 150、JWT の場合は 200 を超えた場合、Microsoft Entra ID によって要求ソースに超過要求が追加されます。 要求ソースは、ユーザーのグループのリストを含む Microsoft Graph エンドポイントを参照します。 |
これらの値はアクセスの管理 (リソースへのアクセスに認可を適用するなど) に使用できます。 |
hasgroups |
Boolean | 存在する場合、常に true であり、ユーザーが 1 つ以上のグループに属しているかどうかを示します。 すべてのグループ要求で URL 長の制限 (現在は 6 以上のグループ) を超えて URI フラグメントが拡張された場合、暗黙的な許可フローの JWT で groups 要求の代わりに使用されます。 クライアントが Microsoft Graph API を使用して、ユーザーのグループ (https://graph.microsoft.com/v1.0/users/{userID}/getMemberObjects) を決定する必要があることを示します。 |
|
groups:src1 |
JSON オブジェクト | トークン要求がトークンに対して大きすぎる場合は、ユーザーの完全なグループ リストへのリンクを含めます。 SAML では groups 要求の代わりに新しい要求として、JWT では分散要求として使用されます。 JWT 値の例: "groups":"src1" "_claim_sources: "src1" : { "endpoint" : "https://graph.microsoft.com/v1.0/users/{userID}/getMemberObjects" } |
|
sub |
String | トークンに関連付けられているプリンシパル。 たとえば、アプリケーションのユーザーです。 この値は不変であり、再割り当てや再利用をしないでください。 サブジェクトは、特定のアプリケーション ID に一意のペアワイズ識別子です。 1 人のユーザーが 2 つの異なるクライアント ID を使用して 2 つの異なるアプリケーションにサインインすると、そのアプリケーションは、サブジェクト要求に対して 2 つの異なる値を受け取ります。 2 つの異なる値の使用は、アーキテクチャとプライバシーの要件によって異なります。 oid 要求 (テナント内のアプリケーション全体で同じまま) もご覧ください。 |
トークンを使用してリソースにアクセスする場合など、認可チェックを実行するためにこの値を使用できます。また、データベース テーブルのキーとして使用することもできます。 |
oid |
文字列、GUID | 要求元の不変識別子。これは、ユーザーやサービス プリンシパルの検証済み ID です。 この ID によって、複数のアプリケーションで要求元が一意に識別されます。 同じユーザーにサインインする 2 つの異なるアプリケーションは oid 要求で同じ値を受け取ります。 Microsoft Graph などの Microsoft オンライン サービスに対してクエリを実行するときに oid を使用できます。 Microsoft Graph は、この ID を、指定されたユーザー アカウントの id プロパティとして返します。 oid では複数のアプリケーションがプリンシパルを相互に関連付けられるため、ユーザーがこの要求を受け取るには、profile スコープを使用します。 1 人のユーザーが複数のテナントに存在する場合、そのユーザーのオブジェクト ID はテナントごとに異なります。 ユーザーは同じ資格情報で各アカウントにログインしますが、アカウントは異なります。 |
トークンを使用してリソースにアクセスする場合など、認可チェックを実行するためにこの値を使用できます。また、データベース テーブルのキーとして使用することもできます。 |
tid |
文字列、GUID | ユーザーがサインインしているテナントを表します。 職場または学校アカウントの場合、GUID はユーザーがサインインしている組織の不変のテナント ID です。 個人用 Microsoft アカウント テナント (Xbox、Teams for Life、Outlook のようなサービス) へのサインインの場合、値は 9188040d-6c67-4c5b-b112-36a304b66dad です。 この要求を受け取るには、アプリケーションが profile スコープを要求する必要があります。 |
認可の決定において、この値は他の要求と組み合わせて考慮する必要があります。 |
unique_name |
文字列、v1.0 トークンにのみ存在する | トークンのサブジェクトを識別する、人が判読できる値を提供します。 | この値はテナント内で異なる場合があり、表示目的でのみ使用します。 |
uti |
String | トークン識別子要求。JWT 仕様の jti と同等です。 大文字と小文字を区別する一意のトークンごとの識別子。 |
|
rh |
あいまいな文字列 | Azure がトークンの再検証に使用する内部要求。 リソースでこの要求を使用しないでください。 | |
ver |
文字列、1.0 または 2.0 |
アクセス トークンのバージョンを示します。 | |
xms_cc |
文字列の JSON 配列 | トークンを取得したクライアント アプリケーションがクレームのチャレンジを処理できるかどうかを示します。 多くの場合、acrs クレームと共に使用されます。 このクレームは、条件付きアクセスと継続的アクセス評価のシナリオでよく使用されます。 トークンの発行対象であるリソース サーバーまたはサービス アプリケーションで、トークン内のこのクレームの存在を制御します。 アクセス トークン内の cp1 の値は、クライアント アプリケーションでクレーム チャレンジを処理できることを識別するための信頼できる方法です。 詳細については、「クレーム チャレンジ、クレーム要求、およびクライアントの機能」を参照してください。 |
グループ超過要求
Microsoft Entra ID では、グループ要求に含まれるオブジェクト ID の数が、HTTP ヘッダーのサイズ制限内に収まるように制限されます。 超過制限 (SAML トークンの場合は 150、JWT トークンの場合は 200、暗黙的フローを使用して発行される場合は 6 のみ) を超えるグループのメンバーにユーザーがなっている場合、Microsoft Entra ID は、グループ要求をトークンに出力しません。 代わりに、Microsoft Graph API に照会してユーザーのグループ メンバーシップを取得するようアプリケーションに指示する超過要求がトークンに追加されます。
{
...
"_claim_names": {
"groups": "src1"
},
"_claim_sources": {
"src1": {
"endpoint": "[Url to get this user's group membership from]"
}
}
...
}
超過のシナリオは、App Creation Scripts フォルダーにある BulkCreateGroups.ps1 を使用してテストします。
Note
返される URL は、Azure AD Graph の URL (つまり、graph.windows.net) になります。 サービスでは、この URL に依存するのではなく、オプションの要求 (トークンがアプリまたはアプリ+ ユーザー トークンのどちらであるかを識別する) を使用 idtyp して、グループの完全な一覧に対してクエリを実行するための Microsoft Graph URL を作成する必要があります。
v1.0 の基本要求
v1.0 トークンには、該当する場合は次の要求が含まれますが、v2.0 トークンには既定では含まれません。 v2.0 に対してこれらの要求を使用するために、アプリケーションの要求では省略可能な要求が使用されます。
| 要求 | フォーマット | 説明 |
|---|---|---|
ipaddr |
String | ユーザーが認証された IP アドレス。 |
onprem_sid |
文字列 (SID 形式) | ユーザーがオンプレミス認証を行った場合、この要求によって SID が提供されます。 レガシ アプリケーションでの承認にこの要求を使用できます。 |
pwd_exp |
int、Unix タイムスタンプ | ユーザーのパスワードの有効期限を示します。 |
pwd_url |
String | ユーザーがパスワードをリセットできる URL。 |
in_corp |
boolean | クライアントが企業ネットワークからサインインしている場合に通知します。 |
nickname |
String | ユーザーの別の名前。姓または名とは別の名前です。 |
family_name |
String | ユーザー オブジェクトで定義されたユーザーの姓を示します。 |
given_name |
String | ユーザー オブジェクトに設定されたユーザーの名を示します。 |
upn |
String | ユーザーのユーザー名。 電話番号、電子メール アドレス、または書式なし文字列を指定できます。 表示目的でのみ使用し、再認証のシナリオでユーザー名のヒントを提供します。 |
amr 要求
ID は、アプリケーションに関連している可能性のあるさまざまな方法で認証できます。 amr 要求は、パスワードと Authenticator アプリの両方を使用した認証用に、複数の項目を格納できる配列 (["mfa", "rsa", "pwd"] など) です。
| 値 | 説明 |
|---|---|
pwd |
パスワード認証。ユーザーの Microsoft パスワードまたはアプリのクライアント シークレット。 |
rsa |
Microsoft Authenticator アプリを使用した認証など、認証が RSA キーの証明に基づいていたことを示します。 この値は、認証にサービス所有の X509 証明書を使用した自己署名 JWT の使用も示します。 |
otp |
電子メールまたはテキスト メッセージを使用したワンタイム パスコード。 |
fed |
フェデレーション認証アサーション (JWT や SAML など) の使用を示します。 |
wia |
Windows 統合認証 |
mfa |
多要素認証の使用を示します。 この要求が存在する場合は、他の認証方法が含まれます。 |
ngcmfa |
mfa と同等です。特定の高度な資格情報の種類のプロビジョニングに使用されます。 |
wiaormfa |
ユーザーが Windows 資格情報または MFA 資格情報を使用して認証されたことを示します。 |
none |
完了した認証がないことを示します。 |
次のステップ
- Microsoft Entra ID で使われるアクセス トークンについて説明します。