Felsöka ditt anpassade autentiseringstillägg

Artikel
03/07/2025

Genom autentiseringshändelser och anpassade anspråkstjänstleverantörer kan du anpassa Microsoft Entra-autentiseringsupplevelsen genom att integrera med externa system. Du kan till exempel skapa ett API för en anpassad anspråksprovider och konfigurera en OpenID Connect-app eller en SAML-app för att ta emot tokens med anspråk från en extern lagring.

Felfunktion

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

För OpenId Connect-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 claims provider 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.

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:

Logga in på administrationscentret för Microsoft Entra som minst molnprogramadministratör.
Bläddra till Identity>Applications>Enterprise applications.
Välj Inloggningsloggar och välj sedan den senaste inloggningsloggen.
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	HändelsehanterareOvväntatFel	Ett oväntat fel uppstod vid bearbetning av en händelsehanterare.
1003001	Oväntat fel i anpassad tillägg	Ett oväntat fel uppstod när ett API för anpassat tillägg anropades.
1003002	Ogiltig HTTP-status för anpassad utökning	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	Ogiltigt svarsinnehåll för anpassad förlängning	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	AnpassadUtökningTidsgränsen	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	OgiltigResponsinnehållstypFörAnpassadUtökning	Det anpassade tilläggets svarsinnehållstyp är inte "application/json".
1003007	CustomExtensionNullClaimsResponse	Det anpassade tilläggs-API:et svarade med en tom kravsuppsättning.
1003008	CustomExtensionInvalidResponseApiSchemaVersion	API:t för specialtillägg svarade inte med samma APISchemaVersion som det var avsett för.
1003009	CustomExtensionEmptyResponse	Api-svarstexten för det anpassade tillägget var null när det inte förväntades.
1003010	Ogiltigt antal åtgärder i anpassad förlängning	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	OgiltigÅtgärdstypFörAnpassadTillägg	Det anpassade tillägget returnerade en ogiltig åtgärdstyp som definierats för den anpassade tilläggstypen.
1003014	Felaktigt format på resurs-ID i anpassad tilläggsinställning	Egenskapen identifierUris i manifestet för programregistreringen för det anpassade tillägget ska vara i formatet "api://{fullständigt domännamn}/{appid}.
1003015	AnpassadUtökadDomänNamnMatcharInte	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 anpassade tilläggets tjänstehuvudnamn kunde inte hittas i klientorganisationen.
1003018	Kundtjänst för anpassad tillägg inaktiverad	Tjänstekontot för den anpassade extensionresursen är inaktiverat i den här klientorganisationen.
1003019	AnpassadUtökningResursTjänsthuvudInaktiverad	Huvudnamnet för tjänstens anpassade tillägg är inaktiverat i den här klientorganisationen.
1003020	Felaktigt format på måladressen för CustomExtension	Mål-URL:en är i ett felaktigt format. Det måste vara en giltig URL som börjar med https.
1003021	AnpassadFörlängningBehörighetEjBeviljadTillServicePrincipal	Tjänstens huvudserver 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 motta HTTP-begäranden för anpassade autentiseringstillägg.
1003022	CustomExtensionMsGraphServicePrincipalInaktiveradEllerInteHittad	MS Graph-tjänsthuvudprincipen är inaktiverad eller hittades inte i denna klient.
1003023	AnpassadFörlängningBlockerad	Den slutpunkt som används för det anpassade tillägget blockeras av tjänsten.
1003024	CustomExtensionResponseSizeÖverskriden	Svarsstorleken för anpassade tillägg överskred den maximala gränsen.
1003025	CustomExtensionResponseClaimsStorlekÖverskriden	Den totala storleken på anspråk i det anpassade tilläggssvaret överskred den maximala gränsen.
1003026	AnpassadUtökningNullEllerTomClaimNyckelInteStöds	API:et för anpassat tillägg svarade med påståenden som innehåller nyckel som är null eller tom.
1003027	CustomExtensionConnectionError	Det gick inte att ansluta till API:et för anpassat tillägg.

Anropa din REST-API direkt

Din REST-API 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
Hämta en åtkomsttoken

För lokal utveckling och testning, öppna local.settings.json och ersätt 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.
Använd det API-testverktyg du föredrar, skapa en ny HTTP-begäran och ange HTTP-metoden till POST.

Använd följande JSON-brödtext som imiterar den begäran Microsoft Entra ID skickar till din REST-API.

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

Tips

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.

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

        ]
    }
}

När du har hämtat en åtkomsttoken, lägger du till den i HTTP-huvudet Authorization. Följ dessa steg för att hämta en åtkomsttoken:

Logga in på administrationscentret för Microsoft Entra som minst molnprogramadministratör.
Bläddra till Identitet>Program>Programregistreringar.
Välj appregistreringen för Azure Functions authentication events API, som tidigare konfigurerats i att konfigurera en anpassad kravleverantör för en tokenutfärdarhändelse.
Kopiera applikations-ID.
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.
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
Öppna önskat API-testverktyg och skapa en ny HTTP-fråga.
Ändra HTTP-metoden till POST.
Ange följande URL. Ersätt {tenantID} med ditt klientorganisations-ID.
```
https://login.microsoftonline.com/{tenantID}/oauth2/v2.0/token
```

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

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

Kör HTTP-frågan och kopiera access_token till https://jwt.ms-webbappen.
iss Jämför med det utfärdarnamn som du konfigurerade i ditt API.
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 upprepade försök misslyckas autentiseringen. Följ nedanstående förslag för att förbättra prestandan för rest-API:et:

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.
Prestandaproblem är ofta relaterade till underordnade tjänster. Lägg till loggning, som registrerar processtiden för anrop till underordnade tjänster.
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.
Kör automatiserade integreringstester för dina autentiseringar. Du kan också använda API-testverktyg för att testa dina API-prestanda.

Dela via

Felsöka ditt anpassade autentiseringstillägg

Felfunktion

Loggning

Referens för felkoder

Anropa din REST-API direkt

Vanliga prestandaförbättringar

Se även

Feedback

Ytterligare resurser