Anpassen von in Token ausgegebenen Ansprüchen für eine bestimmte App auf einem Mandanten mithilfe von PowerShell und der Anspruchszuordnungsrichtlinie
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
- Erfahren Sie, wie Sie einen Microsoft Entra-Mandanten erhalten.
- Laden Sie das neueste Microsoft Graph PowerShell SDK herunter.
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:
- Weglassen der grundlegenden Ansprüche aus Token
- Schließen Sie EmployeeID und TenantCountry als Ansprüche in Token ein
- Verwenden Sie eine Anspruchstransformation in Token
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.
Erstellen Sie eine Anspruchszuordnungsrichtlinie. Diese Richtlinie, verknüpft mit bestimmten Dienstprinzipalen, entfernt den grundlegenden Anspruchsatz aus den Token.
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"
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.
Erstellen Sie eine Anspruchszuordnungsrichtlinie. Diese Richtlinie, die mit bestimmten Dienstprinzipalen verknüpft ist, fügt den Token die Ansprüche „EmployeeID“ und „TenantCountry“ hinzu.
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"
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.
Erstellen Sie eine Anspruchszuordnungsrichtlinie. Diese Richtlinie, die mit bestimmten Dienstprinzipalen verknüpft ist, gibt einen benutzerdefinierten Anspruch
JoinedData
an Tokens aus.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"
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.
Wenn Sie alle Dienstprinzipale Ihrer Organisation anzeigen möchten, können Sie die Microsoft Graph-API abfragen oder sie im Microsoft Graph Explorer nachsehen.
Wenn Sie alle Anspruchszuordnungsrichtlinien in Ihrem Mandanten anzeigen und die Richtlinie
ObjectId
abrufen möchten, führen Sie den folgenden Befehl aus:Get-MgPolicyClaimMappingPolicy
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>"}