省略可能な要求の構成

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

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

前提条件

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

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

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

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

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

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

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

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

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

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

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

1. オプションの要求を構成するアプリケーションを選択します。

2. [管理] で、 [マニフェスト] を選択します。

3. マニフェスト エディターを使用して、次のエントリを追加します。

   有効な値は次のとおりです。

   • "All" (このオプションには [SecurityGroup]、[DirectoryRole]、および [DistributionList] が含まれます)
   • "SecurityGroup"
   • "DirectoryRole"
   • "ApplicationGroup " (このオプションには、アプリケーションに割り当てられているグループのみが含まれます)

   次に例を示します。

   "groupMembershipClaims": "SecurityGroup"
   

   既定では、グループのオブジェクト ID は、グループ要求の値に出力されます。 オンプレミス グループ属性を含むように要求の値を変更する、または要求の種類をロールに変更するには、次のように optionalClaims 構成を使用します。

4. グループ名の構成を [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 で要求を構成します。

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

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

1. オプションの要求を構成するアプリケーションを選択します。

2. [管理] で、 [マニフェスト] を選択してインライン マニフェスト エディターを開きます。

3. このエディターを使用して、マニフェストを直接編集できます。 マニフェストは、アプリケーション エンティティのスキーマに従っています。保存されると、マニフェストの書式が自動的に構成されます。 新しい要素が 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
           }
       ]
   }
   

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

制限事項

アプリケーションは、省略可能な要求として最大 10 個の拡張属性を発行できます。

関連するコンテンツ

• アクセス トークン
• アプリケーション マニフェスト
• ID トークン
• オプションの要求のリファレンス