Felsöka API:et för din anpassade anspråksprovider

Med autentiseringshändelser och anpassade anspråksproviders kan du anpassa autentiseringsupplevelsen för Microsoft Entra genom att integrera med externa system. Du kan till exempel skapa ett API för en anpassad anspråksprovider och konfigurera en OpenID-Anslut-app eller SAML-app för att ta emot token med anspråk från ett externt arkiv.

Felbeteende

När ett API-anrop misslyckas är felbeteendet följande:

• För OpenId Anslut-appar – Microsoft Entra-ID omdirigerar användaren tillbaka till klientprogrammet med ett fel. En token har inte präglats.
• För SAML-appar – Microsoft Entra-ID visar användaren en felskärm i autentiseringsupplevelsen. Användaren omdirigeras inte tillbaka till klientprogrammet.

Felkoden som skickas tillbaka till programmet eller användaren är allmän. Om du vill felsöka kontrollerar du inloggningsloggarna efter felkoderna.

Loggning

För att kunna felsöka problem med rest-API-slutpunkten för din anpassade anspråksprovider måste REST-API:et hantera loggning. Azure Functions och andra API-utvecklingsplattformar tillhandahåller djupgående loggningslösningar. Använd dessa lösningar för att få detaljerad information om api:ernas beteende och felsöka API-logiken.

Inloggningsloggar för Microsoft Entra

Dricks

Stegen i den här artikeln kan variera något beroende på vilken portal du börjar från.

Du kan också använda Inloggningsloggar för Microsoft Entra utöver dina REST API-loggar och vara värd för lösningar för miljödiagnostik. Med microsoft Entra-inloggningsloggar kan du hitta fel som kan påverka användarnas inloggningar. Inloggningsloggarna för Microsoft Entra innehåller information om HTTP-status, felkod, körningstid och antal återförsök som inträffade som API:et anropades av Microsoft Entra-ID.

Microsoft Entra-inloggningsloggar integreras också med Azure Monitor. Du kan konfigurera aviseringar och övervakning, visualisera data och integrera med SIEM-verktyg (säkerhetsinformation och händelsehantering). Du kan till exempel konfigurera meddelanden om antalet fel överskrider ett visst tröskelvärde som du väljer.

Så här kommer du åt inloggningsloggarna för Microsoft Entra:

1. Logga in på administrationscentret för Microsoft Entra som minst molnprogramadministratör.

2. Bläddra till Identity>Applications Enterprise-program.>

3. Välj Inloggningsloggar och välj sedan den senaste inloggningsloggen.

4. Mer information finns på fliken Autentiseringshändelser . Information om REST API-anropet för det anpassade autentiseringstillägget visas, inklusive eventuella felkoder.

   

Referens för felkoder

Använd följande tabell för att diagnostisera en felkod.

Felkod	Felnamn	beskrivning
1003000	EventHandlerUnexpectedError	Ett oväntat fel uppstod vid bearbetning av en händelsehanterare.
1003001	CustomExtenstionUnexpectedError	Ett oväntat fel uppstod när ett API för anpassat tillägg anropades.
1003002	CustomExtensionInvalidHTTPStatus	API:et för anpassat tillägg returnerade en ogiltig HTTP-statuskod. Kontrollera att API:et returnerar en godkänd statuskod som definierats för den anpassade tilläggstypen.
1003003	CustomExtensionInvalidResponseBody	Det gick inte att parsa det anpassade tilläggets svarstext. Kontrollera att API-svarstexten är i ett acceptabelt schema för den anpassade tilläggstypen.
1003004	CustomExtensionThrottlingError	Det finns för många anpassade tilläggsbegäranden. Det här undantaget utlöses för API-anrop för anpassade tillägg när begränsningsgränser nås.
1003005	CustomExtensionTimedOut	Det anpassade tillägget svarade inte inom den tillåtna tidsgränsen. Kontrollera att DITT API svarar inom den konfigurerade tidsgränsen för det anpassade tillägget. Det kan också indikera att åtkomsttoken är ogiltig. Följ stegen för att anropa rest-API:et direkt.
1003006	CustomExtensionInvalidResponseContentType	Det anpassade tilläggets svarsinnehållstyp är inte "application/json".
1003007	CustomExtensionNullClaimsResponse	API:et för anpassat tillägg svarade med en null-anspråkspåse.
1003008	CustomExtensionInvalidResponseApiSchemaVersion	API:et för anpassat tillägg svarade inte med samma apiSchemaVersion som det anropades för.
1003009	CustomExtensionEmptyResponse	Api-svarstexten för det anpassade tillägget var null när det inte förväntades.
1003010	CustomExtensionInvalidNumberOfActions	API-svaret för anpassat tillägg innehöll ett annat antal åtgärder än de som stöds för den anpassade tilläggstypen.
1003011	CustomExtensionNotFound	Det gick inte att hitta det anpassade tillägget som är associerat med en händelselyssnare.
1003012	CustomExtensionInvalidActionType	Det anpassade tillägget returnerade en ogiltig åtgärdstyp som definierats för den anpassade tilläggstypen.
1003014	CustomExtensionIncorrectResourceIdFormat	Egenskapen identifierUris i manifestet för programregistreringen för det anpassade tillägget ska vara i formatet "api://{fullständigt domännamn}/{appid}.
1003015	CustomExtensionDomainNameDoesNotMatch	TargetUrl och resourceId för det anpassade tillägget ska ha samma fullständigt kvalificerade domännamn.
1003016	CustomExtensionResourceServicePrincipalNotFound	AppId för det anpassade tillägget resourceId ska motsvara ett verkligt huvudnamn för tjänsten i klientorganisationen.
1003017	CustomExtensionClientServicePrincipalNotFound	Det gick inte att hitta resurstjänstens huvudnamn för det anpassade tillägget i klientorganisationen.
1003018	CustomExtensionClientServiceDisabled	Resurstjänstens huvudnamn för det anpassade tillägget är inaktiverat i den här klientorganisationen.
1003019	CustomExtensionResourceServicePrincipalDisabled	Resurstjänstens huvudnamn för det anpassade tillägget är inaktiverat i den här klientorganisationen.
1003020	CustomExtensionIncorrectTargetUrlFormat	Mål-URL:en är i ett felaktigt format. Det måste vara en giltig URL som börjar med https.
1003021	CustomExtensionPermissionNotGrantedToServicePrincipal	Tjänstens huvudnamn har inte administratörsmedgivande för approllen Microsoft Graph CustomAuthenticationExtensions.Receive.Payload (även kallat programbehörighet) som krävs för att appen ska kunna ta emot HTTP-begäranden för anpassat autentiseringstillägg.
1003022	CustomExtensionMsGraphServicePrincipalDisabledOrNotFound	MS Graph-tjänstens huvudnamn är inaktiverat eller hittades inte i den här klientorganisationen.
1003023	CustomExtensionBlocked	Den slutpunkt som används för det anpassade tillägget blockeras av tjänsten.
1003024	CustomExtensionResponseSizeExceededed	Svarsstorleken för anpassade tillägg överskred den maximala gränsen.
1003025	CustomExtensionResponseClaimsSizeExceededed	Den totala storleken på anspråk i det anpassade tilläggssvaret överskred den maximala gränsen.
1003026	CustomExtensionNullOrEmptyClaimKeyNotSupported	API:et för anpassat tillägg svarade med anspråk som innehåller null- eller tom nyckel"
1003027	CustomExtension Anslut ionError	Det gick inte att ansluta till API:et för anpassat tillägg.

Anropa rest-API:et direkt

Rest-API:et skyddas av en Microsoft Entra-åtkomsttoken. Du kan testa ditt API genom att;

• Hämta en åtkomsttoken med en programregistrering som är associerad med de anpassade autentiseringstilläggen
• Testa ditt API lokalt med hjälp av ett API-testverktyg.

API-testverktyg

1. För lokal utveckling och testning öppnar du local.settings.json och ersätter koden med följande JSON:

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

   Kommentar

   Om du använde NuGet-paketet Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents måste du ange "AuthenticationEvents__BypassTokenValidation" : true för lokala teständamål.

2. Använd det API-testverktyg du föredrar, skapa en ny HTTP-begäran och ange HTTP-metoden till POST.

3. Använd följande JSON-brödtext som imiterar den begäran som Microsoft Entra-ID skickar till rest-API:et.

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

   Dricks

   Om du använder en åtkomsttoken som hämtats från Microsoft Entra-ID väljer du Auktorisering och väljer sedan Ägartoken och klistrar sedan in den åtkomsttoken som du fick från Microsoft Entra-ID.

4. Välj Skicka och du bör få ett JSON-svar som liknar följande:

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

Hämta en åtkomsttoken

När du har hämtat en åtkomsttoken skickar du http-huvudet Authorization . Följ dessa steg för att hämta en åtkomsttoken:

1. Logga in på administrationscentret för Microsoft Entra som minst molnprogramadministratör.

2. Bläddra till Programregistreringar för identitetsprogram>>.

3. Välj api-appregistreringen för Azure Functions-autentiseringshändelser, som tidigare konfigurerats i konfigurera en anpassad anspråksprovider för en tokenutfärdarhändelse.

4. Kopiera program-ID:t.

5. Om du inte har skapat en apphemlighet följer du dessa steg:

   1. Välj Certifikat och hemligheter>Klienthemligheter>Ny klienthemlighet.
   2. Lägg till en beskrivning för din klienthemlighet.
   3. Välj en förfallotidpunkt för hemligheten eller ange en anpassad livslängd.
   4. Markera Lägga till.
   5. Registrera hemlighetens värde för användning i klientprogramkoden. Hemlighetens värde visas aldrig igen när du har lämnat den här sidan.

6. På menyn väljer du Exponera ett API och kopierar värdet för program-ID-URI:n. Exempel: api://contoso.azurewebsites.net/00001111-aaaa-2222-bbbb-3333cccc4444

7. Öppna önskat API-testverktyg och skapa en ny HTTP-fråga.

8. Ändra HTTP-metoden till POST.

9. Ange följande URL. Ersätt med ditt klientorganisations-ID {tenantID} .

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

10. Under brödtexten väljer du formulärdata och lägger till följande nycklar:

    Tangent	Värde
    grant_type	client_credentials
    client_id	Klient-ID för ditt program.
    client_secret	Programmets klienthemlighet .
    scope	Program-ID-URI : n för ditt program och lägg sedan till .default. Till exempel: api://contoso.azurewebsites.net/00001111-aaaa-2222-bbbb-3333cccc4444/.default

11. Kör HTTP-frågan och kopiera den access_token till webbappen https://jwt.ms .

12. iss Jämför med det utfärdarnamn som du konfigurerade i ditt API.

13. aud Jämför med det klient-ID som du konfigurerade i ditt API.

Vanliga prestandaförbättringar

Ett av de vanligaste problemen är att api:et för din anpassade anspråksprovider inte svarar inom tidsgränsen på två sekunder. Om rest-API:et inte svarar vid efterföljande återförsök misslyckas autentiseringen. Följ nedanstående förslag för att förbättra prestandan för rest-API:et:

1. Om ditt API får åtkomst till underordnade API:er cachelagrade du den åtkomsttoken som används för att anropa dessa API:er, så en ny token behöver inte hämtas vid varje körning.
2. Prestandaproblem är ofta relaterade till underordnade tjänster. Lägg till loggning, som registrerar processtiden för anrop till underordnade tjänster.
3. Om du använder en molnleverantör som värd för ditt API använder du en värdplan som alltid håller API:et "varmt". För Azure Functions kan det vara antingen Premium-planen eller Dedikerad plan.
4. Kör automatiserade integreringstester för dina autentiseringar. Du kan också använda API-testverktyg för att testa dina API-prestanda.

Se även

• Skapa ett REST API med en starthändelse för tokenutfärding
• Konfigurera en SAML-app för att ta emot token med anspråk från ett externt arkiv
• Referensartikel för anpassad anspråksprovider.