省略可能な要求参照
省略可能な要求を使用すると、次のことができます。
- アプリケーションのトークンに含める要求を選択します。
- Microsoft ID プラットフォームがトークンで返す特定の要求の動作を変更します。
- アプリケーションのカスタム要求を追加してアクセスします。
オプションの要求は、v1.0 形式のトークンと v2.0 形式のトークンと SAML トークンの両方でサポートされますが、v1.0 から v2.0 への移行時にほとんどの値が提供されます。 Microsoft ID プラットフォームでは、クライアントによる最適なパフォーマンスを確保するために、小さいトークン サイズが使用されます。 その結果、以前はアクセス トークンと ID トークンに含まれていたクレームがいくつか v2.0 トークンに存在しなくなり、特にアプリケーションごとに要求する必要があります。
| アカウントの種類 | v1.0 トークン | v2.0 トークン |
|---|---|---|
| 個人用 Microsoft アカウント | N/A | サポート |
| Microsoft Entra アカウント | サポート | サポート |
v1.0 と v2.0 の省略可能な要求セット
アプリケーションが使用するために既定で使用できる省略可能な要求のセットを次の表に示します。 拡張属性とディレクトリ拡張機能でカスタム データを使用して、アプリケーションの省略可能な要求を追加できます。 アクセス トークンに要求を追加すると、要求は、アプリケーション によって要求された要求
手記
これらの要求の大部分は、v1.0 および v2.0 トークンの JWT に含めることができますが、[トークンの種類] 列に記載されている場合を除き、SAML トークンには含まれません。 コンシューマー アカウントは、[ユーザーの種類] 列にマークされた、これらの要求のサブセットをサポートします。 一覧表示されている要求の多くはコンシューマー ユーザーには適用されません (テナントがないため、tenant_ctry には値がありません)。
次の表に、v1.0 と v2.0 の省略可能な要求セットを示します。
| 名前 | 形容 | トークンの種類 | ユーザーの種類 | 筆記 |
|---|---|---|---|---|
acct |
テナントのユーザー アカウントの状態 | JWT、SAML | ユーザーがテナントのメンバーである場合、値は 0。 ゲストの場合、値は 1です。 |
|
acrs |
認証コンテキスト ID | JWT | Microsoft Entra ID | ベアラーが実行できる操作の認証コンテキスト ID を示します。 認証コンテキスト ID を使用して、アプリケーションとサービス内からステップアップ認証の要求をトリガーできます。 多くの場合、xms_cc 要求と共に使用されます。 |
auth_time |
ユーザーが最後に認証された時刻。 | JWT | ||
ctry |
ユーザーの国/地域 | JWT | この要求が存在し、フィールドの値が標準の 2 文字の国/地域コード (FR、JP、SZ など) である場合に返されます。 | |
email |
このユーザーの報告された電子メール アドレス | JWT、SAML | MSA、Microsoft Entra ID | ユーザーがテナントのゲストである場合、この値は既定で含まれます。 マネージド ユーザー (テナント内のユーザー) の場合は、この省略可能な要求を通じて要求するか、v2.0 でのみ OpenID スコープで要求する必要があります。 この値は正しいことは保証されておらず、時間の経過と同時に変更可能です。承認やユーザーのデータの保存には使用しないでください。 詳細については、「このデータにアクセスする権限をユーザーが持っているかどうかを検証する」を参照してください。 承認に電子メール要求を使用している場合は、より安全な要求に移行 |
fwd |
IPアドレス | JWT | 要求元のクライアントの元のアドレスを追加します (VNET 内の場合)。 | |
groups |
グループ要求のオプションの書式設定 | JWT、SAML |
groups 要求は、アプリケーション マニフェストの GroupMembershipClaims 設定と共に使用されます。この設定も必要です。 |
|
idtyp |
トークンの種類 | JWT アクセス トークン | 特殊: アプリ専用アクセス トークン内のみ | トークンがアプリ専用トークンの場合、値は app されます。 この要求は、API がトークンがアプリ トークンかアプリ +ユーザー トークンかを判断するための最も正確な方法です。 |
login_hint |
ログイン ヒント | JWT | MSA、Microsoft Entra ID | base 64 でエンコードされた不透明で信頼性の高いログイン ヒント要求。 この値は変更しないでください。 この要求は、SSO を取得するためにすべてのフローで login_hint OAuth パラメーターに使用するのに最適な値です。 アプリケーション間で渡して、アプリケーション間でサイレント SSO を支援することもできます。アプリケーション A は、ユーザーのサインイン、login_hint 要求の読み取り、アプリケーション B へのリンクをユーザーが選択したときにクエリ文字列またはフラグメント内のアプリケーション B に要求と現在のテナント コンテキストを送信できます。競合状態と信頼性の問題を回避するために、login_hint 要求 には、ユーザーの現在のテナントが含まれていない、既定ではユーザーのホーム テナントが使用されます。 ユーザーが別のテナントから来たゲスト シナリオでは、サインイン要求でテナント識別子を指定する必要があります。 を使用して、パートナーのアプリに同じ情報を渡します。 この要求は、SDK の既存の login_hint 機能で使用することを目的としていますが、公開されています。 |
tenant_ctry |
リソース テナントの国/リージョン | JWT | 管理者がテナント レベルで設定する場合を除き、ctry と同じです。また、標準の 2 文字の値にする必要があります。 |
|
tenant_region_scope |
リソース テナントのリージョン | JWT | ||
upn |
UserPrincipalName | JWT、SAML |
username_hint パラメーターで使用できるユーザーの識別子。 ユーザーの永続的な識別子ではなく、承認やユーザー情報を一意に識別するために使用しないでください (データベース キーなど)。 代わりに、データベース キーとしてユーザー オブジェクト 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 | 複数地域テナントの場合、優先されるデータの場所は、ユーザーが存在する地理的リージョンを示す 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 要求 | 名前 | 形容 | 筆記 |
|---|---|---|---|
ipaddr |
IPアドレス | クライアントがログインした IP アドレス。 | |
onprem_sid |
オンプレミスのセキュリティ識別子 | ||
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 パラメーターで使用できるユーザーの識別子。 ユーザーの永続的な識別子ではなく、承認やユーザー情報を一意に識別するために使用しないでください (データベース キーなど)。 詳細については、「要求を検証してアプリケーションと API をセキュリティで保護する」を参照してください。 代わりに、データベース キーとしてユーザー オブジェクト ID (oid) を使用します。
代替ログイン ID を使用してサインインするユーザーには、ユーザー プリンシパル名 (UPN) を表示しないでください。 代わりに、次の preferred_username 要求を使用して、ユーザーにサインイン状態を表示します。 |
profile スコープが必要です。 |
v1.0 固有の省略可能な要求セット
v2 トークン形式の機能強化の一部は、セキュリティと信頼性の向上に役立つため、v1 トークン形式を使用するアプリで利用できます。 これらの機能強化は、SAML トークンではなく JWT にのみ適用されます。
| JWT 要求 | 名前 | 形容 | 筆記 |
|---|---|---|---|
aud |
聴衆 | JWT には常に存在しますが、v1 アクセス トークンでは、さまざまな方法で出力できます。つまり、appID URI、末尾のスラッシュの有無、リソースのクライアント ID などです。 このランダム化は、トークン検証の実行時にコーディングが困難になる場合があります。 この要求の 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 は、api://MyApi.com、api://MyApi.com/、api://myapi.com/AdditionalRegisteredField、またはその API のアプリ ID URI として設定されたその他の値、およびリソースのクライアント ID の aud 要求を持つトークンを取得できます。 |
|
idtyp |
この要求は、トークンの種類 (アプリ、ユーザー、デバイス) を取得するために使用されます。 既定では、アプリ専用トークンに対してのみ出力されます。 アクセス トークンに影響を与えるすべての省略可能な要求と同様に、リソースはアクセス トークンを所有しているため、要求内のリソースはこの省略可能な要求を設定する必要があります。 | |
include_user_token |
ユーザー トークンの idtyp 要求を出力します。 idtyp 要求セットにこの省略可能な追加プロパティがない場合、API はアプリ トークンの要求のみを取得します。 |
additionalProperties の例
"optionalClaims": {
"idToken": [
{
"name": "upn",
"essential": false,
"additionalProperties": [
"include_externally_authenticated_upn"
]
}
]
}
この optionalClaims オブジェクトにより、クライアントに返された ID トークンに、もう一方のホーム テナントとリソース テナントの情報を含む upn 要求が含まれます。
upn 要求は、ユーザーがテナント内のゲスト (認証に別の IDP を使用する) の場合にのみ、トークンで変更されます。
関連項目
次の手順
- 省略可能な要求の構成
の詳細について説明します。