Problemen met de API van uw aangepaste claimprovider oplossen

Met verificatie-gebeurtenissen en aangepaste claimproviders kunt u de Microsoft Entra-verificatie-ervaring aanpassen door te integreren met externe systemen. U kunt bijvoorbeeld een AANGEPASTe claimprovider-API maken en een OpenID Connect-app of SAML-app configureren voor het ontvangen van tokens met claims uit een externe store.

Foutgedrag

Wanneer een API-aanroep mislukt, is het foutgedrag als volgt:

• Voor OpenId Connect-apps - Microsoft Entra ID leidt de gebruiker terug naar de clienttoepassing met een fout. Een token is niet gemunt.
• Voor SAML-apps - Microsoft Entra-id toont de gebruiker een foutscherm in de verificatie-ervaring. De gebruiker wordt niet teruggeleid naar de clienttoepassing.

De foutcode die wordt teruggestuurd naar de toepassing of de gebruiker is algemeen. Als u problemen wilt oplossen, controleert u de aanmeldingslogboeken voor de foutcodes.

Logboekregistratie

Om problemen met het REST API-eindpunt van uw aangepaste claimprovider op te lossen, moet de REST API logboekregistratie verwerken. Azure Functions en andere API-ontwikkelplatforms bieden uitgebreide oplossingen voor logboekregistratie. Gebruik deze oplossingen om gedetailleerde informatie op te halen over het gedrag van uw API's en om problemen met uw API-logica op te lossen.

Aanmeldingslogboeken van Microsoft Entra

Tip

Stappen in dit artikel kunnen enigszins variëren op basis van de portal waaruit u begint.

U kunt ook Aanmeldingslogboeken van Microsoft Entra gebruiken naast uw REST API-logboeken en diagnostische oplossingen voor de hostingomgeving. Met behulp van Microsoft Entra-aanmeldingslogboeken kunt u fouten vinden die van invloed kunnen zijn op de aanmeldingen van gebruikers. De aanmeldingslogboeken van Microsoft Entra bevatten informatie over de HTTP-status, foutcode, uitvoeringsduur en het aantal nieuwe pogingen dat de API heeft aangeroepen door Microsoft Entra-id.

Aanmeldingslogboeken van Microsoft Entra kunnen ook worden geïntegreerd met Azure Monitor. U kunt waarschuwingen en bewaking instellen, de gegevens visualiseren en integreren met SIEM-hulpprogramma's (Security Information and Event Management). U kunt bijvoorbeeld meldingen instellen als het aantal fouten een bepaalde drempelwaarde overschrijdt die u kiest.

Voor toegang tot de aanmeldingslogboeken van Microsoft Entra:

1. Meld u als cloudtoepassingsbeheerder aan bij het Microsoft Entra-beheercentrum.

2. Blader naar Bedrijfstoepassingen voor identiteitstoepassingen>>.

3. Selecteer aanmeldingslogboeken en selecteer vervolgens het meest recente aanmeldingslogboek.

4. Selecteer het tabblad Verificatiegebeurtenissen voor meer informatie. Informatie met betrekking tot de REST API-aanroep van de aangepaste verificatie-extensie wordt weergegeven, inclusief eventuele foutcodes.

   

Naslaginformatie over foutcodes

Gebruik de volgende tabel om een foutcode te diagnosticeren.

Foutcode	Foutnaam	Beschrijving
1003000	EventHandlerUnexpectedError	Er is een onverwachte fout opgetreden bij het verwerken van een gebeurtenis-handler.
1003001	CustomExtenstionUnexpectedError	Er is een onverwachte fout opgetreden bij het aanroepen van een aangepaste extensie-API.
1003002	CustomExtensionInvalidHTTPStatus	De AANGEPASTe extensie-API heeft een ongeldige HTTP-statuscode geretourneerd. Controleer of de API een geaccepteerde statuscode retourneert die is gedefinieerd voor dat aangepaste extensietype.
1003003	CustomExtensionInvalidResponseBody	Er is een probleem opgetreden bij het parseren van de antwoordtekst van de aangepaste extensie. Controleer of de hoofdtekst van het API-antwoord zich in een acceptabel schema bevindt voor dat aangepaste extensietype.
1003004	CustomExtensionThrottlingError	Er zijn te veel aangepaste extensieaanvragen. Deze uitzondering wordt gegenereerd voor API-aanroepen voor aangepaste extensies wanneer beperkingslimieten worden bereikt.
1003005	CustomExtensionTimedOut	De aangepaste extensie heeft niet gereageerd binnen de toegestane time-out. Controleer of uw API reageert binnen de geconfigureerde time-out voor de aangepaste extensie. Het kan ook aangeven dat het toegangstoken ongeldig is. Volg de stappen om uw REST API rechtstreeks aan te roepen.
1003006	CustomExtensionInvalidResponseContentType	Het antwoordinhoudstype van de aangepaste extensie is geen 'application/json'.
1003007	CustomExtensionNullClaimsResponse	De AANGEPASTe extensie-API heeft gereageerd met een null-claimtas.
1003008	CustomExtensionInvalidResponseApiSchemaVersion	De AANGEPASTe extensie-API heeft niet gereageerd met dezelfde apiSchemaVersion waarvoor deze werd aangeroepen.
1003009	CustomExtensionEmptyResponse	De antwoordtekst van de aangepaste extensie-API was null toen dat niet werd verwacht.
1003010	CustomExtensionInvalidNumberOfActions	Het antwoord van de aangepaste extensie-API bevat een ander aantal acties dan de acties die worden ondersteund voor dat aangepaste extensietype.
1003011	CustomExtensionNotFound	Kan de aangepaste extensie die is gekoppeld aan een gebeurtenislistener niet vinden.
1003012	CustomExtensionInvalidActionType	De aangepaste extensie heeft een ongeldig actietype geretourneerd dat is gedefinieerd voor dat aangepaste extensietype.
1003014	CustomExtensionIncorrectResourceIdFormat	De eigenschap identifierUris in het manifest voor de toepassingsregistratie voor de aangepaste extensie moet de indeling 'api://{fully qualified domain name}/{appid} hebben.
1003015	CustomExtensionDomainNameDoesNotMatch	De targetUrl en resourceId van de aangepaste extensie moeten dezelfde volledig gekwalificeerde domeinnaam hebben.
1003016	CustomExtensionResourceServicePrincipalNotFound	De appId van de resourceId van de aangepaste extensie moet overeenkomen met een echte service-principal in de tenant.
1003017	CustomExtensionClientServicePrincipalNotFound	De service-principal voor de aangepaste extensieresource is niet gevonden in de tenant.
1003018	CustomExtensionClientServiceDisabled	De service-principal voor de aangepaste extensieresource is uitgeschakeld in deze tenant.
1003019	CustomExtensionResourceServicePrincipalDisabled	De service-principal voor de aangepaste extensieresource is uitgeschakeld in deze tenant.
1003020	CustomExtensionIncorrectTargetUrlFormat	De doel-URL heeft een onjuiste indeling. Het moet een geldige URL zijn die begint met https.
1003021	CustomExtensionPermissionNotGrantedToServicePrincipal	De service-principal heeft geen beheerderstoestemming voor de microsoft Graph CustomAuthenticationExtensions.Receive.Payload-app-rol (ook wel toepassingsmachtiging genoemd) die vereist is voor het ontvangen van HTTP-aanvragen voor aangepaste verificatie-extensies voor de app.
1003022	CustomExtensionMsGraphServicePrincipalDisabledOrNotFound	De MS Graph-service-principal is uitgeschakeld of niet gevonden in deze tenant.
1003023	CustomExtensionBlocked	Het eindpunt dat wordt gebruikt voor de aangepaste extensie, wordt geblokkeerd door de service.
1003024	CustomExtensionResponseSizeExceeded	De antwoordgrootte van de aangepaste extensie heeft de maximumlimiet overschreden.
1003025	CustomExtensionResponseClaimsSizeExceeded	De totale grootte van claims in het aangepaste extensieantwoord heeft de maximumlimiet overschreden.
1003026	CustomExtensionNullOrEmptyClaimKeyNotSupported	De aangepaste extensie-API heeft gereageerd met claims die null- of lege sleutel bevatten'
1003027	CustomExtensionConnectionError	Fout bij het maken van verbinding met de aangepaste extensie-API.

Uw REST API rechtstreeks aanroepen

Uw REST API wordt beveiligd door een Microsoft Entra-toegangstoken. U kunt uw API testen op;

• Een toegangstoken verkrijgen met een toepassingsregistratie die is gekoppeld aan de aangepaste verificatie-extensies
• Test uw API lokaal met behulp van een API-testprogramma.

HULPPROGRAMMA's voor API-tests

1. Voor lokale ontwikkelings- en testdoeleinden opent u local.settings.json en vervangt u de code door de volgende JSON:

   {
     "IsEncrypted": false,
     "Values": {
       "AzureWebJobsStorage": "",
       "AzureWebJobsSecretStorageType": "files",
       "FUNCTIONS_WORKER_RUNTIME": "dotnet",
       "AuthenticationEvents__BypassTokenValidation" : false
     }
   }
   

   Notitie

   Als u het NuGet-pakket Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents hebt gebruikt, moet u dit instellen "AuthenticationEvents__BypassTokenValidation" : true voor lokale testdoeleinden.

2. Maak met behulp van uw favoriete API-testprogramma een nieuwe HTTP-aanvraag en stel de HTTP-methode in op POST.

3. Gebruik de volgende JSON-hoofdtekst die de aanvraag imiteert die microsoft Entra-id naar uw REST API verzendt.

   {
       "type": "microsoft.graph.authenticationEvent.tokenIssuanceStart",
       "source": "/tenants/aaaabbbb-0000-cccc-1111-dddd2222eeee/applications/00001111-aaaa-2222-bbbb-3333cccc4444",
       "data": {
           "@odata.type": "microsoft.graph.onTokenIssuanceStartCalloutData",
           "tenantId": "aaaabbbb-0000-cccc-1111-dddd2222eeee",
           "authenticationEventListenerId": "11112222-bbbb-3333-cccc-4444dddd5555",
           "customAuthenticationExtensionId": "22223333-cccc-4444-dddd-5555eeee6666",
           "authenticationContext": {
               "correlationId": "aaaa0000-bb11-2222-33cc-444444dddddd",
               "client": {
                   "ip": "127.0.0.1",
                   "locale": "en-us",
                   "market": "en-us"
               },
               "protocol": "OAUTH2.0",
               "clientServicePrincipal": {
                   "id": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
                   "appId": "00001111-aaaa-2222-bbbb-3333cccc4444",
                   "appDisplayName": "My Test application",
                   "displayName": "My Test application"
               },
               "resourceServicePrincipal": {
                   "id": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
                   "appId": "00001111-aaaa-2222-bbbb-3333cccc4444",
                   "appDisplayName": "My Test application",
                   "displayName": "My Test application"
               },
               "user": {
                   "companyName": "Casey Jensen",
                   "createdDateTime": "2023-08-16T00:00:00Z",
                   "displayName": "Casey Jensen",
                   "givenName": "Casey",
                   "id": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
                   "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"
               }
           }
       }
   }
   

   Tip

   Als u een toegangstoken gebruikt dat is verkregen uit Microsoft Entra-id, selecteert u Autorisatie en selecteert u vervolgens het Bearer-token, plakt u het toegangstoken dat u hebt ontvangen van Microsoft Entra-id.

4. Selecteer Verzenden en u moet een JSON-antwoord ontvangen dat er ongeveer als volgt uitziet:

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

Een toegangstoken verkrijgen

Nadat u een toegangstoken hebt verkregen, geeft u dit door aan de HTTP-header Authorization . Voer de volgende stappen uit om een toegangstoken te verkrijgen:

1. Meld u als cloudtoepassingsbeheerder aan bij het Microsoft Entra-beheercentrum.

2. Blader naar toepassingsregistraties voor identiteitstoepassingen>>.

3. Selecteer de API-app-registratie van azure Functions-verificatiegebeurtenissen, die eerder zijn geconfigureerd bij het configureren van een aangepaste claimprovider voor een tokenuitgiftegebeurtenis.

4. Kopieer de toepassings-id.

5. Als u nog geen app-geheim hebt gemaakt, voert u de volgende stappen uit:

   1. Selecteer Certificaten en geheimen Clientgeheimen>>Nieuw clientgeheim.
   2. Voeg een beschrijving voor uw clientgeheim toe.
   3. Selecteer een vervaldatum voor het geheim of geef een aangepaste levensduur op.
   4. Selecteer Toevoegen.
   5. Noteer de waarde van het geheim voor gebruik in uw clienttoepassingscode. Deze geheimwaarde wordt nooit meer weergegeven nadat u deze pagina hebt verlaten.

6. Selecteer een API beschikbaar maken in het menu en kopieer de waarde van de URI van de toepassings-id. Bijvoorbeeld: api://contoso.azurewebsites.net/00001111-aaaa-2222-bbbb-3333cccc4444.

7. Open uw favoriete API-testprogramma en maak een nieuwe HTTP-query.

8. Wijzig de HTTP-methode in POST.

9. Voer de volgende URL in. Vervang de {tenantID} door uw tenant-id.

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

10. Selecteer onder de hoofdtekst formuliergegevens en voeg de volgende sleutels toe:

    Sleutel	Weergegeven als
    grant_type	client_credentials
    client_id	De client-id van uw toepassing.
    client_secret	Het clientgeheim van uw toepassing.
    scope	De URI van de toepassings-id van uw toepassing en voeg vervolgens toe .default. Bijvoorbeeld api://contoso.azurewebsites.net/00001111-aaaa-2222-bbbb-3333cccc4444/.default

11. Voer de HTTP-query uit en kopieer de access_token query naar de https://jwt.ms web-app.

12. Vergelijk de iss naam van de uitgever die u hebt geconfigureerd in uw API.

13. Vergelijk de aud met de client-id die u hebt geconfigureerd in uw API.

Algemene prestatieverbeteringen

Een van de meest voorkomende problemen is dat de API van uw aangepaste claimprovider niet binnen de time-out van twee seconden reageert. Als uw REST API niet reageert bij volgende nieuwe pogingen, mislukt de verificatie. Volg de onderstaande suggesties om de prestaties van uw REST API te verbeteren:

1. Als uw API toegang heeft tot downstream-API's, slaat u het toegangstoken op dat wordt gebruikt om deze API's aan te roepen, zodat er bij elke uitvoering geen nieuw token hoeft te worden verkregen.
2. Prestatieproblemen zijn vaak gerelateerd aan downstreamservices. Voeg logboekregistratie toe, waarmee de procestijd wordt vastgelegd voor het aanroepen van downstreamservices.
3. Als u een cloudprovider gebruikt om uw API te hosten, gebruikt u een hostingabonnement waarmee de API altijd 'warm' blijft. Voor Azure Functions kan dit het Premium- of Dedicated-abonnement zijn.
4. Voer geautomatiseerde integratietests uit voor uw verificaties. U kunt ook API-testhulpprogramma's gebruiken om alleen uw API-prestaties te testen.

Zie ook

• Een REST API maken met een start-gebeurtenis voor tokenuitgifte
• Een SAML-app configureren voor het ontvangen van tokens met claims uit een externe store
• Referentieartikel voor aangepaste claimsprovider .