Referens för anpassad anspråksprovider

Artikel
03/19/2024

I den här referensartikeln kan du lära dig mer om REST API-schemat och principstrukturen för anspråksmappning för anpassade anspråksproviderhändelser.

Starthändelse för tokenutfärding

Med tokenutfärdarhändelsen för anpassade anspråksprovider kan du utöka eller anpassa programtoken med information från externa system. Den här informationen som inte kan lagras som en del av användarprofilen i Microsoft Entra-katalogen.

Komponentöversikt

För att konfigurera och integrera ett anpassat tillägg med ditt program måste flera komponenter vara anslutna. Följande diagram visar en översikt över de konfigurationsplatser och relationer som skapas för att implementera ett anpassat tillägg.

Du bör ha en REST API-slutpunkt offentligt tillgänglig. I det här diagrammet representeras det av Azure Function. REST-API:et genererar och returnerar anpassade anspråk till det anpassade tillägget. Den är associerad med en Microsoft Entra-programregistrering.
Du måste konfigurera ett anpassat tillägg i Microsoft Entra-ID, som är konfigurerat för att ansluta till ditt API.
Du behöver ett program som tar emot anpassade token. Till exempel https://jwt.ms ett Microsoft-ägt webbprogram som visar det avkodade innehållet i en token.
Programmet, till exempel https://jwt.ms måste registreras i Microsoft Entra-ID med appregistrering.
Du måste skapa en association mellan ditt program och ditt anpassade tillägg.
Du kan också skydda Azure-funktionen med en autentiseringsprovider. I den här artikeln använder vi ditt Microsoft Entra-ID.

REST-API

Rest API-slutpunkten ansvarar för att interagera med underordnade tjänster. Till exempel databaser, andra REST-API:er, LDAP-kataloger eller andra lager som innehåller de attribut som du vill lägga till i tokenkonfigurationen.

REST-API:et returnerar ett HTTP-svar till Microsoft Entra-ID som innehåller attributen. Attribut som returneras av rest-API:et läggs inte automatiskt till i en token. I stället måste ett programs princip för anspråksmappning konfigureras för att alla attribut ska inkluderas i token. I Microsoft Entra-ID ändrar en princip för anspråksmappning anspråken som genereras i token som utfärdats för specifika program.

REST API-schema

Använd följande REST API-datakontrakt för att utveckla ditt eget REST API för starthändelsen för tokenutfärdande. Schemat beskriver kontraktet för att utforma hanteraren för begäran och svar.

Ditt anpassade tillägg i Microsoft Entra-ID gör ett HTTP-anrop till rest-API:et med en JSON-nyttolast. JSON-nyttolasten innehåller användarprofildata, autentiseringskontextattribut och information om programmet som användaren vill logga in på. Värdet id i följande JSON är ett Microsoft-program som representerar tjänsten För Microsoft Entra-autentiseringshändelser. JSON-attributen kan användas för att utföra extra logik av ditt API. Begäran till ditt API är i följande 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"
            }
        }
    }
}

REST API-svarsformatet som Azure förväntar sig är i följande format, där anspråken DateOfBirth och CustomRoles returneras till Azure:

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

När en B2B-användare från Fabrikam-organisationen autentiserar till Contosos organisation har nyttolasten för begäran som skickas till REST-API:et elementet user i följande format:

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

Datatyper som stöds

I följande tabell visas de datatyper som stöds av anpassade anspråksproviders för starthändelsen för tokenutfärdning:

Datatyp	Stöds
String	Sant
Strängmatris	Sant
Boolean	Falsk
JSON	Falsk

Princip för anspråksmappning

I Microsoft Entra-ID ändrar en princip för anspråksmappning anspråken som genereras i token som utfärdats för specifika program. Den innehåller anspråk från din anpassade anspråksprovider och utfärdar dem till token.

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

Elementet ClaimsSchema innehåller listan över anspråk som ska mappas med följande attribut:

Källan beskriver källan till attributet , CustomClaimsProvider. Observera att det sista elementet innehåller ett fast värde med principversionen i testsyfte. Därför utelämnas source attributet.
ID är namnet på anspråken som returneras från den Azure-funktion som du skapade.

Viktigt!

Värdet för ID-attributet är skiftlägeskänsligt. Se till att du skriver anspråksnamnet exakt som det returnerades av Azure-funktionen.
JwtClaimType är ett valfritt namn på anspråket i den avgivna token för OpenID Anslut-appen. Du kan ange ett annat namn som returneras i JWT-token. Om API-svaret till exempel har värdet IDdateOfBirthkan det genereras som birthdate i token.

När du har skapat principen för anspråksmappning är nästa steg att ladda upp den till din Microsoft Entra-klientorganisation. Använd följande claimsMappingPolicy Graph API i din klientorganisation.

Viktigt!

Definitionselementet ska vara en matris med ett enda strängvärde. Strängen ska vara den strängifierade och undantagna versionen av principen för anspråksmappning. Du kan använda verktyg som https://jsontostring.com/ för att stränghantera principen för anspråksmappning.

Dela via