次の方法で共有


省略可能な要求の構成

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

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

前提条件

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

  1. クラウド アプリケーション管理者以上として Microsoft Entra 管理センターにサインインします。
  2. [ID]>[アプリケーション]>[アプリの登録] に移動します。
  3. シナリオと目的の結果に基づいて、オプションの要求を構成するアプリケーションを選択します。
  1. [管理] で、 [トークン構成] を選択します。
  2. [省略可能な要求を追加] を選択します。
  3. 構成するトークンの種類 ([アクセス] など) を選択します。
  4. 追加する省略可能な要求を選択します。
  5. [追加] を選択します。

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 を使用してグループのオプションの要求を構成するには、次の手順を実行します。

  1. オプションの要求を構成するアプリケーションを選択します。
  2. [管理] で、 [トークン構成] を選択します。
  3. [Add groups claim](グループの要求の追加) を選択します。
  4. 返すグループの種類を選択します ([セキュリティ グループ]、または [ディレクトリ ロール][すべてのグループ]、または [アプリケーションに割り当てられているグループ]):
    • [アプリケーションに割り当てられているグループ] オプションには、アプリケーションに割り当てられたグループのみが含まれます。 トークンのグループ数の制限により、 アプリケーション オプションに割り当てられた グループが大規模な組織に推奨されます。 アプリケーションに割り当てられているグループを変更するには、[エンタープライズ アプリケーション] リストからアプリケーションを選択します。 [ユーザーとグループ][ユーザーまたはグループの追加] の順に選択します。 ユーザーとグループ からアプリケーションに追加する グループを選択します。
    • [すべてのグループ] オプションには、SecurityGroupDirectoryRole、および 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_namedns_domain_and_sam_account_namenetbios_domain_and_sam_account_nameemit_as_rolescloud_displaynameです。

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

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

    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. マニフェストの更新が完了したら、 [保存] を選択してマニフェストを保存します。