Řetězy přihlašovacích údajů v knihovně identit Azure pro Java

Knihovna identit Azure poskytuje credentials – veřejné třídy, které implementují rozhraní TokenCredential knihovny Azure Core. Přihlašovací údaje představují jedinečný tok ověřování pro získání přístupového tokenu z Microsoft Entra ID. Tyto přihlašovací údaje lze spojit dohromady a vytvořit seřazenou posloupnost ověřovacích mechanismů, které mají být vyzkoušeny.

Jak fungují propojené přihlašovací údaje

Při spuštění se řetěz přihlašovacích údajů pokusí ověřit prvními přihlašovacími údaji v sekvenci. Pokud se tento přihlašovací údaj nepodaří získat přístupový token, pokusí se další přihlašovací údaje v této sekvenci atd., dokud se přístupový token úspěšně nezíská. Toto chování znázorňuje následující sekvenční diagram:

Proč používat řetězy přihlašovacích údajů

Zřetězený přihlašovací údaj může nabídnout následující výhody:

• Rozpoznávání prostředí: Automaticky vybere nejvhodnější přihlašovací údaje na základě prostředí, ve kterém je aplikace spuštěná. Bez něj byste museli psát kód takto:

  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();
  }
  

• Bezproblémové přechody: Aplikace se může přesunout z místního vývoje do přípravného nebo produkčního prostředí beze změny ověřovacího kódu.

• Vylepšená odolnost: Zahrnuje náhradní mechanismus, který se přesune na další přihlašovací údaje, když se předchozí pokus o získání přístupového tokenu nezdaří.

Jak vybrat propojené přihlašovací údaje

Existují dva různé přístupy k řetězení autentizačních údajů:

• Použijte předkonfigurovaný řetězec: Začněte s předkonstruovaným řetězem, který vyhovuje nejběžnějším scénářům ověřování. Tento přístup najdete v části s přehledem DefaultAzureCredential.
• "Sestavte" řetězec: Začněte prázdným řetězem a zahrňte pouze to, co potřebujete. Viz část Přehled ChainedTokenCredential pro tento přístup.

Přehled Default Azure Credential

DefaultAzureCredential je názorově předkonfigurovaný řetězec přihlašovacích údajů. Je navržená tak, aby podporovala mnoho prostředí spolu s nejběžnějšími toky ověřování a vývojářskými nástroji. Základní řetězec v grafické podobě vypadá takto:

Pořadí, ve kterém DefaultAzureCredential zkouší přihlašovací údaje, je následující.

Objednávka	Osvědčení	Popis
1	Prostředí	Načte kolekci proměnných environment a určí, jestli je pro aplikaci nakonfigurovaný instanční objekt aplikace (uživatel aplikace). Pokud ano, DefaultAzureCredential tyto hodnoty použije k ověření aplikace pro Azure. Tuto metodu lze použít při místním vývoji, ale nejčastěji se používá v serverových prostředích.
2	Identita úloh	Pokud je aplikace nasazená na hostitele Azure s povolenou identitou úlohy, ověřte tento účet.
3	Spravovaná identita	Pokud je aplikace nasazená na hostitele Azure s povolenou spravovanou identitou, ověřte aplikaci vůči Azure pomocí této spravované identity.
4	IntelliJ	Pokud se vývojář ověřil prostřednictvím sady Azure Toolkit for IntelliJ, ověřte tento účet.
5	Visual Studio Code	Pokud se vývojář ověřil prostřednictvím rozšíření Azure Resources pro Visual Studio Code a balíček azure-identity-broker je nainstalován, ověřte tento účet.
6	Azure CLI	Pokud se vývojář ověřil v Azure pomocí příkazu az login Azure CLI, ověřte aplikaci v Azure pomocí stejného účtu.
7	Azure PowerShell	Pokud se vývojář ověřil v Azure pomocí cmdletu Azure PowerShell Connect-AzAccount, ověřte aplikaci v Azure pomocí stejného účtu.
8	Azure Cli pro vývojáře	Pokud se vývojář ověřil v Azure pomocí příkazu azd auth login rozhraní příkazového řádku pro vývojáře Azure, ověřte ho pomocí daného účtu.
9	zprostředkovatel	Ověřuje se pomocí výchozího účtu přihlášeného k operačnímu systému prostřednictvím zprostředkovatele. Vyžaduje nainstalování balíčku azure-identity-broker, protože se používá instance InteractiveBrowserCredential s povoleným zprostředkovatelem.

V nejjednodušší podobě můžete použít bezparametrovou verzi DefaultAzureCredential následujícím způsobem:

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

// Code omitted for brevity

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

Jak přizpůsobit DefaultAzureCredential

Následující části popisují strategie pro řízení, které přihlašovací údaje jsou zahrnuty v řetězci.

Vyloučení kategorie typu přihlašovacích údajů

Chcete-li vyloučit všechny přihlašovací údaje Developer tool nebo Deployed service, nastavte proměnnou prostředí AZURE_TOKEN_CREDENTIALS na prod nebo dev. Pokud se použije hodnota prod, základní řetězec přihlašovacích údajů vypadá takto:

Pokud se použije hodnota dev , řetězec vypadá takto:

Důležité

Proměnná AZURE_TOKEN_CREDENTIALS prostředí je podporována ve azure-identity verzích balíčku 1.16.1 a novějších.

Pokud chcete zajistit, aby byla proměnná prostředí definovaná a nastavená na podporovaný řetězec, zavolejte metodu requireEnvVars následujícím způsobem:

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

Důležité

Metoda requireEnvVars je k dispozici ve azure-identity verzích balíčku 1.18.0 a novějších.

Pokud chcete místo výchozího AZURE_TOKEN_CREDENTIALSnázvu použít vlastní proměnnou prostředí, použijte AzureIdentityEnvVars.fromString() k vytvoření odkazu na vlastní proměnnou:

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

Poznámka:

Metoda requireEnvVars vyvolá výjimku IllegalStateException, pokud zadané proměnné prostředí jsou prázdné nebo nejsou nastaveny.

Použití konkrétních přihlašovacích údajů

Pokud chcete vyloučit všechny přihlašovací údaje kromě jednoho, nastavte proměnnou AZURE_TOKEN_CREDENTIALS prostředí na název přihlašovacích údajů. Můžete například zmenšit řetěz DefaultAzureCredential na AzureCliCredential tím, že nastavíte AZURE_TOKEN_CREDENTIALS na AzureCliCredential. Porovnání řetězců se provádí bez rozlišování velkých a malých písmen. Platné řetězcové hodnoty pro proměnnou prostředí zahrnují:

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

Důležité

Proměnná prostředí AZURE_TOKEN_CREDENTIALS podporuje jednotlivé názvy pověření ve verzích balíčku azure-identity 1.17.0 a novějších.

Chcete-li zajistit, aby byla proměnná prostředí definována a nastavena na podporovaný řetězec, zavolejte metodu requireEnvVars následujícím způsobem:

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

Přehled ChainedTokenCredential

ChainedTokenCredential je prázdný řetězec, ke kterému přidáváte přihlašovací údaje, které vyhovují potřebám vaší aplikace. Příklad:

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();

Předchozí příklad kódu vytvoří přizpůsobený řetěz přihlašovacích údajů složený ze dvou přihlašovacích údajů v době vývoje. Nejprve se provede AzureCliCredential, a pokud je to nutné, následuje IntelliJCredential. V grafické podobě řetězec vypadá takto:

Návod

Pokud chcete dosáhnout vyššího výkonu, optimalizujte řazení přihlašovacích údajů v ChainedTokenCredential od většiny po nejméně používané přihlašovací údaje.

Pokyny k použití pro DefaultAzureCredential

DefaultAzureCredential je nepochybně nejjednodušší způsob, jak začít s knihovnou identit Azure, ale s tímto pohodlím přichází kompromisy. Po nasazení aplikace do Azure byste měli porozumět požadavkům na ověřování aplikace a zvážit, jestli je DefaultAzureCredential vhodný pro váš scénář.

DefaultAzureCredential nabízí klíčovou výhodu: odděluje kód aplikace od konkrétních mechanismů ověřování, což vám umožní změnit konfiguraci ověřování beze změny kódu. Pro zkušené vývojáře, kteří při vědomí konfigurují své produkční ověřování, může být tato flexibilita cenná. Tato flexibilita ale přináší potenciální nevýhody:

• Výzvy při ladění: Při selhání ověřování může být náročné ladit a identifikovat chybné přihlašovací údaje. Abyste viděli průběh z jednoho pověření na další a stav úspěchu/selhání každého z nich, musíte povolit protokolování. Další informace najdete v tématu Ladění zřetězených přihlašovacích údajů.
• Výkonová režie: Proces postupného zkoušení více přihlašovacích údajů může představovat výkonovou režii. Například při spuštění na místním vývojovém počítači není spravovaná identita k dispozici. V důsledku toho ManagedIdentityCredential vždy selže v místním vývojovém prostředí.
• Neprediktovatelné chování: DefaultAzureCredential kontroluje přítomnost určitých proměnných prostředí. Je možné, že někdo může přidat nebo upravit tyto proměnné prostředí na úrovni systému na hostitelském počítači. Tyto změny platí globálně a proto mění chování DefaultAzureCredential za běhu v libovolné aplikaci spuštěné na tomto počítači.
• Neshody oprávnění: DefaultAzureCredential Zastaví se u prvních přihlašovacích údajů, které úspěšně získají token, bez ohledu na to, zda mají tato přihlašovací údaje správné oprávnění. Například přihlašovací údaje pro lokální vývoj můžou mít širší oprávnění než spravovaná identita v produkčním prostředí, což umožňuje aplikaci správně fungovat lokálně, ale vede k selhání kontrol autorizace po nasazení.

Ladění zřetězených přihlašovacích údajů

Pokud chcete diagnostikovat neočekávaný problém nebo zjistit, co dělá zřetězený přihlašovací údaj, povolte protokolování v aplikaci.

Pro ilustraci předpokládejme, že k ověření požadavku na účet Blob Storage se používá forma DefaultAzureCredential bez parametrů. Aplikace běží v místním vývojovém prostředí a vývojář se ověřil do Azure pomocí Azure CLI. Při spuštění aplikace se ve výstupu zobrazí následující relevantní položky:

[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

V předchozím výstupu si všimněte, že:

• EnvironmentCredential, WorkloadIdentityCredential, ManagedIdentityCredential, IntelliJCredential a VisualStudioCodeCredential se nepodařilo získat přístupový token Microsoft Entra v daném pořadí.
• Volání AzureCliCredential.getToken se podaří, jak je uvedeno v položce s příponou returns a token. Jakmile AzureCliCredential uspělo, žádné další přihlašovací údaje nebyly zkoušeny.