Freigeben über

Anpassung von Ansprüchen mit PowerShell und der Anspruchszuordnungsrichtlinie

  • Artikel

Ein Anspruch (Claim) bezeichnet Informationen, die ein Identitätsanbieter über einen Benutzer in dem für diesen Benutzer ausgestellten Token angibt. Mandantenadministratoren passen in Token ausgegebene Ansprüche für eine bestimmte Anwendung in ihrem Mandanten an. Mithilfe von Richtlinien für die Anspruchszuordnung können Sie Folgendes:

  • Auswählen, welche Ansprüche in Token enthalten sind.
  • Anspruchstypen erstellen, die es noch nicht gibt.
  • Die Quelle der in konkreten Ansprüchen ausgegebenen Daten auswählen oder ändern.

Die Anspruchsanpassung unterstützt das Konfigurieren von Richtlinien für die Zuordnung von Ansprüchen für die Protokolle SAML, OAuth und OpenID Connect.

Hinweis

Die Anspruchszuordnungsrichtlinie ersetzt sowohl die Richtlinie für benutzerdefinierte Ansprüche als auch die über das Microsoft Entra Admin Center angebotene Anpassung von Ansprüchen. Die Anpassung von Ansprüchen für eine Anwendung mithilfe der Anspruchszuordnungsrichtlinie bedeutet, dass die für diese Anwendung ausgestellten Token die Konfiguration in der Richtlinie für benutzerdefinierte Ansprüche oder die Konfiguration im Blatt für die Anpassung von Ansprüchen im Microsoft Entra Admin Center ignorieren.

Voraussetzungen

Erste Schritte

In den folgenden Beispielen erstellen, aktualisieren, verknüpfen und löschen Sie Richtlinien für Dienstprinzipale. Anspruchszuordnungsrichtlinien können nur Dienstprinzipalobjekten zugewiesen werden.

Beim Erstellen einer Anspruchszuordnungsrichtlinie können Sie auch einen Anspruch von einem Verzeichniserweiterungsattribut in Token ausgeben. Verwenden Sie ExtensionID für das Erweiterungsattribut anstelle von ID im ClaimsSchema-Element. Weitere Informationen zu Erweiterungsattributen finden Sie unter Verwenden von Verzeichniserweiterungsattributen.

Hinweis

Zum Konfigurieren von Anspruchszuordnungsrichtlinien ist das Microsoft Graph PowerShell SDK ist erforderlich.

Öffnen Sie ein Terminal und führen Sie den folgenden Befehl aus, um sich bei Ihrem Microsoft Entra-Administratorkonto anzumelden. Führen Sie diesen Befehl bei jedem Start einer neuen Sitzung aus.

Import-Module Microsoft.Graph.Identity.SignIns

Connect-MgGraph -Scopes "Policy.ReadWrite.ApplicationConfiguration", "Policy.Read.All"

Jetzt können Sie eine Anspruchszuordnungsrichtlinie erstellen und sie einem Dienstprinzipal zu weisen. In den folgenden Beispielen finden Sie gängige Szenarien:

Nachdem Sie eine Anspruchszuordnungsrichtlinie erstellt haben, konfigurieren Sie Ihre Anwendung so, dass bestätigt wird, dass Token benutzerdefinierte Ansprüche enthalten. Weitere Informationen finden Sie unter Überlegungen zur Sicherheit.

Weglassen der grundlegenden Ansprüche aus Token

In diesem Beispiel erstellen Sie eine Richtlinie, die den grundlegenden Anspruchssatz aus den Token entfernt, die an den verknüpften Dienstprinzipal ausgestellte wurden.

  1. Erstellen Sie eine Anspruchszuordnungsrichtlinie. Diese Richtlinie, verknüpft mit bestimmten Dienstprinzipalen, entfernt den grundlegenden Anspruchsatz aus den Token.

  2. Führen Sie über das geöffnete Terminal den folgenden Befehl aus, um die Richtlinie zu erstellen:

    New-MgPolicyClaimMappingPolicy -Definition @('{"ClaimsMappingPolicy":{"Version":1,"IncludeBasicClaimSet":"false"}}') -DisplayName "OmitBasicClaims"

  3. Führen Sie den folgenden Befehl aus, um Ihre neue Richtlinie anzuzeigen und deren ObjectId abzurufen:

    Get-MgPolicyClaimMappingPolicy

Definition                    DeletedDateTime Description DisplayName      Id
----------                    --------------- ----------- -----------      --
{"ClaimsMappingPolicy":{..}}                              OmitBasicClaims  36d1aa10-f9ac...

Einschließen von EmployeeID und TenantCountry als Ansprüche in Tokens

In diesem Beispiel erstellen Sie eine Richtlinie, die Tokens, die für verknüpfte Dienstprinzipale ausgestellt wurden, EmployeeID und TenantCountry hinzufügt. EmployeeID wird als Namensanspruchstyp in den SAML-Token und JWTs ausgegeben. „TenantCountry“ wird als Anspruchstyp für Land/Region in den SAML-Token und JWTs ausgegeben. In diesem Beispiel fahren wir mit dem Einschließen des grundlegenden Anspruchssatzes in Token fort.

  1. Erstellen Sie eine Anspruchszuordnungsrichtlinie. Diese Richtlinie, die mit bestimmten Dienstprinzipalen verknüpft ist, fügt den Token die Ansprüche „EmployeeID“ und „TenantCountry“ hinzu.

  2. Führen Sie den folgenden Befehl in Ihrem Terminal aus, um die Richtlinie zu erstellen:

    New-MgPolicyClaimMappingPolicy -Definition @('{"ClaimsMappingPolicy":{"Version":1,"IncludeBasicClaimSet":"true", "ClaimsSchema": [{"Source":"user","ID":"employeeid","SamlClaimType":"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/employeeid","JwtClaimType":"employeeid"},{"Source":"company","ID":"tenantcountry","SamlClaimType":"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/country","JwtClaimType":"country"}]}}') -DisplayName "ExtraClaimsExample"

  3. Führen Sie den folgenden Befehl aus, um Ihre neue Richtlinie anzuzeigen und deren ObjectId abzurufen:

    Get-MgPolicyClaimMappingPolicy

Verwenden Sie eine Anspruchstransformation in Token

In diesem Beispiel erstellen Sie eine Richtlinie, die einen benutzerdefinierten Anspruch „JoinedData“ an JWTs ausgibt, die für verknüpfte Dienstprinzipale ausgestellt werden. Dieser Anspruch enthält einen Wert, der durch das Verknüpfen der im Attribut „extensionattribute1“ im Benutzerobjekt mit „.-ext“ gespeicherten Daten erstellt wird. In diesem Beispiel schließen wir den grundlegenden Anspruchssatz in Token aus.

  1. Erstellen Sie eine Anspruchszuordnungsrichtlinie. Diese Richtlinie, die mit bestimmten Dienstprinzipalen verknüpft ist, gibt einen benutzerdefinierten Anspruch JoinedData an Tokens aus.

  2. Führen Sie den folgenden Befehl aus, um die Richtlinie zu erstellen:

    New-MgPolicyClaimMappingPolicy -Definition @('{"ClaimsMappingPolicy":{"Version":1,"IncludeBasicClaimSet":"true", "ClaimsSchema":[{"Source":"user","ID":"extensionattribute1"},{"Source":"transformation","ID":"DataJoin","TransformationId":"JoinTheData","JwtClaimType":"JoinedData"}],"ClaimsTransformations":[{"ID":"JoinTheData","TransformationMethod":"Join","InputClaims":[{"ClaimTypeReferenceId":"extensionattribute1","TransformationClaimType":"string1"}], "InputParameters": [{"ID":"string2","Value":"ext"},{"ID":"separator","Value":"-"}],"OutputClaims":[{"ClaimTypeReferenceId":"DataJoin","TransformationClaimType":"outputClaim"}]}]}}') -DisplayName "TransformClaimsExample"

  3. Führen Sie den folgenden Befehl aus, um Ihre neue Richtlinie anzuzeigen und deren ObjectId abzurufen:

    Get-MgPolicyClaimMappingPolicy

Zuweisen der Anspruchszuordnungsrichtlinie zum Dienstprinzipal

Zum Zuweisen der Richtlinie zum Dienstprinzipal brauchen Sie ObjectId Ihrer Anspruchszuordnungsrichtlinie und objectId des Dienstprinzipals, dem die Richtlinie zugewiesen werden muss.

  1. Wenn Sie alle Dienstprinzipale Ihrer Organisation anzeigen möchten, können Sie die Microsoft Graph-API abfragen oder sie im Microsoft Graph Explorer nachsehen.

  2. Wenn Sie alle Anspruchszuordnungsrichtlinien in Ihrem Mandanten anzeigen und die Richtlinie ObjectIdabrufen möchten, führen Sie den folgenden Befehl aus:

    Get-MgPolicyClaimMappingPolicy

  3. Führen Sie den folgenden Befehl aus, wenn Sie über die ObjectId Ihrer Anspruchszuordnungsrichtlinie und des Dienstprinzipals verfügen:

    New-MgServicePrincipalClaimMappingPolicyByRef -ServicePrincipalId <servicePrincipalId> -BodyParameter @{"@odata.id" = "https://graph.microsoft.com/v1.0/policies/claimsMappingPolicies/<claimsMappingPolicyId>"}

Zugehöriger Inhalt