Microsoft Entra ID を使用してアプリケーションのグループ要求を構成する

[アーティクル]
11/06/2023

Microsoft Entra ID では、アプリケーション内で使用するユーザーグループのメンバーシップ情報をトークンで提供できます。この機能では、次の 3 つの主なパターンがサポートされています。

Microsoft Entra オブジェクト識別子 (OID) 属性によって識別されるグループ
Active Directory に同期されたグループとユーザーの sAMAccountName または GroupSID 属性によって識別されるグループ
クラウド専用グループの表示名属性で識別されるグループ

重要

トークンで出力されるグループの数は、SAML アサーションの場合は 150、JWT の場合は 200 (入れ子になったグループを含む) に制限されます。大規模な組織では、トークンでグループ要求を出力する前に、ユーザーがメンバーになっているグループの数が、Microsoft Entra ID で適用される制限を超える可能性があります。この制限を超えると、Microsoft Entra ID はトークンでのグループ要求の送信を完全に省略します。これらの制限に対する回避策については、この機能に関する重要な注意事項を参照してください。

この機能に関する重要な注意点

オンプレミスから同期される sAMAccountName およびセキュリティ識別子 (SID) の属性の使用に関するサポートは、Active Directory フェデレーションサービス (AD FS) およびその他の ID プロバイダーからの既存のアプリケーションの移動を有効にするように設計されています。 Microsoft Entra ID 内で管理されるグループには、これらの要求を発行するために必要な属性は含まれていません。
ユーザーが多数のグループメンバーシップを持っている場合にグループ数の制限を回避するために、要求で出力されるグループをアプリケーションの関連グループに制限できます。 JWT トークンと SAML トークン用にアプリケーションに割り当てられたグループの出力の詳細を参照してください。アプリケーションにグループを割り当てられない場合は、要求で出力されるグループの数を減らすためにグループフィルターを構成することもできます。グループフィルター処理は、ポータルの [Enterprise アプリ] ブレードでグループの要求とフィルター処理が構成されたアプリに対して生成されるトークンに適用されます。大規模な組織では、トークンでグループ要求を出力する前に、ユーザーがメンバーになっているグループの数が、Microsoft Entra ID で適用される制限を超える可能性があることに注意してくださいこの制限を超えると、Microsoft Entra ID はトークンでのグループ要求の送信を完全に省略します。
トークンが暗黙的なフローを通じて発行される場合、グループ要求には 5 グループの制限があります。暗黙的なフローを介して要求されたトークンでは、ユーザーが属するグループの数が 5 つを超える場合にのみ "hasgroups":true 要求が含まれます。
次の場合は、グループではなく、アプリケーションロールに対するアプリ内認可を基準にすることをお勧めします。
- 新しいアプリケーションを開発している、または既存のアプリケーションをそれに構成できる。
- 入れ子になったグループのサポートが必要ない。
アプリケーションロールにより、トークンに入力する必要がある情報の量が制限され、安全性が高まり、アプリの構成からユーザーの割り当てが分離されます。

AD FS およびその他の ID プロバイダーから移行するアプリケーションに対するグループ要求

AD FS によって認証するように構成された多くのアプリケーションでは、Windows Server Active Directory グループ属性の形式のグループメンバーシップ情報に依存しています。これらの属性はグループ sAMAccountName であり、ドメイン名または Windows グループセキュリティ識別子 (GroupSID) によって修飾される場合があります。アプリケーションが AD FS によってフェデレーションされている場合、AD FS では TokenGroups 関数を使用して、ユーザーのグループメンバーシップを取得します。

AD FS から移動されたアプリは、同じ形式の要求を必要とします。 Microsoft Entra ID から出力されるグループとロールの要求には、グループの Microsoft Entra ID objectID 属性ではなく、ドメイン修飾のsAMAccountName 属性または Active Directory から同期された GroupSID 属性が含まれる可能性があります。

グループ要求においてサポートされている形式は、次のとおりです。

Microsoft Entra グループの ObjectId: すべてのグループで使用できます。
sAMAccountName: Active Directory から同期したグループで使用できます。
NetbiosDomain\sAMAccountName: Active Directory から同期したグループで使用できます。
DNSDomainName\sAMAccountName: Active Directory から同期したグループで使用できます。
オンプレミスグループのセキュリティ識別子: Active Directory から同期したグループで使用できます。

Note

sAMAccountName とオンプレミスの GroupSID の属性は、Active Directory から同期されたグループオブジェクトでのみ使用できます。これらは、Microsoft Entra ID または Office 365 で作成されたグループで使用できます。同期されたオンプレミスグループの属性を取得するように Microsoft Entra ID 内で構成されているアプリケーションは、同期されたグループのみでそれらを取得します。

アプリケーションにおいてグループ情報を利用するためのオプション

アプリケーションは、Microsoft Graph グループのエンドポイントを呼び出して、認証されたユーザーのグループ情報を取得できます。関連するグループ数が多い場合でも、この呼び出しによって、ユーザーがメンバーとして属する全グループを確実に利用できるようになります。その際、グループの列挙は、トークンサイズの制限に依存しません。

ただし、既存のアプリケーションが要求を介してグループ情報を使用することが予想される場合は、さまざまな要求形式で Microsoft Entra ID を構成できます。次のオプションを検討してください。

アプリケーション内の認可を目的としてグループメンバーシップを使用している場合は、グループ ObjectID 属性を使用することをお勧めします。グループ ObjectID 属性は変更できないので、Microsoft Entra ID で一意になります。すべてのグループで使用できます。
認可にオンプレミスグループの sAMAccountName 属性を使用している場合は、ドメイン修飾名を使用します。これにより、名前が衝突する可能性が低くなります。 sAMAccountName が 1 つの Active Directory ドメイン内で一意であったとしても、複数の Active Directory ドメインが Microsoft Entra テナントによって同期された場合は、複数のグループが同一の名前を持つ可能性があります。
アプリケーションロールを使用して、グループメンバーシップとアプリケーション間に間接参照レイヤーを提供することを検討してください。そうすると、アプリケーションでは、トークン内のロール要求に基づいて内部承認を決定します。
Active Directory から同期したグループ属性を取得するようにアプリケーションが構成されている場合、グループは、それらの属性を保持していないと、要求の中には含まれません。
グループ要求をアプリケーションに割り当てられたグループに制限するオプションが使用されている場合を除き、トークン内のグループ要求には、入れ子になったグループが含まれます。

ユーザーが GroupB のメンバーであり、GroupB が GroupA のメンバーである場合、そのユーザーに対するグループ要求には GroupA と GroupB の両方が含まれます。組織のユーザーが多数のグループメンバーシップを保有している場合は、トークン内にリストされるグループ数によって、トークンサイズが大きくなる場合があります。 Microsoft Entra ID では、トークンで出力されるグループの数が、SAML アサーションの場合は 150、JWT の場合は 200 に制限されています。ユーザーがより多数のグループのメンバーである場合、グループは省略されます。代わりに、グループ情報を取得するための Microsoft Graph エンドポイントへのリンクが含まれています。

Active Directory から同期されたグループ属性を使用する場合の前提条件

ObjectId 形式を使用すると、グループメンバーシップ要求を任意のグループのトークンで出力できます。グループ ObjectId 以外の形式でグループ要求を使用するには、Microsoft Entra Connect を使用してそのグループが Active Directory から同期されている必要があります。

Active Directory グループにグループ名を出力するように Microsoft Entra ID を構成するには:

Active Directory からグループ名を同期する

Microsoft Entra ID がグループまたはロールの要求でグループ名またはオンプレミスグループの SID を出力できるようにするには、事前に Active Directory から必要な属性を同期する必要があります。 Microsoft Entra Connect バージョン 1.2.70 以降を実行している必要があります。 1.2.70 より前の Microsoft Entra Connect のバージョンでは、Active Directory からグループオブジェクトを同期しますが、必要なグループ名の属性は含まれません。
トークンにグループ要求を含むように Microsoft Entra ID でアプリケーションの登録を構成する

グループ要求は、ポータルの [エンタープライズアプリケーション] セクション、または [アプリケーションの登録] セクションのアプリケーションマニフェストを使用して構成できます。アプリケーションマニフェストでグループ要求を構成するには、この記事で後述する「グループ属性のために Microsoft Entra のアプリケーションの登録を構成する」を参照してください。

SSO 構成を使用して SAML アプリケーションのトークンにグループ要求を追加する

シングルサインオン (SSO) を使用してギャラリーまたはギャラリー以外の SAML アプリケーションのグループ要求を構成するには:

[エンタープライズアプリケーション] を開き、一覧からアプリケーションを選択し、[シングルサインオン構成] を選択してから、[ユーザー属性と要求] を選択します。
[グループ要求を追加する] を選択します。

オプションを使用して、トークン内に含める必要があるグループを選択します。

[グループ要求] ウィンドウとそのグループオプションが示されたスクリーンショット。

[選択]	説明
すべてのグループ	セキュリティグループ、配布リスト、ロールを出力します。
セキュリティグループ	グループ要求の中で、ユーザーがメンバーになっているセキュリティグループが出力します。ユーザーにディレクトリロールが割り当てられている場合は、オブジェクト ID として出力されます。
ディレクトリロール	ユーザーにディレクトリロールが割り当てられている場合は、`wids` 要求として出力されます。 (グループの要求は出力されません。)
アプリケーションに割り当てられているグループ	アプリケーションに明示的に割り当てられ、ユーザーがメンバーになっているグループのみが出力されます。トークンのグループ数の制限により、大規模な組織に推奨されます。

たとえば、ユーザーがメンバーとして属するセキュリティグループをすべて出力するには、[セキュリティグループ] を選択します。

Microsoft Entra ID objectID 属性ではなく、Active Directory から同期されている Active Directory 属性を使用してグループを出力するには、[ソース属性] ドロップダウンリストから目的の形式を選択します。要求には、Active Directory から同期されたグループのみが含まれます。
アプリケーションに割り当てられたグループのみを出力するには、[アプリケーションに割り当てられているグループ] を選択します。

アプリケーションに割り当てられているグループは、トークンに含まれます。ユーザーがメンバーになっている他のグループは省略されます。このオプションでは、入れ子になったグループは含まれません。ユーザーは、アプリケーションに割り当てられたグループの直接のメンバーである必要があります。

アプリケーションに割り当てられているグループを変更するには、[エンタープライズアプリケーション] 一覧からアプリケーションを選択します。次に、アプリケーションの左側のメニューから [ユーザーとグループ] を選択します。

アプリケーションへのグループ割り当ての管理の詳細については、エンタープライズアプリケーションへのユーザーまたはグループの割り当てに関する記事を参照してください。

トークンでクラウド専用グループの表示名を生成する

クラウド専用グループのグループ表示名を含むようにグループ要求を構成できます。

[エンタープライズアプリケーション] を開き、一覧からアプリケーションを選択し、[シングルサインオン構成] を選択してから、[ユーザー属性と要求] を選択します。
グループ要求が既に構成されている場合は、[追加の要求] セクションからそれを選択します。それ以外の場合は、前の手順で説明したようにグループ要求を追加できます。
トークンで生成されるグループの種類として、[アプリケーションに割り当てられているグループ] を選択します。
クラウドグループのみのグループ表示名を生成するには、[ソース属性] ドロップダウンで [クラウド専用グループの表示名] を選びます。
ハイブリッドセットアップの場合、同期されたグループのオンプレミスグループ属性とクラウドグループの表示名を出力するには、目的のオンプレミスソース属性を選び、[クラウド専用グループのグループ名を生成する] チェックボックスをオンにします。

Note

アプリケーションに追加できるのは、割り当てられたグループのクラウドグループ名のみです。 groups assigned to the application に対する制限は、グループ名は一意ではなく、セキュリティリスクを軽減するために、表示名をアプリケーションに明示的に割り当てられたグループに対してのみ出力できるようにするためです。そうしない場合、任意のユーザーが重複した名前でグループを作成し、アプリケーション側でアクセス権を取得できます。

詳細オプションの設定

グループ要求名をカスタマイズする

[詳細オプション] の設定を使用して、グループ要求の出力方法を変更できます。

[グループ要求の名前をカスタマイズする] を選択した場合は、グループ要求に別の要求の種類を指定できます。 [名前] ボックスに要求の種類を、[名前空間] ボックスに要求のオプションの名前空間を入力します。

詳細オプションで、[グループ要求の名前をカスタマイズする] オプションが選択され、名前と名前属性の値が入力されたスクリーンショット。

アプリケーションによっては、グループメンバーシップ情報をロール要求内に表示する必要があります。必要に応じて、[グループをロール要求として生成する] チェックボックスをオンにして、ユーザーのグループをロールとして出力できます。

詳細オプションで、[グループ要求の名前をカスタマイズする] と [グループをロール要求として生成する] チェックボックスが選択されたスクリーンショット。

Note

グループデータをロールとして出力するオプションが使用されると、ロール要求内にグループのみが表示されます。ユーザーが割り当てられているアプリケーションロールはいずれも、ロール要求には表示されなくなります。

グループのフィルター処理

グループのフィルター処理を使用すると、グループ要求の一部として含まれるグループの一覧を細かく制御できます。フィルターが構成されている場合、そのフィルターに一致するグループのみが、そのアプリケーションに送信されるグループ要求に含まれます。このフィルターは、グループ階層に関係なく、すべてのグループに適用されます。

Note

グループフィルター処理は、ポータルの [Enterprise アプリ] ブレードでグループの要求とフィルター処理が構成されたアプリに対して出力されるトークンに適用されます。
グループフィルター処理は、Microsoft Entra ロールには適用されません。

グループの表示名または SAMAccountName 属性に適用するフィルターを構成できます。次のフィルター処理操作がサポートされています。

Prefix: 選択された属性の先頭と照合します。
Suffix: 選択された属性の末尾と照合します。
Contains: 選択された属性内の任意の場所と照合します。

フィルターオプションが示されたスクリーンショット。

グループ化変換

アプリケーションによっては、Microsoft Entra ID での表示方法とは異なる形式のグループが必要になる場合があります。この要件をサポートするために、グループ要求で出力される各グループに変換を適用することができます。これは、カスタムのグループ要求に対して正規表現 (RegEx) と置換値を構成できるようにすることで実現されます。

グループの変換で正規表現情報が追加されたスクリーンショット。 \

正規表現パターン: 正規表現を使用して、このボックスで設定したパターンに従ってテキスト文字列を解析します。アウトラインに使用する正規表現パターンが true に評価された場合、正規表現置換パターンが実行されます。
正規表現置換パターン: アウトラインに使用した正規表現パターンが true に評価された場合、どのように文字列を置き換えるかのアウトラインが正規表現で作成されます。キャプチャグループを使用して、この置換正規表現の部分式を照合します。

正規表現の置換とキャプチャグループの詳細については、「正規表現オブジェクトモデルのキャプチャグループ」を参照してください。

Note

Microsoft Entra のドキュメントで説明されているように、ポリシーを使用して制限付きの要求を変更することはできません。データソースを変更できず、要求を生成するときに変換が適用されません。グループ要求は依然として制限付きの要求であるため、名前を変更してグループをカスタマイズする必要があります。カスタムグループの要求の名前に制限付きの名前を選択した場合、要求は実行時に無視されます。

正規表現パターンに一致しないグループは、結果として得られる要求には出力されないため、正規表現の変換機能をフィルターとして使用することもできます。

元のグループ要求に適用された変換によって新しいカスタム要求が生成された場合、元のグループ要求はトークンから省略されます。ただし、構成された正規表現が元のリストの値と一致しない場合、カスタム要求は存在せず、元のグループ要求がトークンに含まれます。

グループ要求の構成を編集する

グループ要求の構成が [ユーザー属性と要求] 構成に追加されると、グループ要求を追加するオプションは使用できなくなります。グループ要求の構成を変更するには、[追加の要求] の一覧でグループ要求を選択します。

[ユーザー属性と要求] 領域でグループ要求の名前が強調表示されたスクリーンショット。

グループ属性のために Microsoft Entra のアプリケーションの登録を構成する

グループ要求は、[アプリケーションマニフェスト] の省略可能な要求に関するセクションでも構成できます。

ポータルで、[ID]>[アプリケーション]>[アプリの登録]>[アプリケーションの選択]>[マニフェスト] を選択します。

グループメンバーシップの要求を有効にするには、groupMembershipClaims を変更します。

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

[選択]	説明
`All`	セキュリティグループ、配布リスト、ロールが出力されます。
`SecurityGroup`	グループ要求の中で、ユーザーがメンバーになっているセキュリティグループと Microsoft Entra ロールが出力されます。
`DirectoryRole`	ユーザーにディレクトリロールが割り当てられている場合は、`wids` 要求として出力されます。 (グループ要求は出力されません。)
`ApplicationGroup`	アプリケーションに明示的に割り当てられ、ユーザーがメンバーになっているグループのみが出力されます。
`None`	グループは返されません。 (大文字と小文字は区別されません。そのため `none` も機能します。これは、アプリケーションマニフェストで直接設定できます。)

次に例を示します。

"groupMembershipClaims": "SecurityGroup"

既定では、グループの ObjectID 属性は、グループ要求の値に出力されます。オンプレミスグループ属性を含むように要求の値を変更するか、または要求の種類をロールに変更するには、次のステップの説明のように optionalClaims 構成を使用します。

グループ名の構成に対して省略可能な要求を設定します。

トークン内のグループにオンプレミスの Active Directory グループの属性が含まれるようにする場合は、optionalClaims セクションで省略可能な要求の適用先となるトークンの種類を指定します。複数のトークンの種類を一覧表示できます。

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

Note

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"`、`"cloud_displayname"`、`"emit_as_roles"` です。

additionalProperties では、"sam_account_name"、"dns_domain_and_sam_account_name"、または "netbios_domain_and_sam_account_name" のいずれかが必須です。複数ある場合、最初の 1 つが使用され、それ以外は無視されます。

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

クラウド専用グループのグループ表示名を生成するには、additional properties に "cloud_displayname" を追加します。このオプションは、“groupMembershipClaims” が ApplicationGroup に設定されている場合にのみ機能します。

注意

"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"]
    }]
}

次の方法で共有

Microsoft Entra ID を使用してアプリケーションのグループ要求を構成する

この機能に関する重要な注意点

AD FS およびその他の ID プロバイダーから移行するアプリケーションに対するグループ要求

アプリケーションにおいてグループ情報を利用するためのオプション

Active Directory から同期されたグループ属性を使用する場合の前提条件

SSO 構成を使用して SAML アプリケーションのトークンにグループ要求を追加する

トークンでクラウド専用グループの表示名を生成する

詳細オプションの設定

グループ要求名をカスタマイズする

グループのフィルター処理

グループ化変換

グループ要求の構成を編集する

グループ属性のために Microsoft Entra のアプリケーションの登録を構成する

例

次のステップ

フィードバック

その他のリソース