Rozwiązywanie problemów z własnym rozszerzeniem uwierzytelniania
Zdarzenia uwierzytelniania i niestandardowy dostawca oświadczeń umożliwiają dostosowanie środowiska uwierzytelniania Microsoft Entra 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, który jest wysyłany z powrotem do aplikacji lub użytkownika, jest ogólny. Aby rozwiązać problemy, sprawdź dzienniki logowania pod kątem kodów błędów.
Logowanie
Aby rozwiązać problemy z punktem końcowym REST API niestandardowego dostawcy oświadczeń, interfejs API REST musi obsługiwać rejestrowanie. Usługa Azure Functions i inne platformy do tworzenia interfejsu API oferują 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
Oprócz dzienników interfejsu API REST i rozwiązań diagnostycznych dla środowiska hostingu można również użyć dzienników logowania firmy Microsoft Entra. Korzystając z dzienników logowania Microsoft Entra, można znaleźć błędy, które mogą mieć wpływ na logowania użytkowników. Dzienniki te zawierają informacje o stanie HTTP, kodzie błędu, czasie trwania wykonywania oraz liczbie ponownych prób występujących podczas wywołań API przez Microsoft Entra ID.
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 Identity>Aplikacje>Aplikacje dla przedsiębiorstw.
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 niestandardowego rozszerzenia uwierzytelniania, w tym wszelkie kody błędów.
Kody błędów – odniesienie
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 | NieoczekiwanyBłądDostosowanegoRozszerzenia | Wystąpił nieoczekiwany błąd podczas wywoływania niestandardowego interfejsu API rozszerzenia. |
| 1003002 | CustomExtensionInvalidHTTPStatus | Niestandardowy interfejs API rozszerzenia zwrócił nieprawidłowy kod statusu HTTP. Sprawdź, czy interfejs API zwraca akceptowany kod stanu zdefiniowany dla tego niestandardowego typu rozszerzenia. |
| 1003003 | NieprawidłowaTreśćOdpowiedziNiestandardowegoRozszerzenia | 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 dla niestandardowych wywołań interfejsu API rozszerzeń, gdy osiągnięte zostaną limity ograniczania przepustowości. |
| 1003005 | NiestandardoweRozszerzeniePrzekroczyłoLimitCzasu | Rozszerzenie niestandardowe nie odpowiedziało przed upływem 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. Postępuj zgodnie z krokami, aby bezpośrednio wywołać interfejs API REST. |
| 1003006 | NiestandardoweRozszerzenieNieprawidłowyTypTreściOdpowiedzi | Typ zawartości odpowiedzi rozszerzenia niestandardowego nie jest "application/json". |
| 1003007 | CustomExtensionNullClaimsResponse | Interfejs API rozszerzenia niestandardowego odpowiedział pustym zestawem roszczeń. |
| 1003008 | NieprawidłowaWersjaSchemyApiOdpowiedziCustomExtension | Interfejs API rozszerzenia niestandardowego nie odpowiedział z taką samą wersją apiSchema, z którą został wywołany. |
| 1003009 | CustomExtensionEmptyResponse | Treść odpowiedzi interfejsu API rozszerzenia niestandardowego miała wartość null, gdy nie było to oczekiwane. |
| 1003010 | Nieprawidłowa liczba akcji rozszerzenia niestandardowego | Odpowiedź interfejsu API rozszerzenia niestandardowego zawierała inną liczbę akcji niż te obsługiwane dla tego niestandardowego typu rozszerzenia. |
| 1003011 | Nie znaleziono niestandardowego rozszerzenia | Nie można odnaleźć rozszerzenia niestandardowego skojarzonego z nasłuchiwaczem zdarzeń. |
| 1003012 | NieprawidłowyTypAkcjiRozszerzeniaNiestandardowego | Rozszerzenie niestandardowe zwróciło nieprawidłowy typ akcji zdefiniowany dla tego niestandardowego typu rozszerzenia. |
| 1003014 | NieprawidłowyFormatIdentyfikatoraZasobuDlaNiestandardowegoRozszerzenia | Właściwość identifierUris w manifeście rejestracji aplikacji dla rozszerzenia niestandardowego powinna mieć format "api://{w pełni kwalifikowana nazwa domeny}/{appid}. |
| 1003015 | NazwaDomenyNiestandardowegoRozszerzeniaNiePasuje | TargetUrl i resourceId rozszerzenia niestandardowego powinny mieć taką samą w pełni kwalifikowaną nazwę domeny. |
| 1003016 | Główny serwis zasobu CustomExtensionResource nie został znaleziony | Identyfikator appId niestandardowego rozszerzenia resourceId powinien odpowiadać rzeczywistej głównej aplikacji usługi w dzierżawie. |
| 1003017 | CustomExtensionClientServicePrincipalNotFound | Nie można odnaleźć jednostki usługi zasobów rozszerzenia niestandardowego w dzierżawie. |
| 1003018 | UsługaKlientaRozszerzeniaNiestandardowegoWyłączona | Główna usługa zasobu niestandardowego rozszerzenia jest wyłączona dla tego dzierżawcy. |
| 1003019 | Wyłączona Usługa Principal CustomExtensionResource | Główna jednostka usługi zasobów rozszerzenia niestandardowego jest wyłączona w tej dzierżawie. |
| 1003020 | NiestandardoweRozszerzenieNiepoprawnyFormatAdresuUrlDocelowego | Docelowy adres URL jest w niewłaściwym formacie. Musi to być prawidłowy adres URL rozpoczynający się od https. |
| 1003021 | Nie przyznano usługi głównej uprawnień do niestandardowego rozszerzenia | Główna usługa aplikacji nie ma zgody administratora dla roli aplikacji Microsoft Graph CustomAuthenticationExtensions.Receive.Payload (nazywanej również uprawnieniem aplikacji), która jest wymagana, aby aplikacja mogła odbierać żądania HTTP dotyczące niestandardowego rozszerzenia uwierzytelniania. |
| 1003022 | Brak lub wyłączony niestandardowy rozszerzenie MS Graph usługi głównej | Jednostka usługi MS Graph jest wyłączona lub nie można jej odnaleźć w tym dzierżawcy. |
| 1003023 | WłasneRozszerzenieZablokowane | Punkt końcowy używany dla rozszerzenia niestandardowego jest blokowany przez usługę. |
| 1003024 | Przekroczono rozmiar odpowiedzi niestandardowego rozszerzenia | Rozmiar odpowiedzi rozszerzenia niestandardowego przekroczył maksymalny limit. |
| 1003025 | Rozmiar żądań odpowiedzi niestandardowego rozszerzenia przekroczony | Całkowity rozmiar żądań 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. Możesz przetestować swój interfejs API za pomocą
- Uzyskiwanie tokenu dostępu przy użyciu rejestracji aplikacji skojarzonej z niestandardowymi rozszerzeniami uwierzytelniania
- Przetestuj swój interfejs API lokalnie za pomocą 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" : truena 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 limitu czasu wynoszącego dwie sekundy. 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, aby nowy token nie musiał być uzyskiwany przy każdym uruchomieniu.
- Problemy z wydajnością są często związane z usługami podrzędnymi. Dodaj rejestrowanie, które zapisuje czas trwania procesu wywołania dowolnych usług zewnętrznych.
- 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.