Delen via

Problemen met uw aangepaste verificatie-extensie 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 configureren voor het ontvangen van tokens met claims uit een externe store.

Error behavior

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

  • Voor OpenId Connect-apps - Microsoft Entra ID stuurt de gebruiker terug naar de clienttoepassing met een foutmelding. Een token is niet aangemaakt.
  • 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. To troubleshoot, check the sign-in logs for the error codes.

Logging

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

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.

Microsoft Entra sign-in logs also integrate with 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 aan bij het Microsoft Entra-beheercentrum als ten minste een cloudtoepassingsbeheerder.

  2. Browse to Entra ID>Enterprise apps.

  3. Select Sign-in logs, and then select the latest sign-in log.

  4. For more details, select the Authentication Events tab. Information related to the custom authentication extension REST API call is displayed, including any error codes.

    Schermopname van de informatie over verificatie-gebeurtenissen.

Foutcodes overzicht

Gebruik de volgende tabel om een foutcode te diagnosticeren.

Error code Error name Description
1003000 EventHandlerUnexpectedError Er is een onverwachte fout opgetreden bij het verwerken van een gebeurtenis-handler.
1003001 CustomExtensionUnexpectedError 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 werd gegenereerd voor API-aanroepen voor aangepaste extensies wanneer limieten voor throttling 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 lege claim-tas.
1003008 CustomExtensionInvalidResponseApiSchemaVersion De aangepaste extensie-API reageerde niet met dezelfde "apiSchemaVersion" waarvoor het 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 The identifierUris property in the manifest for the application registration for the custom extension, should be in the format of "api://{fully qualified domain name}/{appid}.
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 serviceprincipal van de aangepaste extensieresource is gedeactiveerd in deze tenant.
1003019 CustomExtensionResourceServicePrincipalDisabled De serviceprincipal van de aangepaste extensieresource is gedeactiveerd 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 aangetroffen 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 door;

  • Obtaining an access token with an application registration associated with the custom authentication extensions
  • Test uw API lokaal met behulp van een API-testprogramma.

  1. For local development and testing purposes, open local.settings.json and replace the code with the following JSON:

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

    Note

    If you used the Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents NuGet package, be sure to set "AuthenticationEvents__BypassTokenValidation" : true for local testing purposes.

  2. Using your preferred API testing tool, create a new HTTP request and set the HTTP method to 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

    If you're using an access token obtained from Microsoft Entra ID, select Authorization and then select Bearer token, then paste the access token you received from Microsoft Entra ID.

  4. Select Send, and you should receive a JSON response similar to the following:

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

        ]
    }
}

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.

See also

  • Last updated on