Udostępnij za pośrednictwem

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

  • Artykuł

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ż w zestawie Azure SDK dla języka Java jest dostępnych wiele typów poświadczeń, podzieliliśmy przewodnik rozwiązywania problemów na sekcje oparte na scenariuszu 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 sekcji Obsługa wyjątków w sekcji Omówienie rozwiązywania problemów z zestawem Azure SDK dla języka Java, istnieje kompleksowy zestaw wyjątków i kodów błędów, które mogą zgłaszać zestaw Azure SDK dla języka Java. W przypadku tożsamości platformy Azure istnieje kilka kluczowych typów wyjątków, które są ważne do zrozumienia.

ClientAuthenticationException

Każda metoda klienta usługi, która wysyła żądanie do usługi, może zgłaszać wyjątki wynikające z błędów uwierzytelniania. Te wyjątki są możliwe, ponieważ token jest żądany z poświadczeń podczas pierwszego wywołania usługi i w przypadku wszelkich kolejnych żądań do usługi, które muszą odświeżyć token.

Aby odróżnić te błędy od błędów w kliencie usługi, klasy tożsamości platformy Azure zgłaszają ClientAuthenticationException szczegółowe informacje opisujące źródło błędu w komunikacie o wyjątku i prawdopodobnie komunikat o błędzie. W zależności od aplikacji te błędy mogą lub nie mogą być możliwe do odzyskania. Poniższy kod przedstawia przykład przechwytywania ClientAuthenticationExceptionelementu :

// 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

CredentialUnavailableException jest specjalnym typem wyjątku pochodzącym z ClientAuthenticationExceptionklasy . Ten typ wyjątku służy do wskazywania, że poświadczenie nie może uwierzytelniać się w bieżącym środowisku z powodu braku wymaganej konfiguracji lub konfiguracji. Ten wyjątek jest również używany jako sygnał do łańcuchowych typów poświadczeń, takich jak DefaultAzureCredential i ChainedTokenCredential, że poświadczenie łańcuchowe powinno nadal próbować innych typów poświadczeń w dalszej części łańcucha.

Problemy z uprawnieniami

Wywołania klientów usługi, w wyniku których HttpResponseExceptionStatusCode element 401 lub 403 często wskazuje, ż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 otrzymał odpowiednie role w zasobie.

Znajdowanie odpowiednich informacji w komunikatach o wyjątkach

ClientAuthenticationException jest zgłaszany, gdy wystąpią nieoczekiwane błędy podczas uwierzytelniania poświadczeń. Te błędy mogą obejmować błędy odebrane z żądań do usługi tokenu zabezpieczającego firmy Microsoft (STS) 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 usługi STS i komunikat: kod błędu i komunikat zwrócony z usługi Microsoft Entra STS — w tym przypadku AADSTS7000215: Invalid client secret provided. te informacje mogą dać wgląd w konkretny powód, dla którego żądanie nie powiodło się. Na przykład w tym konkretnym przypadku, ponieważ 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 usługi AADSTS w kodach błędów uwierzytelniania i autoryzacji firmy 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

Zestaw Azure SDK dla języka 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 utworzone 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 zestawie Azure SDK dla języka Java i Rozwiązywanie problemów z widokiem.

Podstawowa biblioteka MSAL, MSAL4J, ma również szczegółowe rejestrowanie. To rejestrowanie jest bardzo pełne i zawiera wszystkie dane osobowe, w tym tokeny. To rejestrowanie jest najbardziej przydatne podczas pracy z pomocą techniczną produktu. Od wersji 1.10.0 poświadczenia, które oferują to rejestrowanie, mają metodę o nazwie enableUnsafeSupportLogging().

Uwaga

Żądania i odpowiedzi w bibliotece tożsamości platformy Azure zawierają informacje poufne. Należy podjąć ś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 bibliotek klienckich zestawu Azure SDK dla języka Java, zalecamy zgłoszenie problemuw repozytorium GitHub zestawu Azure SDK dla języka Java.