Referenz zu benutzerdefinierten Anspruchsanbietern

Artikel
08/01/2024

In diesem Referenzartikel erfahren Sie mehr über das REST-API-Schema und die Richtlinienstruktur der Anspruchszuordnung für benutzerdefinierte Anspruchsanbieterereignisse.

Startereignis für die Tokenausstellung

Mit dem Tokenausstellungsereignis des benutzerdefinierten Anspruchsanbieters können Sie Anwendungstoken mit Informationen aus externen Systemen anreichern oder anpassen. Diese Informationen können nicht als Teil des Benutzerprofils im Microsoft Entra-Verzeichnis gespeichert werden.

Übersicht über die Komponenten

Um eine benutzerdefinierte Erweiterung einzurichten und in Ihre Anwendung zu integrieren, müssen mehrere Komponenten verbunden sein. Das folgende Diagramm zeigt eine allgemeine Ansicht der Konfigurationspunkte und Beziehungen, die zum Implementieren einer benutzerdefinierten Erweiterung erstellt werden.

Ein REST-API-Endpunkt sollte öffentlich verfügbar sein. In diesem Diagramm wird er durch Azure-Funktion dargestellt. Die REST-API generiert und gibt benutzerdefinierte Ansprüche an die benutzerdefinierte Erweiterung zurück. Sie ist einer Microsoft Entra-Anwendungsregistrierung zugeordnet.
Sie müssen eine benutzerdefinierte Erweiterung in Microsoft Entra ID konfigurieren, die zum Herstellen einer Verbindung mit Ihrer API konfiguriert ist.
Sie benötigen eine Anwendung, die die angepassten Token empfängt. Zum Beispiel https://jwt.ms, eine Webanwendung im Besitz von Microsoft, die den decodierten Inhalt eines Tokens anzeigt.
Die Anwendung, wie beispielsweise https://jwt.ms, muss mithilfe der App-Registrierung in Microsoft Entra ID registriert werden.
Sie müssen eine Zuordnung zwischen Ihrer Anwendung und Ihrer benutzerdefinierten Erweiterung erstellen.
Sie können die Azure-Funktion optional mit einem Authentifizierungsanbieter schützen. In diesem Artikel verwenden wir Ihre Microsoft Entra ID-Instanz.

REST-API

Ihr REST-API-Endpunkt bildet die Schnittstelle für nachgeschaltete Dienste. Beispielsweise Datenbanken, andere REST-APIs, LDAP-Verzeichnisse oder andere Speicher, die die Attribute enthalten, die Sie der Tokenkonfiguration hinzufügen möchten.

Die REST-API gibt eine HTTP-Antwort mit den Attributen an Microsoft Entra ID zurück. Attribute, die von Ihrer REST-API zurückgegeben werden, werden nicht automatisch einem Token hinzugefügt. Stattdessen muss die Anspruchszuordnungsrichtlinie einer Anwendung konfiguriert werden, damit jedes Attribut in das Token aufgenommen werden kann. In Microsoft Entra ID ändert eine Anspruchszuordnungsrichtlinie die ausgestellten Ansprüche in Token, die für bestimmte Anwendungen ausgegeben wurden.

REST-API-Schema

Verwenden Sie den folgenden REST-API-Datenvertrag, um eine eigene REST-API für das Tokenausstellungs-Startereignis zu entwickeln. Das Schema beschreibt den Vertrag zum Entwerfen des Anforderungs- und Antworthandlers.

Ihre benutzerdefinierte Erweiterung in Microsoft Entra ID führt einen HTTP-Aufruf an Ihre REST-API mit JSON-Nutzdaten aus. Die JSON-Nutzlast enthält Benutzerprofildaten, Authentifizierungskontextattribute und Informationen zu der Anwendung, bei der sich der Benutzer anmelden möchte. Der id-Wert im folgenden JSON-Code ist eine Microsoft-Anwendung, die den Microsoft Entra-Dienst für Authentifizierungsereignisse repräsentiert. Die JSON-Attribute können verwendet werden, um zusätzliche Logik von Ihrer API auszuführen. Die Anforderung an Ihre API hat das folgende Format:

POST https://your-api.com/endpoint

{
    "type": "microsoft.graph.authenticationEvent.tokenIssuanceStart",
    "source": "/tenants/<Your tenant GUID>/applications/<Your Test Application App Id>",
    "data": {
        "@odata.type": "microsoft.graph.onTokenIssuanceStartCalloutData",
        "tenantId": "<Your tenant GUID>",
        "authenticationEventListenerId": "<GUID>",
        "customAuthenticationExtensionId": "<Your custom extension ID>",
        "authenticationContext": {
            "correlationId": "<GUID>",
            "client": {
                "ip": "30.51.176.110",
                "locale": "en-us",
                "market": "en-us"
            },
            "protocol": "OAUTH2.0",
            "clientServicePrincipal": {
                "id": "<Your Test Applications servicePrincipal objectId>",
                "appId": "<Your Test Application App Id>",
                "appDisplayName": "My Test application",
                "displayName": "My Test application"
            },
            "resourceServicePrincipal": {
                "id": "<Your Test Applications servicePrincipal objectId>",
                "appId": "<Your Test Application App Id>",
                "appDisplayName": "My Test application",
                "displayName": "My Test application"
            },
            "user": {
                "companyName": "Casey Jensen",
                "createdDateTime": "2016-03-01T15:23:40Z",
                "displayName": "Casey Jensen",
                "givenName": "Casey",
                "id": "90847c2a-e29d-4d2f-9f54-c5b4d3f26471", // Client ID representing the Microsoft Entra authentication events service
                "mail": "casey@contoso.com",
                "onPremisesSamAccountName": "caseyjensen",
                "onPremisesSecurityIdentifier": "<Enter Security Identifier>",
                "onPremisesUserPrincipalName": "Casey Jensen",
                "preferredLanguage": "en-us",
                "surname": "Jensen",
                "userPrincipalName": "casey@contoso.com",
                "userType": "Member"
            }
        }
    }
}

Das von Azure erwartete REST-API-Antwortformat hat das folgende Format, in dem die Ansprüche DateOfBirth und CustomRoles an Azure zurückgegeben werden:

{
    "data": {
        "@odata.type": "microsoft.graph.onTokenIssuanceStartResponseData",
        "actions": [
            {
                "@odata.type": "microsoft.graph.tokenIssuanceStart.provideClaimsForToken",
                "claims": {
                    "DateOfBirth": "01/01/2000",
                    "CustomRoles": [
                        "Writer",
                        "Editor"
                    ]
                }
            }
        ]
    }
}

Wenn sich ein B2B-Benutzer aus der Fabrikam-Organisation bei der Contoso-Organisation authentifiziert, weist die an die REST-API gesendete Anforderungsnutzlast das Element user im folgenden Format auf:

"user": {
    "companyName": "Fabrikam",
    "createdDateTime": "2022-07-15T00:00:00Z",
    "displayName": "John Wright",
    "id": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
    "mail": "johnwright@fabrikam.com",
    "preferredDataLocation": "EUR",
    "userPrincipalName": "johnwright_fabrikam.com#EXT#@contoso.onmicrosoft.com",
    "userType": "Guest"
}

Unterstützte Datentypen

Die folgende Tabelle zeigt die Datentypen, die von benutzerdefinierten Anspruchsanbietern für das Tokenausstellung-Startereignis unterstützt werden:

Datentyp	Unterstützt
String	True
Zeichenfolgenarray	True
Boolean	False
JSON	False

Einschränkungen der Anspruchsgröße

Die maximale Anspruchsgröße, die ein Anspruchsanbieter zurückgeben kann, ist auf 3 KB beschränkt. Dies ist die Summe aller Schlüssel-Wert-Paare, die von der REST-API zurückgegeben werden.

Anspruchszuordnungsrichtlinie

In Microsoft Entra ID ändert eine Anspruchszuordnungsrichtlinie die ausgestellten Ansprüche in Token, die für bestimmte Anwendungen ausgegeben wurden. Sie enthält Ansprüche von Ihrem benutzerdefinierten Anspruchsanbieter und gibt sie in dem Token aus.

{
    "ClaimsMappingPolicy": {
        "Version": 1,
        "IncludeBasicClaimSet": "true",
        "ClaimsSchema": [{
            "Source": "CustomClaimsProvider",
            "ID": "dateOfBirth",
            "JwtClaimType": "birthdate"
        },
        {
            "Source": "CustomClaimsProvider",
            "ID": "customRoles",
            "JwtClaimType": "my_roles"
        },
        {
            "Source": "CustomClaimsProvider",
            "ID": "correlationId",
            "JwtClaimType": "correlation_Id"
        },
        {
            "Source": "CustomClaimsProvider",
            "ID": "apiVersion",
            "JwtClaimType": "apiVersion"
        },
        {
            "Value": "tokenaug_V2",
            "JwtClaimType": "policy_version"
        }]
    }
}

Das Element ClaimsSchema enthält die Liste der Ansprüche, die mit den folgenden Attributen zugeordnet werden sollen:

Source beschreibt die Quelle des Attributs, der CustomClaimsProvider. Beachten Sie, dass das letzte Element zu Testzwecken einen festen Wert mit der Richtlinienversion enthält. Daher wird das Attribut source weggelassen.
ID ist der Name der Ansprüche, die von der von Ihnen erstellten Azure-Funktion zurückgegeben werden.

Wichtig

Beim Wert des ID-Attributs wird die Groß-/Kleinschreibung beachtet. Stellen Sie sicher, dass Sie den Anspruchsnamen genau so eingeben, wie er von der Azure-Funktion zurückgegeben wird.
JwtClaimType ist ein optionaler Name des Anspruchs im ausgegebenen Token für die OpenID Connect-App. Sie können einen anderen Namen angeben, der im JWT-Token zurückgegeben wird. Wenn die API-Antwort beispielsweise den ID-Wert dateOfBirth hat, kann sie als birthdate im Token ausgegeben werden.

Nachdem Sie Ihre Anspruchszuordnungsrichtlinie erstellt haben, besteht der nächste Schritt darin, sie in Ihren Microsoft Entra-Mandanten hochzuladen. Verwenden Sie die folgende Graph-API claimsMappingPolicy in Ihrem Mandanten.

Wichtig

Das Definition-Element sollte ein Array mit einem einzelnen Zeichenfolgenwert sein. Die Zeichenfolge sollte die Zeichenfolgenversion Ihrer Anspruchszuordnungsrichtlinie mit Escapezeichen sein. Sie können Tools wie https://jsontostring.com/ verwenden, um Ihre Anspruchszuordnungsrichtlinie in eine Zeichenfolge zu verwandeln.

Freigeben über