Az Azure identitás könyvtár hitelesítő adatláncai Java számára

Az Azure Identity könyvtár hitelesítő adatot biztosít—nyilvános osztályok, amelyek az Azure Core könyvtár TokenCredential felületét implementálják. A hitelesítő adat egy különálló hitelesítési folyamatot jelöl a hozzáférési jogkivonat Microsoft Entra ID-ből való beszerzéséhez. Ezek a hitelesítő adatok összefűzhetők, hogy a megkísérlendő hitelesítési mechanizmusok rendezett sorozatát alakíthassák ki.

A láncba fűzött hitelesítő adatok működése

Futásidőben egy hitelesítési lánc megpróbálja hitelesíteni magát a lánc első hitelesítő adatával. Ha a hitelesítő adatok nem szereznek be hozzáférési jogkivonatot, a rendszer megkísérli a következő hitelesítő adatot a sorozatban, és így tovább, amíg egy hozzáférési jogkivonatot nem szerez be sikeresen. A következő szekvenciadiagram ezt a viselkedést szemlélteti:

Miért érdemes hitelesítőadat-láncokat használni?

A láncolt hitelesítés a következő előnyöket kínálhatja:

• Környezettudatosság: Automatikusan kiválasztja a legmegfelelőbb hitelesítő adatokat az alkalmazás futási környezete alapján. Nélküle a következőhöz hasonló kódot kell írnia:

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

• Zökkenőmentes váltások: Az alkalmazás gond nélkül átállhat a helyi fejlesztésből az előkészítő vagy éles környezetre, anélkül, hogy módosítaná a hitelesítési kódot.

• Továbbfejlesztett rugalmasság: Tartalmaz egy tartalék mechanizmust, amely a következő hitelesítő adatokra kerül, ha az előző nem szerez be hozzáférési jogkivonatot.

Hogyan válasszunk ki láncolt hitelesítő adatokat

A hitelesítő adatok láncolásának két különböző megközelítése van:

• Előre konfigurált lánc használata: Kezdje egy véleményezett, előre konfigurált lánccal, amely a leggyakoribb hitelesítési forgatókönyveket támogatja. Ehhez a megközelítéshez tekintse meg a DefaultAzureCredential áttekintési szakaszát .
• Lánc létrehozása: Kezdje egy üres lánccal, és csak azt foglalja bele, amire szüksége van. Ehhez a megközelítéshez tekintse meg a ChainedTokenCredential áttekintési szakaszát .

DefaultAzureCredential – áttekintés

A DefaultAzureCredential egy véleményezett, előre konfigurált hitelesítőadat-lánc. Számos környezetet támogat, a leggyakoribb hitelesítési folyamatokkal és fejlesztői eszközökkel együtt. Grafikus formában az alapul szolgáló lánc a következőképpen néz ki:

A hitelesítő adatokra tett kísérletek sorrendje a következő. DefaultAzureCredential

Rendelés	Hitelesítő adat	Leírás
1	Környezet	Beolvassa a környezeti változók gyűjteményét annak megállapításához, hogy az alkalmazáshoz konfigurálva van-e egy alkalmazás-szolgáltatás főazonosító (alkalmazásfelhasználó). Ha igen, DefaultAzureCredential ezeket az értékeket használja az alkalmazás hitelesítéséhez Azure. Ez a módszer helyi fejlesztéskor használható, de leggyakrabban kiszolgálói környezetekben használatos.
2	Munkaterhelés identitás	Ha az alkalmazás olyan Azure gazdagépen van üzembe helyezve, amelyen engedélyezve van a számítási feladatok identitása, hitelesítse ezt a fiókot.
3	Felügyelt identitás	Ha az alkalmazást egy olyan Azure gazdagépen helyezi üzembe, amelyen engedélyezve van a felügyelt identitás, hitelesítse az alkalmazást az Azure-ban ezzel a felügyelt identitással.
4	IntelliJ	Ha a fejlesztő az IntelliJ-hez készült Azure Eszközkészleten keresztül hitelesített, hitelesítse ezt a fiókot.
5	Visual Studio Code	Ha a fejlesztő a Visual Studio Code Azure Resources bővítményén keresztül hitelesítette magát, és telepítve van a azure-identity-broker csomag, akkor hitelesítse az adott fiókot.
6	Azure CLI	Ha a fejlesztő hitelesítette magát az Azure CLI az login parancsával az Azure-hoz, akkor az alkalmazást is ugyanazzal a fiókkal hitelesítse az Azure-hoz.
7	Azure PowerShell	Ha a fejlesztő az Azure PowerShell Connect-AzAccount parancsmagjával hitelesítette magát az Azure-ban, hitelesítse az alkalmazást az Azure-hoz ugyanazzal a fiókkal.
8	Azure fejlesztői parancssori felület	Ha a fejlesztő az Azure Fejlesztői CLI azd auth login parancsával hitelesítette magát az Azure-ban, azzal a fiókkal hitelesítsen.
9	Bróker	Hitelesítés az operációs rendszerbe egy közvetítőn keresztül bejelentkezett alapértelmezett fiókkal. Az azure-identity-broker csomag telepítését igényli, mivel a rendszer egy közvetítő által engedélyezett példányt InteractiveBrowserCredential használ.

Legegyszerűbb formájában a paraméter nélküli verziót DefaultAzureCredential az alábbiak szerint használhatja:

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

// Code omitted for brevity

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

A DefaultAzureCredential testreszabása

Az alábbi szakaszok a láncban szereplő hitelesítő adatok szabályozására szolgáló stratégiákat ismertetik.

Hitelesítőadat-típus kategória kizárása

Ha ki akarja zárni az összes Developer tool vagy Deployed service hitelesítő adatot, állítsa be a AZURE_TOKEN_CREDENTIALS környezeti változót prod vagy dev értékre. Ha egy értéket prod használ, a mögöttes hitelesítőadat-lánc a következőképpen néz ki:

Ha egy értéket dev használ, a lánc a következőképpen néz ki:

Fontos

A AZURE_TOKEN_CREDENTIALS környezeti változó az 1.16.1-s és újabb csomagverziókban azure-identity támogatott.

Annak érdekében, hogy a környezeti változó definiálva legyen, és egy támogatott sztringre legyen beállítva, hívja meg a metódust requireEnvVars az alábbiak szerint:

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

Fontos

A requireEnvVars módszer az 1.18.0-s és újabb csomagverziókban azure-identity érhető el.

Ha az alapértelmezett AZURE_TOKEN_CREDENTIALShelyett egyéni környezeti változónevet szeretne használni, AzureIdentityEnvVars.fromString() hozzon létre egy hivatkozást az egyéni változóra:

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

Megjegyzés:

A requireEnvVars metódus egy IllegalStateException olyan értéket ad, ha a megadott környezeti változók nincsenek beállítva, vagy üresek.

Adott hitelesítő adat használata

Ha egy kivételével minden hitelesítő adatot ki szeretne zárni, állítsa be a környezeti változót AZURE_TOKEN_CREDENTIALS a hitelesítő adatok nevére. Például a DefaultAzureCredential láncot AzureCliCredential-re csökkentheti azzal, hogy a AZURE_TOKEN_CREDENTIALS értékét AzureCliCredential-re állítja be. A sztring-összehasonlítás kis- és nagybetűkre érzéketlen módon történik. A környezeti változó érvényes sztringértékei a következők:

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

Fontos

A AZURE_TOKEN_CREDENTIALS környezeti változó támogatja az egyes hitelesítő adatok nevét az 1.17.0-s és újabb csomagverziókban azure-identity .

Annak érdekében, hogy a környezeti változó definiálva legyen, és egy támogatott sztringre legyen beállítva, a hívási metódus az alábbiak szerint követeli meg azEnvVars függvényt:

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

ChainedTokenCredential áttekintés

A ChainedTokenCredential egy üres lánc, amelyhez hitelesítő adatokat ad hozzá az alkalmazás igényeinek megfelelően. Példa:

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

Az előző példakód egy személyre szabott hitelesítőadat-láncot hoz létre, amely két fejlesztési idejű hitelesítő adatból áll. AzureCliCredential-t kísérlik meg először, majd szükség esetén IntelliJCredential-et. Grafikus formában a lánc a következőképpen néz ki:

Tipp.

A jobb teljesítmény érdekében optimalizálja a hitelesítő adatok sorrendjét ChainedTokenCredential a legtöbbtől a legkevésbé használt hitelesítő adatokig.

Használati útmutató a DefaultAzureCredentialhoz

DefaultAzureCredential kétségtelenül a legegyszerűbb módszer az Azure Identitáskódtár használatának megkezdésére, de ezzel a kényelemmel kompromisszumok is járnak. Az alkalmazás Azure való üzembe helyezése után ismernie kell az alkalmazás hitelesítési követelményeit, és meg kell fontolnia, hogy a DefaultAzureCredential megfelelő-e a forgatókönyvhöz.

DefaultAzureCredential Kulcsfontosságú előnyt kínál: leválasztja az alkalmazás kódját az adott hitelesítési mechanizmusokról, így kód módosítása nélkül módosíthatja a hitelesítési konfigurációt. A tapasztalt fejlesztők számára, akik tudatosan konfigurálják az éles hitelesítést, ez a rugalmasság értékes lehet. Ennek a rugalmasságnak azonban vannak lehetséges hátrányai:

• Hibakeresési problémák: Ha a hitelesítés sikertelen, a hibás hitelesítő adatok hibakeresése és azonosítása kihívást jelenthet. Engedélyeznie kell a naplózást, hogy láthassa az egyik hitelesítő adatból a következőbe való előrehaladást, valamint az egyes hitelesítő adatok sikerességi/sikertelenségi állapotát. További információ: Láncolt hitelesítő adatok hibakeresése.
• Teljesítményterhelés: A több hitelesítő adat egymás utáni kipróbálásának folyamata teljesítményterhelést okozhat. Ha például helyi fejlesztőgépen fut, a felügyelt identitás nem érhető el. ManagedIdentityCredential Ezért a helyi fejlesztési környezetben mindig meghiúsul.
• Előzhető viselkedés: DefaultAzureCredential bizonyos környezeti változók jelenlétét ellenőrzi. Lehetséges, hogy valaki hozzáadhatja vagy módosíthatja ezeket a környezeti változókat a gazdaszámítógép rendszerszintjén. Ezek a módosítások globálisan érvényesek, ezért a számítógépen futó alkalmazások futásidejű viselkedését DefaultAzureCredential megváltoztatják.
• Engedélyeltérések: DefaultAzureCredential a jogkivonatot sikeresen beszerző első hitelesítő adatnál leáll, függetlenül attól, hogy az adott hitelesítő adat rendelkezik-e a megfelelő engedélyekkel. Előfordulhat például, hogy egy helyi fejlesztési hitelesítő adat szélesebb körű engedélyekkel rendelkezik, mint az éles környezetben felügyelt identitás, ami azt eredményezi, hogy az alkalmazás helyileg működik, de az üzembe helyezés után az engedélyezés ellenőrzése sikertelen.

Láncolt hitelesítő adatok hibakeresése

Egy váratlan probléma diagnosztizálásához vagy a láncolt hitelesítő adatok használatának megértéséhez engedélyezze a naplózást az alkalmazásban.

Ábrakészítés céljából tegyük fel, hogy a DefaultAzureCredential paraméter nélküli formáját használja egy Blob Storage-fiókra irányuló kérés hitelesítéséhez. Az alkalmazás a helyi fejlesztési környezetben fut, és a fejlesztő hitelesítve van Azure a Azure CLI használatával. Az alkalmazás futtatásakor az alábbi vonatkozó bejegyzések jelennek meg a kimenetben:

[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

Az előző kimenetben figyelje meg, hogy:

• EnvironmentCredential, WorkloadIdentityCredential, ManagedIdentityCredential, IntelliJCredential és VisualStudioCodeCredential nem sikerült Microsoft Entra hozzáférési jogkivonatot beszerezni ebben a sorrendben.
• A AzureCliCredential.getToken hívás sikeres, ahogy azt a returns a token-utótagú bejegyzés is jelzi. Mivel AzureCliCredential sikeres volt, nem próbáltak ki további hitelesítő adatokat.