Résoudre les problèmes liés à votre API de fournisseur de revendications personnalisées

Les événements d’authentification et les fournisseurs de revendications personnalisées vous permettent de personnaliser l’expérience d’authentification Microsoft Entra en l’intégrant à des systèmes externes. Par exemple, vous pouvez créer une API de fournisseur de revendications personnalisées et configurer une application OpenID Connect ou une application SAML pour recevoir des jetons avec des revendications à partir d’un magasin externe.

Comportement d’erreur

Voici le comportement des erreurs lors de l’échec d’un appel d’API :

• Pour les applications OpenId Connect : Microsoft Entra redirige l’utilisateur vers l’application cliente avec une erreur. Aucun jeton n’est frappé.
• Pour les applications SAML : Microsoft Entra affiche un écran d’erreur à destination de l’utilisateur dans l’expérience d’authentification. L’utilisateur n’est pas redirigé vers l’application cliente.

Le code d’erreur renvoyé à l’application ou à l’utilisateur est générique. Pour résoudre les problèmes, reportez-vous auxcodes d’erreur dans les journaux de connexion.

Journalisation

Pour que vous puissiez résoudre les problèmes liés au point de terminaison de votre API REST de fournisseur de revendications personnalisées, l’API REST doit gérer la journalisation. Azure Functions et d’autres plateformes de développement d’API fournissent des solutions de journalisation avancées. Utilisez ces solutions pour obtenir des informations détaillées sur le comportement de vos API et résoudre les problèmes liés à leur fonctionnement.

Journaux de connexion Microsoft Entra

Conseil

Les étapes décrites dans cet article pourraient varier légèrement en fonction du portail de départ.

En plus de vos journaux d’API REST et des solutions de diagnostic des environnements d’hébergement, vous pouvez utiliser les journaux de connexion Microsoft Entra. Grâce aux journaux de connexion Microsoft Entra, vous pouvez rechercher les erreurs susceptibles d’affecter les connexions des utilisateurs. Les journaux de connexion Microsoft Entra fournissent des informations sur l’état HTTP, le code d’erreur, la durée d’exécution et le nombre de nouvelles tentatives lors de l’appel de l’API par Microsoft Entra ID.

Les journaux de connexion Microsoft Entra s’intègrent également à Azure Monitor. Vous pouvez configurer des alertes et des opérations de surveillance, ainsi que visualiser les données et les intégrer aux outils SIEM (Security Information and Event Management). Par exemple, vous pouvez configurer l’envoi de notifications lorsque le nombre d’erreurs dépasse le seuil de votre choix.

Pour accéder aux journaux de connexion Microsoft Entra :

1. Connectez-vous au centre d’administration de Microsoft Entra au minimum en tant qu’Administrateur d’application cloud.

2. Accédez à Identité>Applications>Applications d’entreprise.

3. Sélectionnez Journaux de connexion, puis sélectionnez le dernier journal de connexion.

4. Pour plus d’informations, sélectionnez l’onglet Événements d’authentification. Les informations relatives à l’appel de l’API REST de l’extension d’authentification personnalisée s’affichent, y compris les codes d’erreur correspondants.

   

Informations de référence sur les codes d’erreur

Utilisez le tableau suivant pour diagnostiquer un code d’erreur.

Code d'erreur	Nom de l’erreur	Description
1003000	EventHandlerUnexpectedError	Une erreur inattendue s’est produite lors du traitement d’un gestionnaire d’événements.
1003001	CustomExtenstionUnexpectedError	Une erreur inattendue s’est produite lors de l’appel d’une API d’extension personnalisée.
1003002	CustomExtensionInvalidHTTPStatus	L’API d’extension personnalisée a retourné un code d’état HTTP non valide. Vérifiez que l’API retourne un code d’état accepté et défini pour ce type d’extension personnalisé.
1003003	CustomExtensionInvalidResponseBody	Un problème est survenu lors de l’analyse du corps de réponse de l’extension personnalisée. Vérifiez que le corps de la réponse de l’API se trouve dans un schéma acceptable pour ce type d’extension personnalisé.
1003004	CustomExtensionThrottlingError	Le nombre de demandes d’extension personnalisées est trop élevé. Cette exception est levée pour les appels d’API d’extension personnalisée lorsque les seuils de limitation sont atteints.
1003005	CustomExtensionTimedOut	L’extension personnalisée n’a pas répondu dans les délais autorisés. Vérifiez que votre API répond dans les délais configurés pour l’extension personnalisée. Ce code peut également signifier que le jeton d’accès n’est pas valide. Suivez les étapes pour appeler votre API REST directement.
1003006	CustomExtensionInvalidResponseContentType	Le type de contenu de la réponse de l’extension personnalisée n’est pas « application/json ».
1003007	CustomExtensionNullClaimsResponse	L’API d’extension personnalisée a répondu avec un conteneur de revendications nul.
1003008	CustomExtensionInvalidResponseApiSchemaVersion	L’API d’extension personnalisée n’a pas répondu avec une valeur apiSchemaVersion identique à celle pour laquelle elle était appelée.
1003009	CustomExtensionEmptyResponse	Le corps de réponse de l’API d’extension personnalisée était nul, ce qui n’aurait pas dû être le cas.
1003010	CustomExtensionInvalidNumberOfActions	La réponse de l’API d’extension personnalisée présentait un nombre d’actions différent du nombre pris en charge pour ce type d’extension personnalisé.
1003011	CustomExtensionNotFound	L’extension personnalisée associée à un écouteur d’événements est introuvable.
1003012	CustomExtensionInvalidActionType	L’extension personnalisée a retourné un type d’action non valide pour la définition de ce type d’extension personnalisé.
1003014	CustomExtensionIncorrectResourceIdFormat	La propriété identifierUris du manifeste d’inscription de l’application pour l’extension personnalisée doit être au format « api://{nom de domaine complet}/{appid} ».
1003015	CustomExtensionDomainNameDoesNotMatch	Les valeurs targetUrl et resourceId de l’extension personnalisée doivent avoir le même nom de domaine complet.
1003016	CustomExtensionResourceServicePrincipalNotFound	Dans la valeur resourceId, appId doit correspondre à un principal de service réel du locataire.
1003017	CustomExtensionClientServicePrincipalNotFound	Le principal de service de la ressource d’extension personnalisée est introuvable dans le locataire.
1003018	CustomExtensionClientServiceDisabled	Le principal de service de la ressource d’extension personnalisée est désactivé dans ce locataire.
1003019	CustomExtensionResourceServicePrincipalDisabled	Le principal de service de la ressource d’extension personnalisée est désactivé dans ce locataire.
1003020	CustomExtensionIncorrectTargetUrlFormat	Le format de l’URL cible est incorrect. Il doit s’agir d’une URL valide commençant par https.
1003021	CustomExtensionPermissionNotGrantedToServicePrincipal	Le principal de service ne dispose pas du consentement administrateur pour le rôle d’application Microsoft Graph CustomAuthenticationExtensions.Receive.Payload (également appelé « autorisation d’application »). Ce consentement est requis pour que l’application puisse recevoir des requêtes HTTP d’extensions d’authentification personnalisées.
1003022	CustomExtensionMsGraphServicePrincipalDisabledOrNotFound	Le principal de service MS Graph est désactivé ou introuvable dans ce locataire.
1003023	CustomExtensionBlocked	Le point de terminaison utilisé pour l’extension personnalisée est bloqué par le service.
1003024	CustomExtensionResponseSizeExceeded	La taille de la réponse de l’extension personnalisée a dépassé la limite maximale.
1003025	CustomExtensionResponseClaimsSizeExceeded	La taille totale des revendications de la réponse d’extension personnalisée a dépassé la limite maximale.
1003026	CustomExtensionNullOrEmptyClaimKeyNotSupported	L’API d’extension personnalisée a répondu avec des revendications contenant une clé nulle ou vide.
1003027	CustomExtensionConnectionError	Erreur lors de la connexion à l’API d’extension personnalisée.

Appeler votre API REST directement

Votre API REST est protégée par un jeton d’accès Microsoft Entra. Vous pouvez tester votre API des façons suivantes :

• en obtenant un jeton d’accès avec une inscription d’application associée aux extensions d’authentification personnalisées
• Testez localement votre API en utilisant un outil de test d’API.

Obtenir un jeton d’accès

Une fois le jeton d’accès obtenu, passez-lui l’en-tête HTTP Authorization. Pour obtenir un jeton d’accès, procédez comme suit :

1. Connectez-vous au centre d’administration de Microsoft Entra au minimum en tant qu’Administrateur d’application cloud.

2. Accédez à Identité>Applications>Inscriptions d’applications.

3. Sélectionnez l’inscription de l’application API d’événements d’authentification Azure Functions, précédemment configurée dans Configurer un fournisseur de revendications personnalisé pour un événement d’émission de jeton.

4. Copiez l’ID de l’application.

5. Si vous n’avez pas créé de secret d’application, procédez comme suit :

   1. Sélectionnez Certificats et secrets>Clés secrètes client>Nouvelle clé secrète client.
   2. Ajoutez une description pour votre clé secrète client.
   3. Sélectionnez un délai d’expiration pour le secret ou spécifiez une durée de vie personnalisée.
   4. Sélectionnez Ajouter.
   5. Enregistrez la valeur du secret en prévision d’une utilisation dans le code de votre application cliente. Cette valeur secrète ne sera plus jamais affichée lorsque vous aurez quitté cette page.

6. Dans le menu, sélectionnez Exposer une API et copiez la valeur de l’URI associé à l’ID d’application. Par exemple : api://contoso.azurewebsites.net/00001111-aaaa-2222-bbbb-3333cccc4444.

7. Ouvrez votre outil de test d’API préféré, puis créez une requête HTTP.

8. Modifiez la méthode HTTP en lui attribuant la valeur POST.

9. Entrez l’URL suivante. Remplacez {tenantID} par votre ID de locataire.

   https://login.microsoftonline.com/{tenantID}/oauth2/v2.0/token
   

10. Dans la section Corps, sélectionnez form-data et ajoutez les clés suivantes :

    Clé	Valeur
    grant_type	client_credentials
    client_id	ID client de votre application
    client_secret	Clé secrète client de votre application
    scope	URI de l’ID de votre application, suivi de .default Par exemple, api://contoso.azurewebsites.net/00001111-aaaa-2222-bbbb-3333cccc4444/.default

11. Exécutez la requête HTTP et copiez le access_token dans l’application web https://jwt.ms.

12. Comparez le iss avec le nom de l’émetteur que vous avez configuré dans votre API.

13. Comparez le aud avec le nom de l’ID client que vous avez configuré dans votre API.

Outils de test d’API

Si vous souhaitez tester directement votre API en tirant parti de votre outil de test préféré, suivez ces étapes :

Remarque

Si vous avez utilisé le package NuGet Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents, désactivez la validation des jetons à des fins de test. Ouvrez local.settings.json et ajoutez le paramètre suivant

"AuthenticationEvents__BypassTokenValidation": true

Une fois votre test terminé, veillez à le supprimer.

1. Dans votre API REST, désactivez la validation de la revendicationappid ou azp. Découvrez comment modifier l’API de fonction que vous avez créée précédemment.

2. Créez une requête HTTP et définissez la méthode HTTP sur POST.

3. Dans la section Corps, sélectionnez Brut, puis JSON.

4. Collez le JSON suivant, qui imite la requête envoyée par Microsoft Entra ID à votre API REST.

   {
       "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 authentication extension ID>",
           "authenticationContext": {
               "correlationId": "<Enter correlation ID here>",
               "client": {
                   "ip": "127.0.0.1",
                   "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": "2023-08-16T00:00:00Z",
                   "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": "Casey Jensen",
                   "onPremisesSecurityIdentifier": "<Enter Security Identifier>",
                   "onPremisesUserPrincipalName": "Casey Jensen",
                   "preferredLanguage": "en-us",
                   "surname": "Jensen",
                   "userPrincipalName": "casey@contoso.com",
                   "userType": "Member"
               }
           }
       }
   }
   

   Conseil

   Si vous utilisez un jeton d’accès obtenu à partir de Microsoft Entra ID, sélectionnez Authorization (Autorisation), puis Bearer token (Jeton du porteur). Collez ensuite le jeton d’accès que vous avez reçu de la part de Microsoft Entra ID.

5. Sélectionnez Send (Envoyer), et vous devez recevoir une réponse JSON similaire à ce qui suit :

   {
       "data": {
           "@odata.type": "microsoft.graph.onTokenIssuanceStartResponseData",
           "actions": [
               {
                   "@odata.type": "microsoft.graph.tokenIssuanceStart.provideClaimsForToken",
                   "claims": {
                       "customClaim1": "customClaimValue1",
                       "customClaim2": [
                           "customClaimString1",
                           "customClaimString2" 
                       ]
                   }
               }
   
           ]
       }
   }
   

Améliorations courantes des performances

L’un des problèmes les plus courants concerne l’absence de réponse de votre API de fournisseur de revendications personnalisées dans le délai d’attente de deux secondes. Si votre API REST ne répond pas lors des tentatives suivantes, l’authentification échoue. Pour améliorer les performances de votre API REST, suivez les recommandations ci-dessous :

1. Si votre API accède à des API en aval, mettez en cache le jeton d’accès utilisé pour appeler ces API, de sorte qu’il ne soit pas nécessaire d’obtenir un nouveau jeton à chaque exécution.
2. Les services en aval sont souvent à l’origine des problèmes de performances. Ajoutez des options de journalisation afin d’enregistrer le délai d’appel des processus de l’ensemble des services en aval.
3. Si vous utilisez un fournisseur de services cloud pour héberger votre API, utilisez un plan d’hébergement qui permet à l’API de rester active. Pour Azure Functions, il peut s’agir des plans Premium ou Dedicated.
4. Exécutez des tests d’intégration automatisés pour vos authentifications. Vous pouvez également utiliser des outils de test d’API pour limiter vos tests aux performances de votre API.

Voir aussi

• Créer une API REST avec un événement de démarrage d’émission de jeton
• Configurer une application SAML pour recevoir des jetons avec des revendications d’un magasin externe
• Article Informations de référence sur les fournisseurs de revendications personnalisées.