Referentie voor aangepaste claimsaanbieder

2025-05-25

In deze handleiding vindt u meer informatie over het REST API-schema en de structuur van het toewijzingsbeleid voor claims voor aangepaste claimprovidergebeurtenissen.

Startgebeurtenis voor tokenuitgifte

Met de gebeurtenis voor tokenuitgifte van de aangepaste claimprovider kunt u toepassingstokens verrijken of aanpassen met informatie van externe systemen. Deze informatie die niet kan worden opgeslagen als onderdeel van het gebruikersprofiel in de Microsoft Entra-directory.

Overzicht van onderdelen

Voor het instellen en integreren van een aangepaste extensie met uw toepassing moeten meerdere onderdelen zijn verbonden. In het volgende diagram ziet u een weergave op hoog niveau van de configuratiepunten en relaties die zijn gemaakt om een aangepaste extensie te implementeren.

U moet een REST API-eindpunt openbaar beschikbaar hebben. In dit diagram wordt het vertegenwoordigd door Azure Function. De REST API genereert en retourneert aangepaste claims naar de aangepaste extensie. Deze is gekoppeld aan een Microsoft Entra-toepassingsregistratie.
U moet een aangepaste extensie configureren in Microsoft Entra-id, die is geconfigureerd om verbinding te maken met uw API.
U hebt een toepassing nodig die de aangepaste tokens ontvangt. Bijvoorbeeld https://jwt.ms een webtoepassing die eigendom is van Microsoft waarmee de gedecodeerde inhoud van een token wordt weergegeven.
De toepassing, zoals de https://jwt.ms moet worden geregistreerd bij Microsoft Entra ID met behulp van app-registratie.
U moet een koppeling maken tussen uw toepassing en uw aangepaste extensie.
U kunt de Azure-functie desgewenst beveiligen met een verificatieprovider. In dit artikel gebruiken we uw Microsoft Entra-id.

REST-API

Uw REST API-eindpunt is verantwoordelijk voor communicatie met downstreamservices. Bijvoorbeeld databases, andere REST API's, LDAP-directory's of andere opslaglocaties die de attributen bevatten die u wilt toevoegen aan de tokenconfiguratie.

De REST API retourneert een HTTP-antwoord naar Microsoft Entra ID met de attributen. Kenmerken die door uw REST API worden geretourneerd, worden niet automatisch toegevoegd aan een token. In plaats daarvan moet het claimtoewijzingsbeleid van een toepassing worden geconfigureerd om elk kenmerk dat in het token moet worden opgenomen, op te nemen. In Microsoft Entra ID wijzigt een claims mapping-beleid de claims die worden opgenomen in tokens die zijn uitgegeven voor specifieke toepassingen.

Aanvraag voor de REST API

Als u uw eigen REST API wilt ontwikkelen voor de start-gebeurtenis voor tokenuitgifte, gebruikt u het volgende REST API-gegevenscontract. In het schema wordt het contract beschreven om de aanvraag- en antwoordhandler te ontwerpen.

Uw aangepaste extensie in Microsoft Entra ID maakt een HTTP-aanroep naar uw REST API met een JSON-nettolading. De JSON-nettolading bevat gebruikersprofielgegevens, verificatiecontextkenmerken en informatie over de toepassing die de gebruiker wil aanmelden. De id waarde in de volgende JSON is een Microsoft-toepassing die de Microsoft Entra-verificatie-gebeurtenissenservice vertegenwoordigt. De JSON-kenmerken kunnen worden gebruikt om extra logica uit te voeren door uw API.

De volgende HTTP-aanvraag laat zien hoe Microsoft Entra uw REST API aanroept. Deze HTTP-aanvraag kan worden gebruikt om fouten in uw REST API op te sporen door een aanvraag van Microsoft Entra te simuleren.

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

Content-Type: application/json

[Request payload]

Het volgende JSON-document bevat een voorbeeld van een nettolading van een aanvraag:

{
    "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", 
                "mail": "casey@contoso.com",
                "onPremisesSamAccountName": "caseyjensen",
                "onPremisesSecurityIdentifier": "<Enter Security Identifier>",
                "onPremisesUserPrincipalName": "Casey Jensen",
                "preferredLanguage": "en-us",
                "surname": "Jensen",
                "userPrincipalName": "casey@contoso.com",
                "userType": "Member"
            }
        }
    }
}

Wanneer een B2B-gebruiker van de Fabrikam-organisatie authenticeert bij de organisatie van Contoso, bevat de aanvraagpayload die naar de REST API wordt verzonden het user element in het volgende formaat:

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

Antwoord van de REST API

Microsoft Entra ID verwacht een REST API-antwoord in de volgende HTTP.

HTTP/1.1 200 OK

Content-Type: application/json

[JSON document]

Geef in het HTTP-antwoord het volgende JSON-document op, waarbij de claims DateOfBirth worden geretourneerd en CustomRoles naar Microsoft Entra worden geretourneerd:

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

Ondersteunde gegevenstypen

In de volgende tabel ziet u de gegevenstypen die worden ondersteund door aangepaste claims-providers bij de startgebeurtenis van tokenuitgifte.

Gegevenstype	Ondersteund
Snaar / Touwtje	Klopt
Tekenreeksmatrix	Klopt
Booleaan	Onwaar
JSON	Onwaar

Limieten voor claimgrootte

De maximale claimgrootte die een claimprovider kan retourneren, is beperkt tot 3 KB. Dit is de som van alle sleutel- en waardeparen die worden geretourneerd door de REST API.

Beleid voor claimtoewijzing

In Microsoft Entra ID wijzigt een claims mapping-beleid de claims die worden opgenomen in tokens die zijn uitgegeven voor specifieke toepassingen. Het bevat claims van uw aangepaste claimprovider en geeft deze uit in het 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"
        }]
    }
}

Het ClaimsSchema element bevat de lijst met claims die gemapt moeten worden, voorzien van de volgende kenmerken:

De bron beschrijft de bron van het kenmerk, de CustomClaimsProvider. Let op: het laatste element bevat een vaste waarde met de beleidsversie voor testdoeleinden. source Het kenmerk wordt dus weggelaten.
Id is de naam van de claims die worden geretourneerd vanuit de Azure-functie die u hebt gemaakt.

Belangrijk

De waarde van het ID-attribuut is hoofdlettergevoelig. Zorg ervoor dat u de claimnaam precies typt zoals deze wordt geretourneerd door de Azure-functie.
JwtClaimType is een optionele naam van de claim in het verzonden token voor de OpenID Connect-app. Hiermee kunt u een andere naam opgeven die wordt geretourneerd in het JWT-token. Als het API-antwoord bijvoorbeeld een ID waarde dateOfBirthheeft, kan deze worden verzonden zoals birthdate in het token.

Zodra u het claimtoewijzingsbeleid hebt gemaakt, is de volgende stap het uploaden naar uw Microsoft Entra-tenant. Gebruik de volgende claimsMappingPolicy Graph API in uw tenant.

Belangrijk

Het definitie-element moet een matrix met één tekenreekswaarde zijn. De tekenreeks moet de versievorm zijn van uw claimtoewijzingsbeleid die wordt geserialiseerd en geëscaped. U kunt hulpmiddelen zoals https://jsontostring.com/ gebruiken om uw claimtoewijzingsbeleid naar een string om te zetten.