Łańcuchy poświadczeń w bibliotece tożsamości platformy Azure dla języka Java

Biblioteka tożsamości platformy Azure udostępnia poświadczenia — klasy publiczne, które implementują interfejs TokenCredential biblioteki Azure Core. Poświadczenie reprezentuje odrębny przepływ uwierzytelniania na potrzeby uzyskiwania tokenu dostępu z identyfikatora Entra firmy Microsoft. 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ą dwie różne filozofie 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. W celu realizacji tego podejścia zobacz sekcję Omówienie ChainedTokenCredential.

Przegląd DefaultAzureCredential

DefaultAzureCredential jest specjalnie dostosowanym, 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 jakiej DefaultAzureCredential próbuje użyć poświadczeń, jest następująca.

Zamówienie	Kwalifikacje	opis
1	Środowisko	Odczytuje kolekcję zmiennych środowiskowych w celu określenia, czy dla aplikacji skonfigurowano głównego użytkownika usługi (użytkownika aplikacji). Jeśli tak, DefaultAzureCredential użyj tych wartości do uwierzytelniania aplikacji na platformie Azure. Ta metoda jest najczęściej używana w środowiskach serwera, ale może być również używana podczas opracowywania lokalnie.
2	Tożsamość zadania	Jeśli aplikacja zostanie wdrożona na hoście platformy 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 platformy Azure z włączoną tożsamością zarządzaną, uwierzytelnij aplikację na platformie Azure przy użyciu tej tożsamości zarządzanej.
4	IntelliJ	Jeśli deweloper został uwierzytelniony za pośrednictwem narzędzia Azure Toolkit dla IntelliJ, uwierzytelnij to konto.
5	Visual Studio Code	Jeśli deweloper został uwierzytelniony za pomocą rozszerzenia Visual Studio Code Azure Resources oraz jeśli zainstalowano pakiet azure-identity-broker, uwierzytelnij to konto.
6	Interfejs wiersza polecenia platformy Azure	Jeśli deweloper został uwierzytelniony w Azure za pomocą polecenia Azure CLI, uwierzytelnij aplikację w Azure używając tego samego konta.
7	Azure PowerShell	Jeśli deweloper uwierzytelnił się na platformie Azure przy użyciu polecenia cmdlet programu Azure PowerShell Connect-AzAccount , uwierzytelnij aplikację na platformie Azure przy użyciu tego samego konta.
8	Interfejs wiersza polecenia dla deweloperów platformy Azure	Jeśli deweloper uwierzytelnił się w Azure za pomocą polecenia azd auth login z Azure Developer CLI, 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 najprostszym ujęciu 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();

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ładowy kod 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ą tożsamości platformy Azure, ale z tą wygodą wiążą się kompromisy. Po wdrożeniu aplikacji na platformie Azure należy zrozumieć wymagania dotyczące uwierzytelniania aplikacji. Z tego powodu zastąp DefaultAzureCredential określoną implementacją TokenCredential, taką jak ManagedIdentityCredential.

Poniżej przedstawiono przyczyny:

• Wyzwania związane z debugowaniem: w przypadku niepowodzenia uwierzytelniania może być trudne debugowanie i identyfikowanie obraźliwych poświadczeń. 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ść określonych 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.

Debugowanie poświadczeń łańcuchowych

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

W celach ilustracyjnych załóżmy, że forma bez parametrów DefaultAzureCredential jest używana do uwierzytelniania żądania na koncie usługi Blob Storage. Aplikacja działa w lokalnym środowisku deweloperskim, a deweloper uwierzytelnił się 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 i VisualStudioCodeCredential – każdy z nich nie zdołał uzyskać tokenu dostępu Microsoft Entra, w tej 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.