Rozwiązywanie problemów z uwierzytelnianiem tożsamości Azure

W tym artykule opisano techniki badania błędów, typowe błędy typów poświadczeń w bibliotece klienta Java tożsamości platformy Azure oraz kroki ograniczania ryzyka w celu rozwiązania tych błędów. Ponieważ wiele typów poświadczeń jest dostępnych w Azure SDK dla Java, ten przewodnik rozwiązywania problemów jest podzielony na sekcje na podstawie scenariusza użycia. Dostępne są następujące sekcje:

W pozostałej części tego artykułu omówiono ogólne techniki rozwiązywania problemów i wskazówki dotyczące wszystkich typów poświadczeń.

Obsługa wyjątków tożsamości platformy Azure

Jak wspomniano w artykule Obsługa wyjątków w Azure SDK dla Java sekcji Omówienie rozwiązywania problemów, Azure SDK dla Java może zgłosić kompleksowy zestaw wyjątków i kodów błędów. W przypadku Azure Identity kilka kluczowych typów wyjątków jest istotnych dla zrozumienia.

ClientAuthenticationException

Każda metoda klienta usługi, która wysyła żądanie do usługi, może zgłaszać wyjątki od błędów uwierzytelniania. Te wyjątki mogą wystąpić, ponieważ token jest żądany przy użyciu poświadczeń przy pierwszym wywołaniu usługi oraz przy każdym kolejnym żądaniu do usługi wymagającym odświeżenia tokenu.

Aby odróżnić te błędy od błędów w kliencie usługi, klasy Azure Identity zgłaszają ClientAuthenticationException z szczegółowymi informacjami opisującymi źródło błędu w komunikacie o wyjątku i ewentualnie zawierającymi komunikat o błędzie. W zależności od aplikacji te błędy mogą być możliwe do odzyskania. Poniższy kod przedstawia przykład przechwytywania ClientAuthenticationException:

// Create a secret client using the DefaultAzureCredential
SecretClient client = new SecretClientBuilder()
    .vaultUrl("https://myvault.vault.azure.net/")
    .credential(new DefaultAzureCredentialBuilder().build())
    .buildClient();

try {
    KeyVaultSecret secret = client.getSecret("secret1");
} catch (ClientAuthenticationException e) {
    //Handle Exception
    e.printStackTrace();
}

CredentialUnavailableException (Brak dostępnych danych uwierzytelniających)

CredentialUnavailableException jest szczególnym typem wyjątku pochodzącym z klasy ClientAuthenticationException. Użyj tego typu wyjątku, aby wskazać, że poświadczenie nie może zostać uwierzytelnione w bieżącym środowisku z powodu braku wymaganej konfiguracji lub konfiguracji wstępnej. Ten wyjątek sygnalizuje również typom poświadczeń w łańcuchu, takim jak DefaultAzureCredential i ChainedTokenCredential, aby poświadczenie w łańcuchu nadal wypróbowywało inne typy poświadczeń w dalszej części łańcucha.

Problemy z uprawnieniami

Wywołania klientów usługi, których wynikiem jest HttpResponseExceptionStatusCode wartość 401 lub 403, często wskazują, że obiekt wywołujący nie ma wystarczających uprawnień dla określonego interfejsu API. Zapoznaj się z dokumentacją usługi, aby określić, które role są potrzebne dla określonego żądania. Upewnij się, że uwierzytelniony użytkownik lub jednostka usługi ma przyznane odpowiednie role w zasobie.

Znajdowanie odpowiednich informacji w komunikatach o wyjątkach

Wyjątek ClientAuthenticationException jest zgłaszany, gdy podczas uwierzytelniania poświadczenia wystąpią nieoczekiwane błędy. Błędy te mogą obejmować błędy zwracane w odpowiedzi na żądania kierowane do usługi tokenów zabezpieczających (STS) platformy Microsoft Entra i często zawierają informacje pomocne w diagnostyce. Rozważmy następujący ClientAuthenticationException komunikat:

ClientSecretCredential authentication failed: A configuration issue is preventing authentication - check the error message from the server for details. You can modify the configuration in the application registration portal. See https://aka.ms/msal-net-invalid-client for details.

Original exception:
AADSTS7000215: Invalid client secret provided. Ensure the secret being sent in the request is the client secret value, not the client secret ID, for a secret added to app 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'.
Trace ID: XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
Correlation ID: XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
Timestamp: 2022-01-01 00:00:00Z

Ten komunikat o błędzie zawiera następujące informacje:

  • Typ poświadczeń zakończony niepowodzeniem: typ poświadczenia, którego nie można uwierzytelnić — w tym przypadku ClientSecretCredential. Te informacje są przydatne podczas diagnozowania problemów z typami poświadczeń łańcuchowych, takimi jak DefaultAzureCredential lub ChainedTokenCredential.

  • Kod błędu i komunikat usługi STS: kod błędu i komunikat zwrócony z usługi Microsoft Entra STS — w tym przypadku AADSTS7000215: Invalid client secret provided. te informacje zawierają wgląd w konkretną przyczynę niepowodzenia żądania. Na przykład w tym konkretnym przypadku podany klucz tajny klienta jest niepoprawny. Aby uzyskać więcej informacji na temat kodów błędów STS, zobacz sekcję kody błędów AADSTS w kodach błędów uwierzytelniania i autoryzacji Microsoft Entra.

  • Identyfikator korelacji i sygnatura czasowa: identyfikator korelacji i sygnatura czasowa wywołania używana do identyfikowania żądania w dziennikach po stronie serwera. Te informacje są przydatne dla inżynierów pomocy technicznej podczas diagnozowania nieoczekiwanych awarii usługi STS.

Włączanie i konfigurowanie rejestrowania

Azure SDK dla Java oferuje spójny scenariusz rejestrowania, który pomaga w rozwiązywaniu problemów z błędami aplikacji i pomaga przyspieszyć ich rozwiązywanie. Dzienniki przechwytują przepływ aplikacji przed dotarciem do stanu terminalu, aby ułatwić zlokalizowanie głównego problemu. Aby uzyskać wskazówki dotyczące rejestrowania, zobacz Konfigurowanie rejestrowania w Azure SDK dla Javy i Przegląd rozwiązywania problemów.

Podstawowa biblioteka MSAL, czyli MSAL4J, ma również szczegółowe rejestrowanie. To logowanie jest bardzo szczegółowe i obejmuje wszystkie dane osobowe, w tym tokeny. Rejestrowanie jest najbardziej użyteczne podczas pracy z wsparciem technicznym produktu. Od wersji 1.10.0 poświadczenia, które oferują to rejestrowanie, mają metodę o nazwie enableUnsafeSupportLogging().

Ostrożność

Żądania i odpowiedzi w bibliotece tożsamości platformy Azure zawierają informacje poufne. Podejmij środki ostrożności, aby chronić dzienniki podczas dostosowywania danych wyjściowych, aby uniknąć naruszenia zabezpieczeń konta.

Następne kroki

Jeśli wskazówki dotyczące rozwiązywania problemów w tym artykule nie pomogą rozwiązać problemów podczas korzystania z Azure SDK dla bibliotek klienckich Java, zgłoś problem w Azure SDK dla repozytorium Java GitHub.

  • Last updated on