Łańcuchy poświadczeń w bibliotece Azure Identity dla Java

Biblioteka Azure Identity udostępnia poświadczenia — klasy publiczne implementujące interfejs TokenCredential biblioteki Azure Core. Poświadczenie reprezentuje odrębny przepływ uwierzytelniania na potrzeby uzyskiwania tokenu dostępu z Microsoft Entra ID. Te poświadczenia można połączyć w łańcuch, aby utworzyć uporządkowaną sekwencję mechanizmów uwierzytelniania, które można stosować.

Jak działa poświadczenie łańcuchowe

Podczas działania łańcuch poświadczeń próbuje uwierzytelnić się przy użyciu pierwszego poświadczenia z sekwencji. Jeśli to poświadczenie nie może uzyskać tokenu dostępu, zostanie podjęta próba następnego poświadczenia w sekwencji itd., dopóki token dostępu nie zostanie pomyślnie uzyskany. Poniższy diagram sekwencji ilustruje to zachowanie:

Dlaczego warto używać łańcuchów poświadczeń

Poświadczenie łańcuchowe może oferować następujące korzyści:

• Świadomość środowiska: automatycznie wybiera najbardziej odpowiednie poświadczenia na podstawie środowiska, w którym działa aplikacja. Bez niego musisz napisać kod podobny do następującego:

  import com.azure.core.credential.TokenCredential;
  import com.azure.identity.AzureCliCredentialBuilder;
  import com.azure.identity.ManagedIdentityCredentialBuilder;
  
  // Code omitted for brevity
  
  TokenCredential credential = null;
  
  // Set up credential based on environment (Azure or local development)
  String environment = System.getenv("ENV");
  
  if (environment != null && environment.equals("production")) {
      credential = new ManagedIdentityCredentialBuilder()
          .clientId(userAssignedClientId)
          .build();
  } else {
      credential = new AzureCliCredentialBuilder()
          .build();
  }
  

• Bezproblemowe przejścia: Aplikacja może przejść z lokalnego programowania do środowiska przejściowego lub produkcyjnego bez zmiany kodu uwierzytelniania.

• Ulepszona odporność: obejmuje mechanizm rezerwowy, który przechodzi do następnego poświadczenia, gdy poprzednia próba uzyskania tokenu dostępu zakończy się niepowodzeniem.

Jak wybrać poświadczenie łańcuchowe

Istnieją dwa różne podejścia do tworzenia łańcuchów poświadczeń:

• Użyj wstępnie skonfigurowanego łańcucha: zacznij od zoptymalizowanego, wstępnie zbudowanego łańcucha, który uwzględnia najczęstsze scenariusze uwierzytelniania. W przypadku tego podejścia zobacz sekcję Omówienie DefaultAzureCredential.
• "Utwórz" łańcuch: zacznij od pustego łańcucha i uwzględnij tylko potrzebne elementy. Aby zapoznać się z tym podejściem, zobacz sekcję Omówienie ChainedTokenCredential.

Przegląd DefaultAzureCredential

DefaultAzureCredential jest opiniotwórczym, wstępnie skonfigurowanym łańcuchem poświadczeń. Jest ona przeznaczona do obsługi wielu środowisk wraz z najczęściej używanymi przepływami uwierzytelniania i narzędziami deweloperskich. W postaci graficznej podstawowy łańcuch wygląda następująco:

Kolejność, w której DefaultAzureCredential próbuje użyć danych uwierzytelniających, jest następująca.

Zamówienie	Kwalifikacje	opis
1	Środowisko	Odczytuje kolekcję zmiennych środowiskowych aby określić, czy dla aplikacji skonfigurowano głównego podmiotu usługi aplikacji (użytkownika aplikacji). Jeśli tak, DefaultAzureCredential używa tych wartości do uwierzytelniania aplikacji na platformie Azure. Tej metody można używać podczas tworzenia lokalnie, ale jest najczęściej używana w środowiskach serwera.
2	Tożsamość zadania	Jeśli aplikacja zostanie wdrożona na hoście Azure z włączoną tożsamością obciążenia, uwierzytelnij to konto.
3	Tożsamość zarządzana	Jeśli aplikacja zostanie wdrożona na hoście Azure z włączoną tożsamością zarządzaną, uwierzytelnij aplikację w Azure przy użyciu tej tożsamości zarządzanej.
4	IntelliJ	Jeśli deweloper jest uwierzytelniony za pośrednictwem Azure Toolkit for IntelliJ, należy uwierzytelnić to konto.
5	Visual Studio Code	Jeśli deweloper uwierzytelnił się za pośrednictwem rozszerzenia Visual Studio Code Azure Resources i zainstalowano pakiet azure-identity-broker, należy uwierzytelnić to konto.
6	Azure CLI	Jeśli deweloper uwierzytelnił się w Azure przy użyciu polecenia az login Azure CLI, uwierzytelnij aplikację do Azure przy użyciu tego samego konta.
7	Azure PowerShell	Jeśli deweloper uwierzytelnił się w Azure przy użyciu polecenia cmdlet Connect-AzAccount Azure PowerShell, uwierzytelnij aplikację w Azure przy użyciu tego samego konta.
8	interfejs wiersza polecenia dewelopera Azure	Jeśli deweloper uwierzytelnił się w Azure przy użyciu polecenia azd auth login interfejsu wiersza polecenia dewelopera Azure, uwierzytelnij się przy użyciu tego konta.
9	Brokera	Uwierzytelnia się przy użyciu konta domyślnego zalogowanego do systemu operacyjnego za pośrednictwem brokera. Wymaga zainstalowania pakietu azure-identity-broker , ponieważ jest używane wystąpienie obsługiwane przez brokera InteractiveBrowserCredential .

W najprostszej formie można użyć wersji DefaultAzureCredential bez parametrów w następujący sposób:

import com.azure.identity.DefaultAzureCredential;
import com.azure.identity.DefaultAzureCredentialBuilder;

// Code omitted for brevity

DefaultAzureCredential credential = new DefaultAzureCredentialBuilder()
    .build();

Jak dostosować DefaultAzureCredential

W poniższych sekcjach opisano strategie kontrolowania poświadczeń zawartych w łańcuchu.

Wyklucz kategorię typu poświadczeń

Aby wykluczyć wszystkie Developer tool lub Deployed service poświadczenia, ustaw odpowiednio zmienną środowiskową AZURE_TOKEN_CREDENTIALS na prod lub dev. Gdy jest używana wartość prod , podstawowy łańcuch poświadczeń wygląda następująco:

W przypadku użycia wartości dev łańcuch wygląda następująco:

Ważne

Zmiennej środowiskowej AZURE_TOKEN_CREDENTIALS są obsługiwane w pakietach azure-identity wersji 1.16.1 i nowszej.

Aby upewnić się, że zmienna środowiskowa jest zdefiniowana i ustawiona na obsługiwany ciąg, wywołaj metodę requireEnvVars w następujący sposób:

DefaultAzureCredential credential = new DefaultAzureCredentialBuilder()
    .requireEnvVars(AzureIdentityEnvVars.AZURE_TOKEN_CREDENTIALS)
    .build();

Ważne

Metoda requireEnvVars jest dostępna w pakiecie azure-identity w wersjach 1.18.0 i nowszych.

Aby użyć niestandardowej nazwy zmiennej środowiskowej zamiast domyślnej AZURE_TOKEN_CREDENTIALS, użyj polecenia AzureIdentityEnvVars.fromString() , aby utworzyć odwołanie do zmiennej niestandardowej:

DefaultAzureCredential credential = new DefaultAzureCredentialBuilder()
    .requireEnvVars(AzureIdentityEnvVars.fromString("MY_CUSTOM_TOKEN_CREDENTIALS"))
    .build();

Uwaga / Notatka

Metoda requireEnvVars zgłasza błąd IllegalStateException , jeśli określone zmienne środowiskowe nie są ustawione lub są puste.

Używanie określonego poświadczenia

Aby wykluczyć wszystkie poświadczenia z wyjątkiem jednego, ustaw zmienną środowiskową AZURE_TOKEN_CREDENTIALS na nazwę poświadczenia. Możesz, na przykład, zmniejszyć DefaultAzureCredential do AzureCliCredential, ustawiając AZURE_TOKEN_CREDENTIALS na AzureCliCredential. Porównanie ciągów jest wykonywane w sposób niewrażliwy na wielkość liter. Prawidłowe wartości ciągów dla zmiennej środowiskowej obejmują:

• AzureCliCredential
• AzureDeveloperCliCredential
• AzurePowerShellCredential
• EnvironmentCredential
• IntelliJCredential
• ManagedIdentityCredential
• VisualStudioCodeCredential
• WorkloadIdentityCredential

Ważne

Zmienna AZURE_TOKEN_CREDENTIALS środowiskowa obsługuje poszczególne nazwy poświadczeń w pakietach azure-identity wersjach 1.17.0 lub nowszych.

Aby upewnić się, że zmienna środowiskowa jest zdefiniowana i ustawiona na obsługiwany ciąg, wywołaj metodę requireEnvVars w następujący sposób:

DefaultAzureCredential credential = new DefaultAzureCredentialBuilder()
    .requireEnvVars(AzureIdentityEnvVars.AZURE_TOKEN_CREDENTIALS)
    .build();

ChainedTokenCredential — omówienie

ChainedTokenCredential to pusty łańcuch, do którego dodasz poświadczenia zgodnie z potrzebami aplikacji. Na przykład:

import com.azure.identity.AzureCliCredential;
import com.azure.identity.AzureCliCredentialBuilder;
import com.azure.identity.ChainedTokenCredential;
import com.azure.identity.ChainedTokenCredentialBuilder;
import com.azure.identity.IntelliJCredential;
import com.azure.identity.IntelliJCredentialBuilder;

// Code omitted for brevity

AzureCliCredential cliCredential = new AzureCliCredentialBuilder()
    .build();
IntelliJCredential ijCredential = new IntelliJCredentialBuilder()
    .build();

ChainedTokenCredential credential = new ChainedTokenCredentialBuilder()
    .addLast(cliCredential)
    .addLast(ijCredential)
    .build();

Powyższy przykład kodu tworzy dostosowany łańcuch poświadczeń składający się z dwóch poświadczeń w czasie programowania. Najpierw podejmowana jest próba z AzureCliCredential, a w razie potrzeby z IntelliJCredential. W formie graficznej łańcuch wygląda następująco:

Napiwek

Aby uzyskać lepszą wydajność, zoptymalizuj kolejność poświadczeń w ChainedTokenCredential z większości do najmniej używanych poświadczeń.

Instrukcja użytkowania DefaultAzureCredential

DefaultAzureCredential jest niewątpliwie najprostszym sposobem rozpoczęcia pracy z biblioteką Azure Identity, ale z tą wygodą wiążą się kompromisy. Po wdrożeniu aplikacji w Azure należy zrozumieć wymagania dotyczące uwierzytelniania aplikacji i rozważyć, czy DefaultAzureCredential jest odpowiednia dla danego scenariusza.

DefaultAzureCredential oferuje kluczową korzyść: rozdziela kod aplikacji z określonych mechanizmów uwierzytelniania, umożliwiając zmianę konfiguracji uwierzytelniania bez modyfikowania kodu. Dla doświadczonych deweloperów, którzy świadomie konfigurują swoje uwierzytelnianie produkcyjne, ta elastyczność może być cenna. Jednak ta elastyczność wiąże się z potencjalnymi wadami:

• Problemy z debugowaniem: w przypadku niepowodzenia uwierzytelniania, debugowanie oraz identyfikacja wadliwych poświadczeń mogą być trudne. Należy włączyć rejestrowanie, aby zobaczyć postęp z jednego poświadczenia do następnego i stan powodzenia/niepowodzenia każdego z nich. Aby uzyskać więcej informacji, zobacz Debugowanie poświadczeń łańcuchowych.
• Obciążenie związane z wydajnością: proces sekwencyjnie próbujący uzyskać wiele poświadczeń może wprowadzić obciążenie związane z wydajnością. Na przykład podczas uruchamiania na lokalnym komputerze deweloperskim tożsamość zarządzana jest niedostępna. W związku z tym ManagedIdentityCredential zawsze kończy się niepowodzeniem w lokalnym środowisku projektowym.
• Nieprzewidywalne zachowanie: DefaultAzureCredential sprawdza obecność niektórych zmiennych środowiskowych. Możliwe, że ktoś może dodać lub zmodyfikować te zmienne środowiskowe na poziomie systemu na maszynie hosta. Te zmiany są stosowane globalnie i w związku z tym zmieniają zachowanie DefaultAzureCredential w trakcie działania dowolnej aplikacji uruchomionej na tym komputerze.
• Niezgodność uprawnień: DefaultAzureCredential zatrzymuje się na pierwszym poświadczeniu, które pomyślnie uzyskuje token, niezależnie od tego, czy to poświadczenie ma odpowiednie uprawnienia. Na przykład lokalne poświadczenia deweloperskie mogą mieć szersze uprawnienia niż zarządzana tożsamość w środowisku produkcyjnym, co powoduje, że aplikacja działa lokalnie, ale po wdrożeniu nie przechodzi kontroli autoryzacji.

Debugowanie poświadczeń łańcuchowych

Aby zdiagnozować nieoczekiwany problem lub zrozumieć, co robi poświadczenie łańcuchowe, włączyć rejestrowanie w aplikacji.

W celach ilustracyjnych załóżmy, że forma bez parametrów DefaultAzureCredential służy do uwierzytelniania żądania na koncie Blob Storage. Aplikacja działa w lokalnym środowisku programistycznym, a deweloper uwierzytelniony w Azure przy użyciu Azure CLI. Po uruchomieniu aplikacji w danych wyjściowych są wyświetlane następujące istotne wpisy:

[main] INFO com.azure.identity.ChainedTokenCredential - Azure Identity => Attempted credential EnvironmentCredential is unavailable.
[main] INFO com.azure.identity.ChainedTokenCredential - Azure Identity => Attempted credential WorkloadIdentityCredential is unavailable.
[ForkJoinPool.commonPool-worker-1] WARN com.microsoft.aad.msal4j.ConfidentialClientApplication - [Correlation ID: aaaa0000-bb11-2222-33cc-444444dddddd] Execution of class com.microsoft.aad.msal4j.AcquireTokenByClientCredentialSupplier failed: java.util.concurrent.ExecutionException: com.azure.identity.CredentialUnavailableException: ManagedIdentityCredential authentication unavailable. Connection to IMDS endpoint cannot be established.
[main] INFO com.azure.identity.ChainedTokenCredential - Azure Identity => Attempted credential ManagedIdentityCredential is unavailable.
[main] INFO com.azure.identity.ChainedTokenCredential - Azure Identity => Attempted credential IntelliJCredential is unavailable.
[main] INFO com.azure.identity.ChainedTokenCredential - Azure Identity => Attempted credential VisualStudioCodeCredential is unavailable.
[main] INFO com.azure.identity.ChainedTokenCredential - Azure Identity => Attempted credential AzureCliCredential returns a token

W poprzednich danych wyjściowych zwróć uwagę, że:

• EnvironmentCredential, WorkloadIdentityCredential, ManagedIdentityCredential, IntelliJCredential oraz VisualStudioCodeCredential nie udało się uzyskać tokenu dostępu Microsoft Entra w podanej kolejności.
• Wywołanie AzureCliCredential.getToken kończy się sukcesem, co wskazuje wpis z sufiksem returns a token. Ponieważ AzureCliCredential powiodło się, nie próbowano żadnych poświadczeń poza tym.