Konfigurieren von Gruppenansprüchen für Anwendungen mit Microsoft Entra ID

Microsoft Entra ID kann Informationen zur Gruppenmitgliedschaft eines Benutzer in Token bereitstellen, damit diese in Anwendungen verwendet werden können. Dieses Feature unterstützt drei grundlegende Muster:

• Gruppen, die durch das Attribut ihres Microsoft Entra-Objektbezeichners (OID) identifiziert werden
• Gruppen, die durch sAMAccountName- oder GroupSID-Attribute für in Active Directory synchronisierte Gruppen und Benutzer*innen identifiziert werden
• Gruppen, die anhand ihres Anzeigenamenattributs für rein cloudbasierte Gruppen identifiziert werden

Wichtige Einschränkungen für diese Funktionalität

• Die Unterstützung für die Verwendung lokal synchronisierter sAMAccountName- und SID-Attribute (Sicherheits-ID) soll das Verschieben vorhandener Anwendungen aus Active Directory-Verbunddienste (AD FS) und anderen Identitätsanbietern ermöglichen. In Microsoft Entra ID verwaltete Gruppen enthalten die Attribute nicht, die zur Ausgabe dieser Ansprüche erforderlich sind.

• Um die Beschränkung der Gruppenanzahl zu vermeiden, wenn Ihre Benutzer über eine große Anzahl von Gruppenmitgliedschaften verfügen, können Sie die in Ansprüchen ausgegebenen Gruppen auf die für die Anwendung relevanten Gruppen einschränken. Weitere Informationen zum Ausgeben von Gruppen, die der Anwendung zugewiesen sind, finden Sie jeweils unter JWT-Token bzw. SAML-Token. Wenn das Zuweisen von Gruppen zu Ihrer Anwendung nicht möglich ist, können Sie einen Gruppenfilter konfigurieren, um die Anzahl der im Anspruch ausgegebenen Gruppen zu reduzieren. Die Gruppenfilterung gilt für Token, die für Apps ausgegeben werden, bei denen Gruppenansprüche und Filter auf dem Blatt Unternehmensanwendungen im Portal konfiguriert wurden. Beachten Sie, dass in größeren Organisationen die Anzahl der Gruppen, bei denen ein Benutzer Mitglied ist, den Grenzwert überschreiten kann, den Microsoft Entra ID vor dem Ausstellen von Gruppenansprüchen in einem Token anwendet. Das Überschreiten dieses Grenzwerts führt dazu, dass Microsoft Entra ID das Senden von Gruppenansprüchen im Token vollständig auslässt.

• Für Gruppenansprüche gilt ein Grenzwert von fünf Gruppen, wenn das Token über den impliziten Flow ausgestellt wird. Token, die über den impliziten Flow angefordert werden, weisen nur dann den Anspruch "hasgroups":true auf, wenn sich der Benutzer in mehr als fünf Gruppen befindet.

• In folgenden Fällen empfehlen wir, die In-App-Autorisierung nicht mit Gruppen, sondern mit Anwendungsrollen zu verwenden:

  • Für die Entwicklung neuer Anwendungen oder in Fällen, in denen die Anwendung nicht hierfür konfiguriert werden kann.
  • In Fällen, in denen keine Unterstützung für geschachtelte Gruppen erforderlich ist.

  Bei Verwendung von Anwendungsrollen müssen weniger Informationen in das Token aufgenommen werden. Diese Vorgehensweise ist sicherer, und dadurch wird die Benutzerzuweisung von der App-Konfiguration getrennt.

Gruppenansprüche für aus AD FS und anderen Identitätsanbietern migrierte Anwendungen

Viele Anwendungen, die für die Authentifizierung bei AD FS konfiguriert sind, benötigen Informationen zur Gruppenmitgliedschaft in Form von Windows Server Active Directory-Gruppenattributen. Bei diesen Attributen handelt es sich um den sAMAccountName der Gruppe, der anhand des Domänennamens qualifiziert werden kann, oder um die Windows-Gruppensicherheits-ID (GroupSID). Wenn die Anwendung in einen Verbund mit AD FS platziert wird, verwendet AD FS die TokenGroups-Funktion, um die Gruppenmitgliedschaften der Benutzer*innen abzurufen.

Eine App, die aus AD FS verschoben wurde, benötigt Ansprüche im gleichen Format. Von Microsoft Entra ID ausgegebene Gruppen- und Rollenansprüche können das domänenqualifizierte Attribut sAMAccountName oder das über Active Directory synchronisierte Attribut GroupSID anstelle des Microsoft Entra ID-Attributs objectID der Gruppe enthalten.

Folgende Formate für Gruppenansprüche werden unterstützt:

• ObjectID der Microsoft Entra-Gruppe: Für alle Gruppen verfügbar.
• sAMAccountName: Für Gruppen verfügbar, die über Active Directory synchronisiert werden.
• NetbiosDomain\sAMAccountName: Für Gruppen verfügbar, die über Active Directory synchronisiert werden.
• DNSDomainName\sAMAccountName: Für Gruppen verfügbar, die über Active Directory synchronisiert werden.
• Lokale Gruppensicherheits-ID: Für Gruppen verfügbar, die über Active Directory synchronisiert werden.

Optionen für die Verwendung von Gruppeninformationen in Anwendungen

Anwendungen können den Microsoft Graph-Gruppenendpunkt aufrufen, um Gruppeninformationen zum authentifizierten Benutzer abzurufen. Dieser Aufruf stellt sicher, dass alle Gruppen, in denen ein Benutzer Mitglied ist, verfügbar sind, auch wenn eine große Anzahl von Gruppen beteiligt ist. Die Gruppenenumeration ist dann unabhängig von Einschränkungen hinsichtlich der Tokengröße.

Wenn jedoch für eine vorhandene Anwendung der Eingang von Gruppeninformationen über Ansprüche erwartet wird, können Sie Microsoft Entra ID mit verschiedenen Anspruchsformaten konfigurieren. Ziehen Sie folgende Möglichkeiten in Betracht:

• Wenn Sie die Gruppenmitgliedschaft für die anwendungsinterne Autorisierung verwenden, sollten Sie das Attribut ObjectID der Gruppe verwenden. Das Attribut ObjectID ist unveränderlich und in Microsoft Entra ID eindeutig. Es ist für alle Gruppen verfügbar.

• Wenn Sie das Attribut sAMAccountName der lokalen Gruppe für die Autorisierung nutzen, sollten Sie qualifizierte Domänennamen verwenden. Dadurch wird das Risiko eines Namenskonflikts reduziert. sAMAccountName kann innerhalb einer Active Directory-Domäne eindeutig sein. Wenn jedoch mehrere Active Directory-Domänen mit einem Microsoft Entra-Mandanten synchronisiert werden, besteht die Möglichkeit, dass mehrere Gruppen den gleichen Namen aufweisen.

• Erwägen Sie die Verwendung von Anwendungsrollen, um eine Dereferenzierungsschicht zwischen der Gruppenmitgliedschaft und der Anwendung bereitzustellen. Die Anwendung trifft dann anhand der Rollenansprüche im Token interne Autorisierungsentscheidungen.

• Wenn die Anwendung für den Abruf von Gruppenattributen konfiguriert ist, die aus Active Directory synchronisiert werden, und ein Group-Objekt diese Attribute nicht enthält, wird die entsprechende Gruppe nicht in die Ansprüche eingeschlossen.

• Gruppenansprüche in Token enthalten geschachtelte Gruppen, sofern nicht die Option zum Einschränken von Gruppenansprüchen auf Gruppen, die der Anwendung zugewiesen sind, verwendet wird.

  Wenn ein Benutzer Mitglied von Gruppe B und Gruppe B Mitglied von Gruppe A ist, enthalten die Gruppenansprüche für den Benutzer sowohl Gruppe A als auch Gruppe B. Wenn eine Organisationen Benutzer mit sehr vielen Gruppenmitgliedschaften aufweist, kann die Anzahl der in den Token enthaltenen Gruppen die Tokengröße erhöhen. Microsoft Entra ID begrenzt die Anzahl Gruppen, die in einem Token ausgegeben werden, auf 150 für SAML-Assertionen und auf 200 für JWT. Wenn ein Benutzer Mitglied von sehr vielen Gruppen ist, werden die Gruppen ausgelassen. Stattdessen wird ein Link zu dem Microsoft Graph-Endpunkt bereitgestellt, über den Gruppeninformationen abgerufen werden können.

Voraussetzungen für die Verwendung von Gruppenattributen, die über Active Directory synchronisiert werden

Ansprüche von Gruppenmitgliedschaften können in Token für beliebige Gruppen ausgegeben werden, wenn Sie das ObjectId-Format verwenden. Damit Gruppenansprüche in anderen Formaten als der ObjectId der Gruppe verwendet werden können, müssen die Gruppen aus Active Directory über Microsoft Entra Connect synchronisiert werden.

So konfigurieren Sie Microsoft Entra ID für die Ausgabe von Gruppennamen für Active Directory-Gruppen:

1. Synchronisieren von Gruppennamen über Active Directory

   Bevor Microsoft Entra ID Gruppennamen oder lokale Gruppen-SIDs in Gruppen- oder Rollenansprüchen ausgeben kann, müssen Sie die erforderlichen Attribute über Active Directory synchronisieren. Sie müssen Microsoft Entra Connect-Version 1.2.70 oder höher ausführen. Bei Microsoft Entra Connect-Versionen vor 1.2.70 werden die Gruppenobjekte zwar über Active Directory synchronisiert, die erforderlichen Gruppennamenattribute sind dabei jedoch nicht eingeschlossen.

2. Konfigurieren der Anwendungsregistrierung in Microsoft Entra ID, sodass Gruppenansprüche in Token eingeschlossen werden

   Gruppenansprüche können Sie im Abschnitt Unternehmensanwendungen im Portal oder mithilfe des Anwendungsmanifests im Abschnitt Anwendungsregistrierungen konfigurieren. Informationen zum Konfigurieren von Gruppenansprüchen im Anwendungsmanifest finden Sie weiter unten in diesem Artikel unter Konfigurieren der Microsoft Entra-Anwendungsregistrierung für Gruppenattribute.

Hinzufügen von Gruppenansprüchen zu Token für SAML-Anwendungen mithilfe der SSO-Konfiguration

So konfigurieren Sie Gruppenansprüche für eine SAML-Anwendung (aus dem Katalog oder nicht aus dem Katalog) über einmaliges Anmelden (Single Sign-On, SSO):

1. Öffnen Sie Unternehmensanwendungen, und wählen Sie die Anwendung in der Liste aus. Wählen Sie SSO-Konfiguration und dann Benutzerattribute & Ansprüche aus.

2. Wählen Sie Gruppenanspruch hinzufügen aus.

   

3. Verwenden Sie die Optionen, um die Gruppen auszuwählen, die im Token enthalten sein sollen.

   

   Auswahl	BESCHREIBUNG
   Alle Gruppen	Gibt Sicherheitsgruppen und Verteilerlisten sowie Rollen aus.
   Sicherheitsgruppen	Gibt im Gruppenanspruch Sicherheitsgruppen aus, in denen der Benutzer Mitglied ist. Wenn der Benutzerin oder dem Benutzer Verzeichnisrollen zugewiesen sind, werden diese als Objekt-ID ausgegeben.
   Verzeichnisrollen	Wenn dem Benutzer Verzeichnisrollen zugewiesen sind, werden diese als wids-Anspruch ausgegeben. (Die Gruppenansprüche werden nicht ausgegeben.)
   Der Anwendung zugewiesene Gruppen	Gibt nur die Gruppen aus, die der Anwendung explizit zugewiesen sind und in denen der Benutzer Mitglied ist. Empfohlen für große Organisationen aufgrund der Einschränkung der Gruppenanzahl im Token.

   • Wenn Sie beispielsweise alle Sicherheitsgruppen ausgeben möchten, in denen der Benutzer Mitglied ist, wählen Sie Sicherheitsgruppen aus.

     

     Wenn Sie Gruppen mithilfe der Active Directory-Attribute ausgeben möchten, die über Active Directory und nicht über objectID-Attribute von Microsoft Entra ID synchronisiert werden, wählen Sie in der Dropdownliste Quellattribut das erforderliche Format aus. In den Ansprüchen sind nur Gruppen enthalten, die aus Active Directory synchronisiert werden.

     

   • Wenn Sie nur die der Anwendung zugewiesenen Gruppen ausgeben möchten, wählen Sie Der Anwendung zugewiesene Gruppen aus.

     

     Gruppen, die der Anwendung zugewiesen sind, werden in das Token eingeschlossen. Andere Gruppen, in denen der Benutzer Mitglied ist, werden ausgelassen. Bei dieser Option werden keine geschachtelten Gruppen eingeschlossen, und der Benutzer muss ein direktes Mitglied der Gruppe sein, die der Anwendung zugewiesen ist.

     Wenn Sie die der Anwendung zugewiesenen Gruppen ändern möchten, wählen Sie die Anwendung in der Liste Unternehmensanwendungen aus. Wählen Sie anschließend im linken Men+ der Anwendung Benutzer und Gruppen aus.

     Weitere Informationen zum Verwalten von Gruppenzuweisungen zu Anwendungen finden Sie unter Zuweisen eines Benutzers oder einer Gruppe zu einer Unternehmens-App.

Ausgeben des Anzeigenamens für rein cloudbasierte Gruppen im Token

Sie können den Gruppenanspruch so konfigurieren, dass er den Gruppenanzeigenamen für die rein cloudbasierten Gruppen enthält.

1. Öffnen Sie Unternehmensanwendungen, und wählen Sie die Anwendung in der Liste aus. Wählen Sie SSO-Konfiguration und dann Benutzerattribute & Ansprüche aus.

2. Wenn Sie bereits Gruppenansprüche konfiguriert haben, können Sie sie im Abschnitt Zusätzliche Ansprüche auswählen. Andernfalls können Sie den Gruppenanspruch wie in den vorherigen Schritten beschrieben hinzufügen.

3. Wählen Sie für den im Token ausgegebenen Gruppentyp die Option Der Anwendung zugewiesene Gruppen aus:

   

4. Wenn der Anzeigename der Gruppe nur für Cloudgruppen ausgegeben werden soll, wählen Sie in der Dropdownliste Quellattribut die Option Anzeigenamen nur für rein cloudbasierte Gruppen aus:

   

5. Wenn Sie in einem Hybridsetup ein lokales Gruppenattribut für synchronisierte Gruppen und einen Anzeigenamen für Cloudgruppen ausgeben möchten, können Sie das gewünschte Attribut für lokale Quellen auswählen und das Kontrollkästchen Gruppenname für rein cloudbasierte Gruppen ausgeben aktivieren:

   

Festlegen erweiterter Optionen

Anpassen des Gruppenanspruchsnamens

Sie können die Art und Weise ändern, wie Gruppenansprüche ausgegeben werden, indem Sie die Einstellungen unter Erweiterte Optionen verwenden.

Wenn Sie Name des Gruppenanspruchs anpassen auswählen, können Sie für Gruppenansprüche einen anderen Anspruchstyp angeben. Geben Sie den Anspruchstyp im Feld Name und den optionalen Namespace für den Anspruch im Feld Namespace ein.

Bei einigen Anwendungen ist es erforderlich, dass die Informationen zur Gruppenmitgliedschaft im Anspruch „role“ enthalten sind. Sie können optional die Gruppen des Benutzers als Rollen ausgeben, indem Sie das Kontrollkästchen Gruppen als Rollenansprüche ausgeben aktivieren.

Gruppenfilterung

Die Gruppenfilterung ermöglicht eine differenzierte Steuerung der Liste der Gruppen, die als Teil des Gruppenanspruchs enthalten ist. Wenn ein Filter konfiguriert ist, werden nur Gruppen, die dem Filter entsprechen, in den Gruppenanspruch eingeschlossen, der an diese Anwendung gesendet wird. Der Filter wird unabhängig von der Gruppenhierarchie auf alle Gruppen angewendet.

Sie können Filter so konfigurieren, dass sie auf den Anzeigenamen oder das Attribut SAMAccountName der Gruppe angewendet werden. Die folgenden Filtervorgänge werden unterstützt:

• Präfix: Entspricht dem Anfang des ausgewählten Attributs.
• Suffix: Entspricht dem Ende des ausgewählten Attributs.
• Enthält: Entspricht einer beliebigen Position im ausgewählten Attribut.

Gruppentransformation

Für einige Anwendungen müssen die Gruppen möglicherweise in einem anderen als in dem in Microsoft Entra ID dargestellten Format vorliegen. Wenn Sie dies unterstützen möchten, können Sie eine Transformation auf jede Gruppe anwenden, die im Gruppenanspruch ausgegeben wird. Dies erreichen Sie, indem die Konfiguration eines regulären Ausdrucks (RegEx) und eines Ersetzungswerts für benutzerdefinierte Gruppenansprüche ermöglichen.

\

• RegEx-Muster: Verwenden Sie einen regulären Ausdruck, um Textzeichenfolgen gemäß dem Muster zu analysieren, das Sie in diesem Feld festlegen. Wenn das beschriebene RegEx-Muster als true ausgewertet wird, wird das RegEx-Ersetzungsmuster ausgeführt.
• RegEx-Ersetzungsmuster: Beschreiben Sie in der RegEx-Notation, wie Sie Ihre Zeichenfolge ersetzen möchten, wenn das beschriebene RegEx-Muster als true ausgewertet wird. Verwenden Sie Erfassungsgruppen, um in diesem regulären Ausdruck Teilausdrücke zu ersetzen.

Weitere Informationen zu RegEx-Ersetzungs- und RegEx-Erfassungsgruppen finden Sie unter Das Objektmodell für reguläre Ausdrücke: Die erfasste Gruppe.

Bearbeiten der Konfiguration für Gruppenansprüche

Nachdem Sie der Konfiguration Benutzerattribute und Ansprüche eine Gruppenanspruchskonfiguration hinzugefügt haben, ist die Option zum Hinzufügen eines Gruppenanspruchs nicht verfügbar. Wenn Sie die Gruppenanspruchskonfiguration ändern möchten, wählen Sie in der Liste Zusätzliche Ansprüche den Gruppenanspruch aus.

Konfigurieren der Microsoft Entra-Anwendungsregistrierung für Gruppenattribute

Gruppenansprüche können Sie auch im Abschnitt Optionale Ansprüche des Anwendungsmanifests konfigurieren.

1. Wählen Sie im Portal Identität>Anwendungen>App-Registrierungen>Anwendung auswählen>Manifest.

2. Aktivieren Sie Gruppenmitgliedschaftsansprüche, indem Sie groupMembershipClaims ändern.

   Gültige Werte sind:

   Auswahl	BESCHREIBUNG
   All	Gibt Sicherheitsgruppen, Verteilerlisten und Rollen aus.
   SecurityGroup	Gibt im Gruppenanspruch Sicherheitsgruppen und Microsoft Entra-Rollen aus, in denen der Benutzer Mitglied ist.
   DirectoryRole	Wenn dem Benutzer Verzeichnisrollen zugewiesen sind, werden diese als wids-Anspruch ausgegeben. (Gruppenansprüche werden nicht ausgegeben.)
   ApplicationGroup	Gibt nur die Gruppen aus, die der Anwendung explizit zugewiesen sind und in denen der Benutzer Mitglied ist.
   None	Es werden keine Gruppen zurückgegeben. (Die Groß-/Kleinschreibung ist nicht relevant, daher funktioniert auch none. Dies kann direkt im Anwendungsmanifest festgelegt werden.)

   Beispiel:

   "groupMembershipClaims": "SecurityGroup"
   

   Standardmäßig werden ObjectID-Attribute von Gruppen im Wert des Gruppenanspruchs ausgegeben. Wenn Sie den Anspruchswert so ändern möchten, dass er lokale Gruppenattribute enthält, oder um den Anspruchstyp in „role“ zu ändern, verwenden Sie die im nächsten Abschnitt beschriebene optionalClaims-Konfiguration.

3. Legen Sie optionale Ansprüche für die Konfiguration des Gruppennamens fest.

   Wenn in den Gruppen im Token die lokalen Active Directory-Gruppenattribute enthalten sollen, geben Sie im Abschnitt optionalClaims an, welcher optionale Anspruch des Tokentyps angewendet werden soll. Sie können mehrere Tokentypen auflisten:

   • idToken für das OIDC-ID-Token
   • accessToken für das OAuth/OIDC-Zugriffstoken
   • Saml2Token für SAML-Token

   Hinweis

   Der Saml2Token-Typ gilt nur für Token im SAML1.1- und SAML2.0-Format.

   Ändern Sie für jeden relevanten Tokentyp den Gruppenanspruch so, dass der Abschnitt optionalClaims im Manifest verwendet wird. Das optionalClaims-Schema lautet folgendermaßen:

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

   Schema für optionale Ansprüche	Wert
   name	Muss "groups"lauten.
   source	Wird nicht verwendet. Auslassen oder null angeben.
   essential	Wird nicht verwendet. Auslassen oder false angeben.
   additionalProperties	Liste zusätzlicher Eigenschaften. Gültige Optionen sind "sam_account_name", "dns_domain_and_sam_account_name", "netbios_domain_and_sam_account_name", "cloud_displayname" und "emit_as_roles".

   In additionalProperties ist entweder "sam_account_name", "dns_domain_and_sam_account_name" oder "netbios_domain_and_sam_account_name" erforderlich. Wenn mehrere dieser Optionen vorhanden sind, wird die erste verwendet, alle weiteren werden ignoriert.

   Einige Anwendungen erfordern Gruppeninformationen über Benutzer im Rollenanspruch. Fügen Sie "emit_as_roles" zu den zusätzlichen Eigenschaften hinzu, um den Anspruchstyp von einem Gruppenanspruch in einen Rollenanspruch zu ändern. Die Gruppenwerte werden im Rollenanspruch ausgegeben.

   Wenn Sie einen Gruppenanzeigenamen für rein cloudbasierte Gruppen ausgeben möchten, können Sie "cloud_displayname" zu additional properties hinzufügen. Diese Option funktioniert nur, wenn “groupMembershipClaims” auf ApplicationGroup festgelegt ist.

   Hinweis

   Wenn Sie verwenden "emit_as_roles", sind die konfigurierten Anwendungsrollen, denen der Benutzer zugewiesen ist, im Rollenanspruch nicht enthalten.

Beispiele

Ausgeben von Gruppen als Gruppennamen in OAuth-Zugriffstoken im Format DNSDomainName\sAMAccountName:

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

Ausgeben von Gruppennamen, die im Format NetbiosDomain\sAMAccountName als Rollenanspruch in SAML- und OIDC-ID-Token zurückgegeben werden sollen:

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

Nächste Schritte

• Hinzufügen der Autorisierung mit Gruppen und Gruppenansprüchen zu einer ASP.NET Core-Web-App (Codebeispiel)
• Zuweisen eines Benutzers oder einer Gruppe zu einer Unternehmens-App
• Konfigurieren von Rollenansprüchen