Informations de référence sur les fournisseurs de revendications personnalisées

Article
03/20/2024

Dans cet article de référence, vous pouvez en savoir plus sur le schéma API REST et la structure de stratégie de mappage des revendications pour les événements liés aux fournisseurs de revendications personnalisées.

Événement de démarrage d’émission de jetons

L’événement d’émission de jetons du fournisseur de revendications personnalisées vous permet d’enrichir ou de personnaliser les jetons d’application avec des informations provenant de systèmes externes. Ces informations ne peuvent pas être stockées dans le cadre du profil utilisateur dans l’annuaire Microsoft Entra.

Vue d’ensemble des composants

La configuration et l’intégration d’une extension personnalisée à votre application nécessitent la connexion de plusieurs composants. Le diagramme suivant montre une vue d’ensemble des points de configuration et les relations créées pour implémenter une extension personnalisée.

Vous devez disposer d’un point de terminaison API REST disponible publiquement. Dans ce diagramme, il est représenté par une fonction Azure. L’API REST génère et retourne des revendications personnalisées à l’extension personnalisée. Elle est associée à une inscription d’application Microsoft Entra.
Vous devez configurer une extension personnalisée dans Microsoft Entra ID, qui est configurée pour se connecter à votre API.
Vous avez besoin d’une application qui reçoit les jetons personnalisés. Par exemple, https://jwt.ms, une application web appartenant à Microsoft qui affiche le contenu décodé d’un jeton.
L’application, telle que https://jwt.ms, doit être inscrite dans Microsoft Entra ID à l’aide de l’inscription d’application.
Vous devez créer une association entre votre application et votre extension personnalisée.
Vous pouvez éventuellement sécuriser la fonction Azure avec un fournisseur d’authentification. Dans cet article, nous utilisons Microsoft Entra ID.

REST API

Votre point de terminaison API REST fait office d’interface avec les services en aval. Par exemple, les bases de données, les autres API REST, les annuaires LDAP ou tous les autres magasins qui contiennent les attributs à ajouter à la configuration du jeton.

L’API REST retourne à Microsoft Entra ID une réponse HTTP contenant les attributs. Les attributs retournés par l’API REST ne sont pas automatiquement ajoutés à un jeton. En lieu et place, la stratégie de mappage des revendications d’une application doit être configurée pour que les attributs soient inclus dans le jeton. Dans Microsoft Entra ID, une stratégie de mappage des revendications modifie les revendications comprises dans les jetons émis pour des applications spécifiques.

Schéma API REST

Pour développer votre propre API REST pour l’événement de démarrage d’émission de jetons, utilisez le contrat de données API REST suivant. Le schéma décrit le contrat qui permet de concevoir le gestionnaire de requêtes et de réponses.

Votre extension personnalisée dans Microsoft Entra ID effectue un appel HTTP à votre API REST avec une charge utile JSON. La charge utile JSON contient des données de profil utilisateur, des attributs de contexte d’authentification et des informations sur l’application à laquelle l’utilisateur souhaite se connecter. La valeur id dans le JSON suivant est une application Microsoft représentant le service d’événements d’authentification Microsoft Entra. Les attributs JSON peuvent être utilisés par votre API pour effectuer une logique supplémentaire. La requête adressée à votre API est au format suivant :

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

Le format de réponse de l’API REST attendu par Azure est le suivant, où les revendications DateOfBirth et CustomRoles sont retournées à Azure :

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

Lorsqu’un utilisateur B2B de l’organisation Fabrikam s’authentifie auprès de l’organisation de Contoso, la charge utile de requête envoyée à l’API REST contient l’élément user au format suivant :

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

Types de données pris en charge

Le tableau suivant montre les types de données pris en charge par les fournisseurs de revendications personnalisées pour l’événement de démarrage d’émission de jetons :

Type de données	Pris en charge
String	True
Tableau de chaînes	True
Boolean	False
JSON	False

Stratégie de mappage des revendications

Dans Microsoft Entra ID, une stratégie de mappage des revendications modifie les revendications comprises dans les jetons émis pour des applications spécifiques. Elle inclut les revendications de votre fournisseur de revendications personnalisées et émises dans le jeton.

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

L’élément ClaimsSchema contient la liste des revendications à mapper avec les attributs suivants :

Source décrit la source de l’attribut, CustomClaimsProvider. Le dernier élément contient une valeur fixe avec la version de stratégie, à des fins de test. Par conséquent, l’attribut source est omis.
ID correspond au nom des revendications retourné par la fonction Azure.

Important

La valeur de l’attribut ID respecte la casse. Veillez à taper le nom de la revendication exactement tel qu’il a été retourné par la fonction Azure.
JwtClaimType correspond à un nom de revendication facultatif dans le jeton émis pour l’application OpenID Connect. Il vous permet de fournir un autre nom retourné dans le jeton JWT. Par exemple, si la réponse de l’API contient une valeur IDdateOfBirth, elle peut être émise en tant que birthdate dans le jeton.

Une fois la stratégie de mappage des revendications créée, l’étape suivante consiste à la charger dans votre locataire Microsoft Entra. Utilisez l’API Graph claimsMappingPolicy suivante dans votre locataire.

Important

L’élément definition doit être un tableau avec une seule valeur de chaîne. La chaîne doit être la version convertie en chaîne et placée dans une séquence d’échappement de votre stratégie de mappage des revendications. Vous pouvez utiliser des outils tels que https://jsontostring.com/ pour convertir votre stratégie de mappage des revendications en chaîne.

Share via