Rozwiązywanie problemów z interfejsem API dostawcy oświadczeń niestandardowych
Zdarzenia uwierzytelniania i niestandardowe dostawcy oświadczeń umożliwiają dostosowanie środowiska uwierzytelniania entra firmy Microsoft przez integrację z systemami zewnętrznymi. Można na przykład utworzyć niestandardowy interfejs API dostawcy oświadczeń i skonfigurować aplikację OpenID Connect lub aplikację SAML do odbierania tokenów z oświadczeniami z magazynu zewnętrznego.
Zachowanie błędu
Gdy wywołanie interfejsu API zakończy się niepowodzeniem, zachowanie błędu jest następujące:
- W przypadku aplikacji OpenId Connect — identyfikator Entra firmy Microsoft przekierowuje użytkownika z powrotem do aplikacji klienckiej z powodu błędu. Token nie jest wybity.
- W przypadku aplikacji SAML — identyfikator Entra firmy Microsoft pokazuje użytkownikowi ekran błędu w środowisku uwierzytelniania. Użytkownik nie jest przekierowywany z powrotem do aplikacji klienckiej.
Kod błędu wysłany z powrotem do aplikacji lub użytkownik jest ogólny. Aby rozwiązać problemy, sprawdź dzienniki logowania pod kątem kodów błędów.
Rejestrowanie
Aby rozwiązać problemy z punktem końcowym interfejsu API REST dostawcy oświadczeń niestandardowych, interfejs API REST musi obsługiwać rejestrowanie. Usługa Azure Functions i inne platformy deweloperskie interfejsu API zapewniają szczegółowe rozwiązania do rejestrowania. Skorzystaj z tych rozwiązań, aby uzyskać szczegółowe informacje na temat zachowania interfejsów API i rozwiązywania problemów z logiką interfejsu API.
Dzienniki logowania w usłudze Microsoft Entra
Napiwek
Kroki opisane w tym artykule mogą się nieznacznie różnić w zależności od portalu, od którego zaczynasz.
Oprócz dzienników interfejsu API REST i hostowania rozwiązań diagnostycznych środowiska można również użyć dzienników logowania firmy Microsoft Entra. Korzystając z dzienników logowania firmy Microsoft Entra, można znaleźć błędy, które mogą mieć wpływ na logowania użytkowników. Dzienniki logowania w usłudze Microsoft Entra zawierają informacje o stanie HTTP, kodzie błędu, czasie trwania wykonywania i liczbie ponownych prób, które wystąpiły, interfejs API został wywołany przez identyfikator Firmy Microsoft Entra.
Dzienniki logowania w usłudze Microsoft Entra również integrują się z usługą Azure Monitor. Możesz skonfigurować alerty i monitorowanie, wizualizować dane i integrować je z narzędziami do zarządzania informacjami i zdarzeniami zabezpieczeń (SIEM). Możesz na przykład skonfigurować powiadomienia, jeśli liczba błędów przekroczy wybrany próg.
Aby uzyskać dostęp do dzienników logowania firmy Microsoft Entra:
Zaloguj się do centrum administracyjnego firmy Microsoft Entra co najmniej jako administrator aplikacji w chmurze.
Przejdź do aplikacji dla przedsiębiorstw usługi Identity>Applications>.
Wybierz pozycję Dzienniki logowania, a następnie wybierz najnowszy dziennik logowania.
Aby uzyskać więcej informacji, wybierz kartę Zdarzenia uwierzytelniania. Zostaną wyświetlone informacje związane z wywołaniem interfejsu API REST rozszerzenia niestandardowego uwierzytelniania, w tym wszelkie kody błędów.
Odwołanie do kodów błędów
Skorzystaj z poniższej tabeli, aby zdiagnozować kod błędu.
| Kod błędu | Błąd nazwy | opis |
|---|---|---|
| 1003000 | EventHandlerUnexpectedError | Wystąpił nieoczekiwany błąd podczas przetwarzania programu obsługi zdarzeń. |
| 1003001 | CustomExtenstionUnexpectedError | Wystąpił nieoczekiwany błąd podczas wywoływania niestandardowego interfejsu API rozszerzenia. |
| 1003002 | CustomExtensionInvalidHTTPStatus | Interfejs API rozszerzenia niestandardowego zwrócił nieprawidłowy kod stanu HTTP. Sprawdź, czy interfejs API zwraca akceptowany kod stanu zdefiniowany dla tego niestandardowego typu rozszerzenia. |
| 1003003 | CustomExtensionInvalidResponseBody | Wystąpił problem podczas analizowania treści odpowiedzi rozszerzenia niestandardowego. Sprawdź, czy treść odpowiedzi interfejsu API znajduje się w akceptowalnym schemacie dla tego niestandardowego typu rozszerzenia. |
| 1003004 | CustomExtensionThrottlingError | Istnieje zbyt wiele niestandardowych żądań rozszerzenia. Ten wyjątek jest zgłaszany w przypadku niestandardowych wywołań interfejsu API rozszerzeń w przypadku osiągnięcia limitów ograniczania przepustowości. |
| 1003005 | CustomExtensionTimedOut | Rozszerzenie niestandardowe nie odpowiedziało w ramach dozwolonego limitu czasu. Sprawdź, czy interfejs API odpowiada w ramach skonfigurowanego limitu czasu dla rozszerzenia niestandardowego. Może również wskazywać, że token dostępu jest nieprawidłowy. Wykonaj kroki, aby bezpośrednio wywołać interfejs API REST. |
| 1003006 | CustomExtensionInvalidResponseContentType | Typ zawartości odpowiedzi rozszerzenia niestandardowego nie jest "application/json". |
| 1003007 | CustomExtensionNullClaimsResponse | Interfejs API rozszerzenia niestandardowego odpowiedział przy użyciu torby oświadczeń o wartości null. |
| 1003008 | CustomExtensionInvalidResponseApiSchemaVersion | Interfejs API rozszerzenia niestandardowego nie odpowiedział przy użyciu tego samego interfejsu APISchemaVersion, dla którego został wywołany. |
| 1003009 | CustomExtensionEmptyResponse | Treść odpowiedzi interfejsu API rozszerzenia niestandardowego miała wartość null, gdy nie było to oczekiwane. |
| 1003010 | CustomExtensionInvalidNumberOfActions | Odpowiedź interfejsu API rozszerzenia niestandardowego zawierała inną liczbę akcji niż te obsługiwane dla tego niestandardowego typu rozszerzenia. |
| 1003011 | CustomExtensionNotFound | Nie można odnaleźć rozszerzenia niestandardowego skojarzonego z odbiornikiem zdarzeń. |
| 1003012 | CustomExtensionInvalidActionType | Rozszerzenie niestandardowe zwróciło nieprawidłowy typ akcji zdefiniowany dla tego niestandardowego typu rozszerzenia. |
| 1003014 | CustomExtensionIncorrectResourceIdFormat | Właściwość identifierUris w manifeście rejestracji aplikacji dla rozszerzenia niestandardowego powinna mieć format "api://{w pełni kwalifikowana nazwa domeny}/{appid}. |
| 1003015 | CustomExtensionDomainNameDoesNotMatch | TargetUrl i resourceId rozszerzenia niestandardowego powinny mieć taką samą w pełni kwalifikowaną nazwę domeny. |
| 1003016 | CustomExtensionResourceServicePrincipalNotFound | Identyfikator appId niestandardowego identyfikatora resourceId rozszerzenia powinien odpowiadać rzeczywistej jednostce usługi w dzierżawie. |
| 1003017 | CustomExtensionClientServicePrincipalNotFound | Nie można odnaleźć jednostki usługi zasobów rozszerzenia niestandardowego w dzierżawie. |
| 1003018 | CustomExtensionClientServiceDisabled | Jednostka usługi zasobów rozszerzenia niestandardowego jest wyłączona w tej dzierżawie. |
| 1003019 | CustomExtensionResourceServicePrincipalDisabled | Jednostka usługi zasobów rozszerzenia niestandardowego jest wyłączona w tej dzierżawie. |
| 1003020 | CustomExtensionIncorrectTargetUrlFormat | Docelowy adres URL jest w niewłaściwym formacie. Musi to być prawidłowy adres URL rozpoczynający się od https. |
| 1003021 | CustomExtensionPermissionNotGrantedToServicePrincipal | Jednostka usługi nie ma zgody administratora dla roli aplikacji CustomAuthenticationExtensions.Receive.Payload (nazywanej również uprawnieniem aplikacji), która jest wymagana, aby aplikacja odbierała niestandardowe żądania HTTP rozszerzenia uwierzytelniania. |
| 1003022 | CustomExtensionMsGraphServicePrincipalDisabledOrNotFound | Jednostka usługi MS Graph jest wyłączona lub nie można jej odnaleźć w tej dzierżawie. |
| 1003023 | CustomExtensionBlocked | Punkt końcowy używany dla rozszerzenia niestandardowego jest blokowany przez usługę. |
| 1003024 | CustomExtensionResponseSizeExceeded | Rozmiar odpowiedzi rozszerzenia niestandardowego przekroczył maksymalny limit. |
| 1003025 | CustomExtensionResponseClaimsSizeExceeded | Całkowity rozmiar oświadczeń w odpowiedzi rozszerzenia niestandardowego przekroczył maksymalny limit. |
| 1003026 | CustomExtensionNullOrEmptyClaimKeyNotSupported | Interfejs API rozszerzenia niestandardowego odpowiedział oświadczeniami zawierającymi wartość null lub pusty klucz" |
| 1003027 | CustomExtensionConnectionError | Błąd podczas nawiązywania połączenia z niestandardowym interfejsem API rozszerzenia. |
Bezpośrednie wywoływanie interfejsu API REST
Interfejs API REST jest chroniony przez token dostępu firmy Microsoft Entra. Interfejs API można przetestować według;
- Uzyskiwanie tokenu dostępu przy użyciu rejestracji aplikacji skojarzonej z niestandardowymi rozszerzeniami uwierzytelniania
- Testowanie interfejsu API lokalnie przy użyciu narzędzia do testowania interfejsu API.
W celach programowania i testowania lokalnego otwórz local.settings.json i zastąp kod następującym kodem JSON:
{ "IsEncrypted": false, "Values": { "AzureWebJobsStorage": "", "AzureWebJobsSecretStorageType": "files", "FUNCTIONS_WORKER_RUNTIME": "dotnet", "AuthenticationEvents__BypassTokenValidation" : false } }Uwaga
Jeśli użyto pakietu NuGet Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents , pamiętaj, aby ustawić
"AuthenticationEvents__BypassTokenValidation" : truego na potrzeby testowania lokalnego.Za pomocą preferowanego narzędzia do testowania interfejsu API utwórz nowe żądanie HTTP i ustaw metodę HTTP na
POST.Użyj następującej treści JSON, która naśladuje żądanie wysyłane przez identyfikator Entra firmy Microsoft do interfejsu API REST.
{ "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" } } } }Napiwek
Jeśli używasz tokenu dostępu uzyskanego z identyfikatora Entra firmy Microsoft, wybierz pozycję Autoryzacja , a następnie wybierz pozycję Token elementu nośnego, a następnie wklej token dostępu otrzymany z identyfikatora Entra firmy Microsoft.
Wybierz pozycję Wyślij i powinna zostać odebrana odpowiedź JSON podobna do następującej:
{ "data": { "@odata.type": "microsoft.graph.onTokenIssuanceStartResponseData", "actions": [ { "@odata.type": "microsoft.graph.tokenIssuanceStart.provideClaimsForToken", "claims": { "customClaim1": "customClaimValue1", "customClaim2": [ "customClaimString1", "customClaimString2" ] } } ] } }
Typowe ulepszenia wydajności
Jednym z najczęstszych problemów jest to, że interfejs API dostawcy oświadczeń niestandardowych nie odpowiada w ciągu dwóch sekund limitu czasu. Jeśli interfejs API REST nie odpowie w kolejnych ponownych próbach, uwierzytelnianie zakończy się niepowodzeniem. Aby zwiększyć wydajność interfejsu API REST, postępuj zgodnie z poniższymi sugestiami:
- Jeśli interfejs API uzyskuje dostęp do jakichkolwiek podrzędnych interfejsów API, buforuj token dostępu używany do wywoływania tych interfejsów API, więc nowy token nie musi być uzyskiwany w każdym wykonaniu.
- Problemy z wydajnością są często związane z usługami podrzędnymi. Dodaj rejestrowanie, które rejestruje czas procesu w celu wywołania dowolnych usług podrzędnych.
- Jeśli używasz dostawcy usług w chmurze do hostowania interfejsu API, użyj planu hostingu, który utrzymuje interfejs API zawsze "ciepły". W przypadku usługi Azure Functions może to być plan Premium lub plan dedykowany.
- Uruchom testy automatycznej integracji na potrzeby uwierzytelniania. Możesz również użyć narzędzi do testowania interfejsu API, aby przetestować tylko wydajność interfejsu API.