Referentie voor aangepaste claimsprovider

Artikel
03/18/2024

In dit naslagartikel vindt u meer informatie over het REST API-schema en de structuur van het toewijzingsbeleid voor claims voor aangepaste claimproviders.

Start-gebeurtenis 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 winkels die de kenmerken bevatten die u wilt toevoegen aan de tokenconfiguratie.

De REST API retourneert een HTTP-antwoord op De Microsoft Entra-id die de kenmerken bevat. 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 voor elk kenmerk dat in het token moet worden opgenomen. In Microsoft Entra ID wijzigt een claimtoewijzingsbeleid de claims die worden verzonden in tokens die zijn uitgegeven voor specifieke toepassingen.

REST API-schema

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 aanvraag voor uw API heeft de volgende indeling:

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

De REST API-antwoordindeling die door Azure wordt verwacht, heeft de volgende indeling, waarbij de claims DateOfBirth worden geretourneerd en CustomRoles naar Azure worden geretourneerd:

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

Wanneer een B2B-gebruiker van de Fabrikam-organisatie wordt geverifieerd bij de organisatie van Contoso, heeft de nettolading van de aanvraag die naar de REST API wordt verzonden, het user element in de volgende indeling:

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

Ondersteunde gegevenstypen

In de volgende tabel ziet u de gegevenstypen die worden ondersteund door aangepaste claimproviders voor de start-gebeurtenis voor tokenuitgifte:

Gegevenstype	Ondersteund
String	Waar
Tekenreeksmatrix	Waar
Booleaanse waarde	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.

Claimtoewijzingsbeleid

In Microsoft Entra ID wijzigt een claimtoewijzingsbeleid de claims die worden verzonden 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 moeten worden toegewezen met 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-kenmerk 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 tekenreeks en escape-versie van uw claimtoewijzingsbeleid zijn. U kunt hulpprogramma's gebruiken om https://jsontostring.com/ uw claimtoewijzingsbeleid te stringificeren.

Delen via