オプションの要求のリファレンス
次の処理に省略可能な要求を使用できます。
- アプリケーションのトークンに含める要求を選択する。
- Microsoft ID プラットフォームからトークンで返される特定の要求の動作を変更する。
- アプリケーションのカスタムの要求を追加してアクセスする。
省略可能な要求は v1.0 と v2.0 の両方の形式のトークンと、SAML トークンによってサポートされていますが、それらの価値は、v1.0 から v2.0 に移行する場合に最大限にまで高まります。 Microsoft ID プラットフォームでは、サイズの小さいトークンを使用してクライアントのパフォーマンスを最適化します。 その結果、以前のバージョンではアクセス トークンと ID トークンに含まれていた一部の要求は、v2.0 トークンでは削除されたため、アプリケーションごとに具体的に要求する必要があります。
| アカウントの種類 | v1.0 トークン | v2.0 トークン |
|---|---|---|
| 個人用 Microsoft アカウント | 該当なし | サポートされています |
| Microsoft Entra アカウント | サポートされています | サポートされています |
v1.0 と v2.0 の省略可能な要求セット
既定でアプリケーションが使用できるオプションの要求セットを次の表に示します。 拡張機能属性とディレクトリ拡張機能でカスタム データを使って、アプリケーションの省略可能な要求を追加することができます。 要求をアクセス トークンに追加する場合、アプリケーション (Web API) "に対して" 求められたアクセス トークンに要求が適用されます (アプリケーション "によって" 求められた要求ではありません)。 クライアントがどのように API にアクセスしても、API の認証に使用されるアクセス トークンには適切なデータが存在します。
注意
このような要求の大部分は v1.0 および v2.0 トークンの JWT に含めることができますが、「トークンの種類」列に記載されている場合を除き、SAML トークンに含めることはできません。 "ユーザーの種類" 列でマークされているこれらの要求のサブセットは、コンシューマー アカウントでサポートされます。 記載されている要求の多くは、コンシューマー ユーザーに適用されません (テナントがなく、tenant_ctry の値がないためです)。
次の表に、v1.0 と v2.0 のオプションの要求セットを示します。
| 名前 | 説明 | トークンの種類 | ユーザーの種類 | Notes |
|---|---|---|---|---|
acct |
テナント内のユーザー アカウントの状態 | JWT、SAML | ユーザーがテナントのメンバーである場合、値は 0 です。 ゲストの場合、値は 1 です。 |
|
acrs |
認証コンテキスト ID | JWT | Microsoft Entra ID | ベアラーで実行できる操作の認証コンテキスト ID を示します。 認証コンテキスト ID を使用して、アプリケーションとサービス内からステップアップ認証の要求をトリガーできます。 多くの場合、xms_cc クレームと共に使用されます。 |
auth_time |
ユーザーが最後に認証された時刻。 | JWT | ||
ctry |
ユーザーの国またはリージョン | JWT | この要求は、存在する場合にその値を返します。フィールド値は FR、JP、SZ など、標準の 2 文字の国コードまたはリージョンコードです。 | |
email |
このユーザーの報告されている電子メールアドレス | JWT、SAML | MSA、Microsoft Entra ID | ユーザーがテナントのゲストである場合、この値は既定で含まれます。 マネージド ユーザー (テナント内のユーザー) の場合は、この省略可能な要求により、または OpenID スコープで (v2.0 の場合のみ)、それを要求する必要があります。 この値は正しいとは限りません。また、時間の経過と共に変化する場合があります。認可に使用したり、ユーザーのデータを保存したりすることはできません。 詳細については、「ユーザーがこのデータにアクセスするためのアクセス許可を持っていることを検証する」を参照してください。 認可用にメール クレームを使用している場合は、より安全なクレームへ移行することをお勧めします。 アプリでアドレス指定可能なメール アドレスが必要な場合は、この要求を提案として使用するか、UX に事前に入力して、このデータをユーザーに直接要求します。 |
fwd |
IP アドレス | JWT | 要求側クライアントの元のアドレスを追加します (VNET 内の場合)。 | |
groups |
グループ要求の省略可能な形式 | JWT、SAML | groups 要求は、アプリケーション マニフェストの GroupMembershipClaims 設定 (これも設定が必要) と共に使用されます。 |
|
idtyp |
トークンの種類 | JWT のアクセス トークン | 特殊: アプリ専用アクセス トークンのみ | トークンがアプリ専用トークンの場合、値は app です。 API を使用してトークンがアプリ トークンかアプリ + ユーザー トークンかを判断する場合、この要求が最も正確な方法です。 |
login_hint |
ログイン ヒント | JWT | MSA、Microsoft Entra ID | base64 でエンコードされた非透過的で信頼性の高いログイン ヒント クレーム。 この値は変更しないでください。 この要求は、すべてのフロー内の login_hint OAuth パラメーターで SSO を取得するために使用するのに最適な値です。 アプリケーション間で渡すことにより、SSO をサイレントで実行するのにも役立ちます。アプリケーション A は、あるユーザーにサインインし、login_hint 要求を読み取ってから、アプリケーション B に移動するリンクをユーザーが選んだときに要求と現在のテナント コンテキストをクエリ文字列またはフラグメント内でアプリケーション B に送信できます。競合状態と信頼性の問題を回避するために、login_hint 要求にはユーザーの現在のテナントは含まれ "ません"。使用される場合、既定ではユーザーのホーム テナントになります。 ユーザーが別のテナントからアクセスするゲスト シナリオでは、サインイン要求でテナント ID を指定する必要があります。 そして、パートナーのアプリにも同じテナント ID を渡します。 この要求は、公開されている SDK の既存の login_hint 機能と共に使用することを目的としています。 |
sid |
セッション ID。セッションごとのユーザーのサインアウトに使用されます | JWT | 個人アカウントと Microsoft Entra アカウント。 | |
tenant_ctry |
リソース テナントの国またはリージョン | JWT | 管理者によってテナント レベルで設定されることを除き ctry と同じです。また、標準の 2 文字値にする必要があります。 |
|
tenant_region_scope |
リソースのテナントのリージョン | JWT | ||
upn |
UserPrincipalName | JWT、SAML | "username_hint" パラメーターで使用できるユーザー ID。 そのユーザーの持続的な識別子ではないため、認可やユーザー情報の一意な識別 (データベース キーとして、など) には使用しないでください。 代わりに、ユーザー オブジェクト ID (oid) をデータベース キーとして使用します。 詳しくは、「要求を検証してアプリケーションと API をセキュリティで保護する」をご覧ください。 代替ログイン ID を使用してサインインするユーザーには、ユーザー プリンシパル名 (UPN) は表示されません。 代わりに、サインイン状態をユーザーに表示するには、ID トークン要求 (v1 トークンの場合は preferred_username または unique_name、v2 トークンの場合は preferred_username) を使用します。 この要求は自動的に含まれますが、ゲスト ユーザーの場合に、動作を変更するために他のプロパティを付加するよう、オプションの要求として指定することもできます。 login_hint を使用するには login_hint 要求を使用する必要があります。ユーザーが判読できる識別子 (UPN など) は信頼できません。 |
|
verified_primary_email |
ユーザーの PrimaryAuthoritativeEmail が送信元です | JWT | ||
verified_secondary_email |
ユーザーの SecondaryAuthoritativeEmail が送信元です | JWT | ||
vnet |
VNET 指定子情報。 | JWT | ||
xms_cc |
クライアント機能 | JWT | Microsoft Entra ID | トークンを取得したクライアント アプリケーションがクレームのチャレンジを処理できるかどうかを示します。 多くの場合、acrs クレームと共に使用されます。 このクレームは、条件付きアクセスと継続的アクセス評価のシナリオでよく使用されます。 トークンの発行対象であるリソース サーバーまたはサービス アプリケーションで、トークン内のこのクレームの存在を制御します。 アクセス トークン内の cp1 の値は、クライアント アプリケーションでクレーム チャレンジを処理できることを識別するための信頼できる方法です。 詳細については、「クレーム チャレンジ、クレーム要求、およびクライアントの機能」を参照してください。 |
xms_edov |
ユーザーのメール ドメイン所有者が検証されているかを示すブール値。 | JWT | ユーザー アカウントが存在するテナントに属し、かつテナント管理者がドメインを検証済みの場合、メールはドメイン検証済みと見なされます。 また、メールは Microsoft アカウント (MSA)、Google アカウント、またはワンタイム パスコード (OTP) フローを使用した認証で使用されている必要があります。 Facebook アカウントと SAML/WS-Fed アカウントには、検証済みドメインがありません。 この要求をトークンで返すには、email 要求の存在が必要です。 |
|
xms_pdl |
優先されるデータの場所 | JWT | Multi-Geo テナントの場合、優先されるデータの場所は、ユーザーがどの地域にいるかを示す 3 文字のコードです。 詳細については、優先されるデータの場所に関する Microsoft Entra Connect のドキュメントを参照してください。 | |
xms_pl |
ユーザーの優先する言語 | JWT | ユーザーの優先する言語 (設定されている場合)。 ゲスト アクセスのシナリオの場合、ソースはホーム テナントです。 LL-CC ("en-us") という形式です。 | |
xms_tpl |
テナントの優先する言語 | JWT | リソース テナントの優先する言語 (設定されている場合)。 LL ("en") という形式です。 | |
ztdid |
ゼロタッチ デプロイ ID | JWT | Windows AutoPilot に使用されるデバイス ID。 |
警告
email または upn クレーム値を使用して、保存したり、アクセス トークン内のユーザーがデータにアクセスできるかどうかを判断したりしないでください。 このような変更可能な要求値は時間の経過と共に変わることがあり、認可のために安全ではなくなり、信頼性が低くなくなります。
v2.0 固有の省略可能な要求セット
これらの要求は常に v1.0 トークンに含まれますが、要求されない限り v2.0 トークンには含まれません。 これらの要求は、JWT (ID トークンとアクセス トークン) にのみ適用されます。
| JWT の要求 | 名前 | 説明 | Notes |
|---|---|---|---|
ipaddr |
IP アドレス | ログインしたクライアントの IP アドレス。 | |
onprem_sid |
オンプレミスのセキュリティ ID | ||
pwd_exp |
パスワードの有効期限 | iat 要求の時刻から、パスワード有効期限が切れるまでの期間を示す秒数。 この要求は、パスワードの有効期限が間もなく切れる場合にのみ含められます (パスワード ポリシーの "通知日" で定義されています)。 |
|
pwd_url |
パスワードの変更 URL | ユーザーがパスワードを変更するためにアクセスできる URL。 この要求は、パスワードの有効期限が間もなく切れる場合にのみ含められます (パスワード ポリシーの "通知日" で定義されています)。 | |
in_corp |
企業ネットワーク内 | クライアントが企業ネットワークからログインしている場合に通知します。 そうでない場合、この要求は含まれません。 | MFA の信頼できる IP の設定に基づきます。 |
family_name |
姓 | ユーザー オブジェクトで定義されたユーザーの姓を示します。 たとえば、"family_name":"Miller" のようにします。 |
MSA と Microsoft Entra ID でサポートされます。 profile スコープが必要です。 |
given_name |
名 | ユーザー オブジェクトに設定されたユーザーの名を示します。 たとえば、"given_name": "Frank" のようにします。 |
MSA と Microsoft Entra ID でサポートされます。 profile スコープが必要です。 |
upn |
ユーザー プリンシパル名 | "username_hint" パラメーターで使用できるユーザー ID。 そのユーザーの持続的な識別子ではないため、認可やユーザー情報の一意な識別 (データベース キーとして、など) には使用しないでください。 詳しくは、「要求を検証してアプリケーションと API をセキュリティで保護する」をご覧ください。 代わりに、ユーザー オブジェクト ID (oid) をデータベース キーとして使用します。 代替ログイン ID を使用してサインインするユーザーには、ユーザー プリンシパル名 (UPN) は表示されません。 代わりに、次の preferred_username 要求を使用して、ユーザーにサインイン状態を表示します。 |
profile スコープが必要です。 |
v1.0 固有の省略可能な要求セット
v2 トークン形式の機能強化の一部は、セキュリティと信頼性の向上に役立つため、v1 トークン形式を使用するアプリで利用できます。 これらの機能強化は、SAML トークンではなく JWT のみに適用されます。
| JWT の要求 | 名前 | 説明 | Notes |
|---|---|---|---|
aud |
対象ユーザー | JWT には常に存在しますが、v1 アクセス トークンでは、リソースのクライアント ID と、任意の appID URI、末尾にスラッシュがある場合とない場合など、さまざまな方法で出力することができます。 このランダム化は、トークンの検証を実行するときに、コーディングが困難になる場合があります。 additionalProperties をこの要求に使用すると、常に v1 アクセス トークン内リソースのクライアント ID が確実に設定されるようになります。 |
v1 JWT アクセス トークンのみ |
preferred_username |
推奨ユーザー名 | v1 トークン内の優先ユーザー名要求を提供します。 この要求により、トークンの種類に関係なく、アプリでユーザー名のヒントを提供したり、人間が判読できる表示名を表示したりするのが簡単になります。 upn や unique_name を使用する代わりに、このオプションの要求を使用することをお勧めします。 |
v1 ID トークンとアクセス トークン |
オプションの要求の additionalProperties
一部の省略可能な要求は、要求が返される方法を変更するように構成することができます。 これらの additionalProperties は、ほとんどの場合、さまざまなデータが見込まれるオンプレミス アプリケーションの移行を支援するために使用されます。 たとえば、include_externally_authenticated_upn_without_hash は UPN 内のハッシュ マーク (#) を処理できないクライアントに役立ちます。
| プロパティ名 | additionalProperty 名 |
説明 |
|---|---|---|
upn |
SAML 応答と JWT 応答の両方や、v1.0 および v2.0 トークンに使用できます。 | |
include_externally_authenticated_upn |
リソース テナントに格納されているゲスト UPN が含まれます。 たとえば、「 foo_hometenant.com#EXT#@resourcetenant.com 」のように入力します。 |
|
include_externally_authenticated_upn_without_hash |
ハッシュ マーク (#) がアンダースコア (_) に置き換えられる点を除き、前述の一覧と同じです。例: foo_hometenant.com_EXT_@resourcetenant.com。 |
|
aud |
v1 アクセス トークンでは、この要求は aud 要求の形式を変更するために使用されます。 この要求は v2 トークンまたはいずれかのバージョンの ID トークンに影響がありません。ここで、aud 要求は常にクライアント ID です。 この構成を使用すると、API による対象ユーザーの検証が確実により簡単になります。 リソースはアクセス トークンを所有しているので、要求内のリソースでは、アクセス トークンに影響を与えるすべての省略可能なクレームと同様に、この省略可能なクレームも設定する必要があります。 |
|
use_guid |
リソース (API) のクライアント ID を GUID 形式で aud 要求として常に生成します。これはランタイム依存ではありません。 たとえば、リソースによってこのフラグが設定され、そのクライアント ID が 00001111-aaaa-2222-bbbb-3333cccc4444 の場合、そのリソースのアクセス トークンを要求するすべてのアプリは、aud : 00001111-aaaa-2222-bbbb-3333cccc4444 を含むアクセス トークンを受け取ります。 この要求が設定されていない場合、API は aud 要求に、api://MyApi.com、api://MyApi.com/、api://myapi.com/AdditionalRegisteredField、またはその API のアプリ ID URI として設定されたその他の値、およびリソースのクライアント ID が設定されたトークンを取得します。 |
|
idtyp |
この要求は、トークンの種類 (アプリ、ユーザー、デバイス) を取得するために使用されます。 既定では、アプリ専用トークンに対してのみ出力されます。 リソースはアクセス トークンを所有しているので、要求内のリソースでは、アクセス トークンに影響を与えるすべての省略可能なクレームと同様に、この省略可能なクレームも設定する必要があります。 | |
include_user_token |
ユーザー トークンの idtyp 要求を出力します。 idtyp 要求セットにこの省略可能な追加のプロパティがない場合、API によりアプリ トークンの要求のみが取得されます。 |
additionalProperties の例
"optionalClaims": {
"idToken": [
{
"name": "upn",
"essential": false,
"additionalProperties": [
"include_externally_authenticated_upn"
]
}
]
}
この optionalClaims オブジェクトにより、クライアントに返される ID トークンに、他のホーム テナントとリソース テナントの情報を持つ upn 要求が含まれます。 トークンの upn 要求は、ユーザーが (認証に異なる IDP を使用する) テナントのゲストである場合にのみ変更されます。
関連項目
次の手順
- オプションの要求の構成の詳細を確認します。