省略可能な要求の構成

[アーティクル]
06/10/2024

Microsoft Entra によって返されるトークンは、それを要求するクライアントが最適なパフォーマンスを実現できるように、小さく抑えられます。その結果、一部の要求が規定ではトークンに存在しなくなり、アプリケーションごとに特定して要求する必要があります。

Microsoft Entra 管理センターのアプリケーション UI またはマニフェストを使用して、アプリケーションの省略可能な要求を構成できます。

前提条件

アクティブなサブスクリプションが含まれる Azure アカウント。無料でアカウントを作成できます。
次の項目の完了: 「クイックスタート: アプリケーションを登録する」

アプリケーションで省略可能な要求を構成する

クラウドアプリケーション管理者以上として Microsoft Entra 管理センターにサインインします。
[ID]>[アプリケーション]>[アプリの登録] に移動します。
シナリオと目的の結果に基づいて、オプションの要求を構成するアプリケーションを選択します。

アプリ UI を使って続行する
マニフェストを使って続行する

[管理] で、 [トークン構成] を選択します。
[省略可能な要求を追加] を選択します。
構成するトークンの種類 ([アクセス] など) を選択します。
追加する省略可能な要求を選択します。
[追加] を選択します。

[管理] で、 [マニフェスト] を選択します。 Web ベースのマニフェストエディターが開き、マニフェストを編集できます。必要があれば、 [ダウンロード] を選択してローカルでマニフェストを編集します。その後、 [アップロード] を使用して、アプリケーションにマニフェストを再適用します。ファイルに optionalClaims プロパティが含まれていない場合は、追加できます。

次のアプリケーションマニフェストのエントリにより、auth_time、ipaddr、upn の省略可能な要求が、ID、アクセス、および SAML トークンに追加されます。
```
"optionalClaims": {
    "idToken": [
        {
            "name": "auth_time",
            "essential": false
        }
    ],
    "accessToken": [
        {
            "name": "ipaddr",
            "essential": false
        }
    ],
    "saml2Token": [
        {
            "name": "upn",
            "essential": false
        },
        {
            "name": "extension_ab603c56068041afb2f6832e2a17e237_skypeId",
            "source": "user",
            "essential": false
        }
    ]
}
```
終わったら、 [保存] を選択します。これで、指定されたオプションの要求がアプリケーションのトークンに含まれるようになります。

optionalClaims オブジェクトは、アプリケーションから要求されるオプションの要求を宣言します。アプリケーションは、ID トークン、アクセストークン、SAML 2 トークンで返される、オプションの要求を構成できます。アプリケーションは、トークンの種類ごとに返される異なる省略可能な要求セットを構成できます。

名前	種類	説明
`idToken`	コレクション	JWT ID トークンで返される省略可能な要求。
`accessToken`	コレクション	JWT アクセストークンで返される省略可能な要求。
`saml2Token`	コレクション	JWT SAML トークンで返される省略可能な要求。

特定の要求でサポートされている場合は、"additionalProperties" フィールドを使用してオプションの要求の動作を変更することもできます。

名前	種類	説明
`name`	Edm.String	省略可能な要求の名前。
`source`	Edm.String	要求のソース (ディレクトリオブジェクト)。定義済みの要求と、拡張プロパティのユーザー定義の要求があります。ソース値が null の場合、この要求は定義済みの省略可能な要求です。ソース値が user の場合、name プロパティの値はユーザーオブジェクトの拡張プロパティです。
`essential`	Edm.Boolean	値が true の場合、エンドユーザーから要求された特定のタスクの承認エクスペリエンスを円滑にするために、クライアントに指定された要求が必要です。既定値は false です。
`additionalProperties`	コレクション (Edm.String)	要求のその他プロパティ。このコレクションにプロパティが存在する場合、name プロパティに指定された省略可能な要求の動作が変更されます。

ディレクトリ拡張機能のオプションの要求を構成する

標準の省略可能な要求セットに加え、Microsoft Graph 拡張機能を含むようにトークンを構成することもできます。詳しくは、「拡張機能を使用してカスタムデータをリソースに追加する」をご覧ください。

重要

アクセストークンは、クライアントではなく、常にリソースのマニフェストを使用して生成されます。 ...scope=https://graph.microsoft.com/user.read... の要求では、リソースは Microsoft Graph API です。アクセストークンは、クライアントのマニフェストではなく、Microsoft Graph API マニフェストを使用して作成されます。アプリケーションのマニフェストを変更しても、Microsoft Graph API のトークンは変更されません。 accessToken の変更が反映されたことを検証するには、他のアプリではなく、自分のアプリケーションにトークンを要求します。

オプションの要求では、拡張機能の属性と、ディレクトリ拡張機能がサポートされます。この機能は、アプリで使用できるユーザー情報をさらに加える場合に便利です。たとえば、ユーザーが設定したその他の識別子や、重要な構成オプションなどです。アプリケーションマニフェストがカスタム拡張機能を要求し、MSA ユーザーがアプリにログインした場合、これらの拡張機能は返されません。

ディレクトリ拡張の形式

アプリケーションマニフェストを使用してディレクトリ拡張機能の省略可能な要求を構成する場合は、拡張機能の完全な名前 (形式: extension_<appid>_<attributename>) を使用します。 <appid> は、この要求を必須とするアプリケーションの appId (またはクライアント ID) が削除されたバージョンです。

JWT 内では、このような要求は extn.<attributename> という形式の名前で発行されます。 SAML トークン内では、このような要求は http://schemas.microsoft.com/identity/claims/extn.<attributename> という形式の URI で発行されます。

グループのオプションの要求を構成する

ヒント

この記事の手順は、開始するポータルによって若干異なる場合があります。

このセクションでは、グループ要求で使用されるグループ属性を、既定のグループ objectID からオンプレミス Windows Active Directory から同期される属性へ変更するための、省略可能な要求の構成オプションについて説明します。 Azure portal またはアプリケーションマニフェストを使用して、アプリケーション用にグループのオプションの要求を構成できます。ユーザープリンシパルのグループの省略可能なクレームのみが、JWT 内に出力されます。サービスプリンシパルは、JWT で出力されるグループのオプションの要求には含まれません。

重要

トークンで出力されるグループの数は、SAML アサーションの場合は 150、JWT の場合は 200 (入れ子になったグループを含む) に制限されます。グループ制限と、オンプレミス属性からのグループ要求に関する重要な注意事項などについて詳しくは、「アプリケーションに対するグループ要求を構成する」をご覧ください。

Azure portal を使用してグループのオプションの要求を構成するには、次の手順を実行します。

オプションの要求を構成するアプリケーションを選択します。
[管理] で、 [トークン構成] を選択します。
[Add groups claim](グループの要求の追加) を選択します。
返すグループの種類を選択します ([セキュリティグループ]、または [ディレクトリロール]、[すべてのグループ]、または [アプリケーションに割り当てられているグループ]):
- [アプリケーションに割り当てられているグループ] オプションには、アプリケーションに割り当てられたグループのみが含まれます。トークンのグループ数の制限により、 アプリケーションオプションに割り当てられた グループが大規模な組織に推奨されます。アプリケーションに割り当てられているグループを変更するには、[エンタープライズアプリケーション] リストからアプリケーションを選択します。 [ユーザーとグループ]、[ユーザーまたはグループの追加] の順に選択します。 ユーザーとグループ からアプリケーションに追加するグループを選択します。
- [すべてのグループ] オプションには、SecurityGroup、DirectoryRole、および DistributionList が含まれますが、 [アプリケーションに割り当てられているグループ] は含まれません。
省略可能: 特定のトークンの種類のプロパティを選択して、オンプレミスのグループ属性を含めるようにグループの要求値を変更したり、要求の種類をロールに変更したりします。
[保存] を選択します。

アプリケーションマニフェストを使用してグループのオプションの要求を構成するには、次の手順を実行します。

オプションの要求を構成するアプリケーションを選択します。
[管理] で、 [マニフェスト] を選択します。
マニフェストエディターを使用して、次のエントリを追加します。

有効な値は次のとおりです。
- "All" (このオプションには [SecurityGroup]、[DirectoryRole]、および [DistributionList] が含まれます)
- "SecurityGroup"
- "DirectoryRole"
- "ApplicationGroup " (このオプションには、アプリケーションに割り当てられているグループのみが含まれます)
次に例を示します。
```
"groupMembershipClaims": "SecurityGroup"
```
既定では、グループのオブジェクト ID は、グループ要求の値に出力されます。オンプレミスグループ属性を含むように要求の値を変更する、または要求の種類をロールに変更するには、次のように optionalClaims 構成を使用します。

グループ名の構成を [optional claims](オプションの要求) に設定します。

トークン内のグループに、[オプションの要求] セクションのオンプレミスグループ属性を含める場合は、オプションの要求を適用する必要があるトークンの種類を指定します。また、要求されるオプションの要求の名前と、必要なその他プロパティも指定します。

次に示す複数のトークンの種類が、一覧に表示される可能性があります。

idToken (OIDC ID トークンの場合)
accessToken (OAuth アクセストークンの場合)
Saml2Token (SAML トークンの場合)。

Saml2Token の種類は、SAML 1.1と SAML 2.0 の両方の形式のトークンに適用されます。

関連する各トークンの種類に対して、マニフェストの optionalClaims セクションを使用するようにグループ要求を変更します。 optionalClaims スキーマは次のとおりです。

{
    "name": "groups",
    "source": null,
    "essential": false,
    "additionalProperties": []
}

省略可能な要求のスキーマ	値
`name`	`groups` である必要があります。
`source`	使用されていません。省略するか、null 値を指定します。
`essential`	使用されていません。省略するか、false を指定します。
`additionalProperties`	その他プロパティの一覧。有効なオプションは`sam_account_name`、`dns_domain_and_sam_account_name`、`netbios_domain_and_sam_account_name`、`emit_as_roles`、`cloud_displayname`です。

additionalProperties では、sam_account_name、dns_domain_and_sam_account_name、netbios_domain_and_sam_account_name のいずれか 1 つのみが必須です。複数ある場合、最初の 1 つが使用され、それ以外は無視されます。また、cloud_displayname を追加して、クラウドグループの表示名を出力することもできます。このオプションは groupMembershipClaims が ApplicationGroup に設定されている場合にのみ機能します。

アプリケーションによっては、ロール要求内にユーザーに関するグループ情報が必要になります。要求の種類をグループ要求からロール要求に変更するには、emit_as_roles を additionalProperties に追加します。グループの値が、ロール要求内に出力されます。

emit_as_roles が使用された場合、ユーザー (またはリソースアプリケーション) が割り当て済みとして構成されているアプリケーションロールは、ロール要求に含まれません。

次の例は、グループ要求のマニフェスト構成を示しています。

dnsDomainName\sAMAccountName の形式で、OAuth アクセストークンのグループ名としてグループを出力します。

"optionalClaims": {
    "accessToken": [
        {
            "name": "groups",
            "additionalProperties": [
                "dns_domain_and_sam_account_name"
            ]
        }
    ]
}

SAML および OIDC ID のトークンでロール要求として netbiosDomain\sAMAccountName 形式で返されるグループ名を出力します。

"optionalClaims": {
    "saml2Token": [
        {
            "name": "groups",
            "additionalProperties": [
                "netbios_domain_and_sam_account_name",
                "emit_as_roles"
            ]
        }
    ],
    "idToken": [
        {
            "name": "groups",
            "additionalProperties": [
                "netbios_domain_and_sam_account_name",
                "emit_as_roles"
            ]
        }
    ]
}

オンプレミス同期グループの sam_account_name 形式のグループ名、SAML クラウドグループの cloud_display 名、アプリケーションに割り当てられたグループの OIDC ID トークンを出力します。

"groupMembershipClaims": "ApplicationGroup",
"optionalClaims": {
    "saml2Token": [
        {
            "name": "groups",
            "additionalProperties": [
                "sam_account_name",
                "cloud_displayname"
            ]
        }
    ],
    "idToken": [
        {
            "name": "groups",
            "additionalProperties": [
                "sam_account_name",
                "cloud_displayname"
            ]
        }
    ]
}

省略可能な要求の例

アプリケーションの ID 構成に関するプロパティを更新し、省略可能な要求を有効にして構成するには、複数のオプションがあります。

Azure portal で実行できます
マニフェストを使用できます。
また、Microsoft Graph API を使用してアプリケーションを更新するアプリケーションを作成することもできます。 Microsoft Graph API リファレンスガイドにある OptionalClaims という種類を使用すると、省略可能な要求の構成に役立ちます。

次の例では、Azure portal とマニフェストを使用して、アプリケーション用のアクセス、ID、SAML トークンにオプションの要求を追加します。アプリケーションが受け取ることができるトークンの型ごとに、さまざまなオプションの要求が追加されます。

ID トークンには、完全な形式 (<upn>_<homedomain>#EXT#@<resourcedomain>) でフェデレーションユーザーの UPN が含まれます。
他のクライアントがこのアプリケーションに要求するアクセストークンには、auth_time 要求が含まれます。
SAML トークンには skypeId ディレクトリスキーマ拡張機能が含まれます (この例では、このアプリの ID は ab603c56068041afb2f6832e2a17e237 です)。 SAML トークンは Skype ID を extension_ab603c56068041afb2f6832e2a17e237_skypeId として公開します。

Azure portal で要求を構成します。

オプションの要求を構成するアプリケーションを選択します。
[管理] で、 [トークン構成] を選択します。
[省略可能な要求の追加] を選択し、 [ID] トークンの型を選択して、要求の一覧から [upn] を選択し、 [追加] を選択します。
[省略可能な要求の追加] を選択し、 [アクセス] トークンの型を選択して、要求の一覧から auth_time を選択し、 [追加] を選択します。
[トークン構成の概要] 画面で、 [upn] の横にある鉛筆アイコンを選択し、 [外部で認証された] の切り替えを選択して、 [保存] を選択します。
[省略可能な要求の追加] を選択し、[SAML] トークンの型を選択して、要求の一覧から [extn. skypeID] を選択し (skypeID という Microsoft Entra ユーザーオブジェクトを作成した場合にのみ適用されます)、[追加] を選択します。

マニフェストで要求を構成します。

オプションの要求を構成するアプリケーションを選択します。
[管理] で、 [マニフェスト] を選択してインラインマニフェストエディターを開きます。

このエディターを使用して、マニフェストを直接編集できます。マニフェストは、アプリケーションエンティティのスキーマに従っています。保存されると、マニフェストの書式が自動的に構成されます。新しい要素が optionalClaims プロパティに追加されます。

"optionalClaims": {
    "idToken": [
        {
            "name": "upn",
            "essential": false,
            "additionalProperties": [
                "include_externally_authenticated_upn"
            ]
        }
    ],
    "accessToken": [
        {
            "name": "auth_time",
            "essential": false
        }
    ],
    "saml2Token": [
        {
            "name": "extension_ab603c56068041afb2f6832e2a17e237_skypeId",
            "source": "user",
            "essential": true
        }
    ]
}

マニフェストの更新が完了したら、 [保存] を選択してマニフェストを保存します。

次の方法で共有

省略可能な要求の構成

前提条件

アプリケーションで省略可能な要求を構成する

ディレクトリ拡張機能のオプションの要求を構成する

ディレクトリ拡張の形式

グループのオプションの要求を構成する

省略可能な要求の例

フィードバック

その他のリソース

次の方法で共有

省略可能な要求の構成

前提条件

アプリケーションで省略可能な要求を構成する

ディレクトリ拡張機能のオプションの要求を構成する

ディレクトリ拡張の形式

グループのオプションの要求を構成する

省略可能な要求の例

関連するコンテンツ

フィードバック

その他のリソース