Hitelesítőadat-láncok a Pythonhoz készült Azure Identity-kódtárban

Az Azure Identity-kódtár hitelesítő adatokat biztosít– az Azure Core-kódtár TokenCredential protokollját implementáló nyilvános osztályok. A hitelesítő adatok egy különálló hitelesítési folyamatot jelentenek a hozzáférési jogkivonat Microsoft Entra-azonosító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.

Láncolt hitelesítő működése

Futásidőben egy hitelesítőadat-lánc megkísérli a hitelesítést a sorozat első hitelesítő adataival. 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ő adatok a következő előnyöket kínálhatják:

• 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:

  # Set up credential based on environment (Azure or local development)
  if os.getenv("WEBSITE_HOSTNAME"):
      credential = ManagedIdentityCredential(client_id=user_assigned_client_id)
  else:
      credential = AzureCliCredential()
  

• Zökkenőmentes áttűnés: Az alkalmazás a helyi fejlesztési környezetből az előkészítési vagy éles környezetbe válthat 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.

Láncolt azonosító kiválasztása

A hitelesítő adatok láncolásának két különböző filozófiája van:

• Lánc "lebontása": Kezdje egy előre konfigurált lánccal, és zárja ki azt, amire nincs szüksége. Ehhez a megközelítéshez tekintse meg a DefaultAzureCredential áttekintési szakaszát .
• Lánc összeállítása: Kezdje egy üres lánccal, és csak azt tegye 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 DefaultAzureCredential .

Rendelés	Hitelesítő adat	Leírás	Alapértelmezés szerint engedélyezett?
1	Környezet	Beolvassa a környezeti változók gyűjteményét annak megállapítására, hogy az alkalmazáshoz konfigurálva van-e egy alkalmazási szolgáltatói azonosító (alkalmazásfelhasználó). Ha igen, DefaultAzureCredential ezeket az értékeket használva hitelesítheti az alkalmazást az Azure-ban. Ezt a módszert leggyakrabban kiszolgálókörnyezetekben használják, de helyi fejlesztéskor is használható.	Igen
2	Számítási feladatok identitása	Ha az alkalmazás olyan Azure-gazdagépen van üzembe helyezve, amelyen engedélyezve van a Számítási feladat identitása, hitelesítse ezt a fiókot.	Igen
3	Felügyelt identitás	Ha az alkalmazás olyan Azure-gazdagépen van üzembe helyezve, amelyen engedélyezve van a felügyelt identitás, hitelesítse az alkalmazást az Azure-ban ezzel a felügyelt identitással.	Igen
4	Megosztott jogkivonat tár	Csak Windows rendszeren, ha a fejlesztő a Visual Studióba való bejelentkezéssel hitelesítette az Azure-t, azonos fiókkal hitelesítse az alkalmazást az Azure-ban.	Igen
5	Azure CLI	Ha a fejlesztő az Azure CLI parancsával az login hitelesítést végzett az Azure-ban, azonos fiókkal hitelesítse az alkalmazást az Azure-ban.	Igen
6	Azure PowerShell	Ha a fejlesztő az Azure PowerShell parancsmagjával Connect-AzAccount hitelesítette az Azure-t, azonos fiókkal hitelesítse az alkalmazást az Azure-ban.	Igen
7	Azure Developer CLI	Ha a fejlesztő az Azure Developer CLI azd auth login parancsával hitelesítve van az Azure-ban, akkor ezzel a fiókkal hitelesíthet.	Igen
8	Interaktív böngésző	Ha engedélyezve van, interaktívan hitelesítse a fejlesztőt az aktuális rendszer alapértelmezett böngészőjén keresztül.	Nem

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

from azure.identity import DefaultAzureCredential
from azure.storage.blob import BlobServiceClient

# Acquire a credential object
credential = DefaultAzureCredential()

blob_service_client = BlobServiceClient(
    account_url="https://<my_account_name>.blob.core.windows.net",
    credential=credential
)

A DefaultAzureCredential testreszabása

A következő szakaszok a hitelesítő adatok láncból való kihagyásával kapcsolatos stratégiákat ismertetik.

Egyéni hitelesítő adatok kizárása

Egy adott hitelesítő adat kizárásához használja a megfelelő DefaultAzureCredential előtaggal rendelkező exclude. Példa:

credential = DefaultAzureCredential(
    exclude_environment_credential=True, 
    exclude_workload_identity_credential=True,
    managed_identity_client_id=user_assigned_client_id
)

Az előző kódmintában, EnvironmentCredential és WorkloadIdentityCredential el lesz távolítva a hitelesítőadat-láncból. Ennek eredményeképpen az első megkísérlendő hitelesítő adat az ManagedIdentityCredential. A módosított lánc így néz ki:

Feljegyzés

InteractiveBrowserCredential alapértelmezés szerint ki van zárva, ezért nem jelenik meg az előző ábrán. A InteractiveBrowserCredential belefoglalásához állítsa be a exclude_interactive_browser_credential kulcsszóparamétert False a DefaultAzureCredential konstruktor meghívásakor.

Mivel több exclude-előtagú kulcsszóparaméter van beállítva True (a hitelesítő adatok kizárása konfigurálva), csökken DefaultAzureCredential használatának előnyei. Ilyen esetekben jobb választás, ChainedTokenCredential és kevesebb kódot igényel. A szemléltetés érdekében ez a két kódminta ugyanúgy viselkedik:

DefaultAzureCredential

credential = DefaultAzureCredential(
    exclude_environment_credential=True,
    exclude_workload_identity_credential=True,
    exclude_shared_token_cache_credential=True,
    exclude_azure_powershell_credential=True,
    exclude_azure_developer_cli_credential=True,
    managed_identity_client_id=user_assigned_client_id
)

ChainedTokenCredential

credential = ChainedTokenCredential(
    ManagedIdentityCredential(client_id=user_assigned_client_id),
    AzureCliCredential()
)

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.23.0-s és újabb csomagverziókban azure-identity támogatott.

ChainedTokenCredential áttekintés

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

credential = ChainedTokenCredential(
    AzureCliCredential(),
    AzureDeveloperCliCredential()
)

Az előző kódminta egy személyre szabott hitelesítőadat-láncot hoz létre, amely két fejlesztési idejű hitelesítő adatból áll. Először a AzureCliCredential kerül megkísérlésre, szükség esetén pedig a AzureDeveloperCliCredential. 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 az Azure Identity-kódtár használatának legegyszerűbb módja, de ezzel a kényelemmel kompromisszumok is járnak. Miután üzembe helyezi az alkalmazást az Azure-ban, ismernie kell az alkalmazás hitelesítési követelményeit. Ezért cserélje le a DefaultAzureCredential egy adott TokenCredential implementációra, például ManagedIdentityCredential.

A következőkért:

• 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. Ennek eredményeként ManagedIdentityCredential mindig meghiúsul a helyi fejlesztési környezetben, kivéve, ha a megfelelő exclude előtaggal ellátott tulajdonság kifejezetten le van tiltva.
• Kiszámíthatatlan 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.

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. Ha szeretné, szűrje a naplókat csak az Azure Identity-ügyfélkódtárból kibocsátott eseményekre. Példa:

import logging
from azure.identity import DefaultAzureCredential

# Set the logging level for the Azure Identity library
logger = logging.getLogger("azure.identity")
logger.setLevel(logging.DEBUG)

# Direct logging output to stdout. Without adding a handler,
# no logging output is visible.
handler = logging.StreamHandler(stream=sys.stdout)
logger.addHandler(handler)

# Optional: Output logging levels to the console.
print(
    f"Logger enabled for ERROR={logger.isEnabledFor(logging.ERROR)}, "
    f"WARNING={logger.isEnabledFor(logging.WARNING)}, "
    f"INFO={logger.isEnabledFor(logging.INFO)}, "
    f"DEBUG={logger.isEnabledFor(logging.DEBUG)}"
)

Ábrakészítés céljából tegyük fel, hogy a paraméter nélküli formátumot DefaultAzureCredential használják a blobtároló-fiókra irányuló kérések hitelesítéséhez. Az alkalmazás a helyi fejlesztési környezetben fut, és a fejlesztő az Azure CLI használatával hitelesítve van az Azure-ban. Tegyük fel azt is, hogy a naplózási szint a következőre logging.DEBUGvan állítva: . Az alkalmazás futtatásakor az alábbi vonatkozó bejegyzések jelennek meg a kimenetben:

Logger enabled for ERROR=True, WARNING=True, INFO=True, DEBUG=True
No environment configuration found.
ManagedIdentityCredential will use IMDS
EnvironmentCredential.get_token failed: EnvironmentCredential authentication unavailable. Environment variables are not fully configured.
Visit https://aka.ms/azsdk/python/identity/environmentcredential/troubleshoot to troubleshoot this issue.
ManagedIdentityCredential.get_token failed: ManagedIdentityCredential authentication unavailable, no response from the IMDS endpoint.     
SharedTokenCacheCredential.get_token failed: SharedTokenCacheCredential authentication unavailable. No accounts were found in the cache.
AzureCliCredential.get_token succeeded
[Authenticated account] Client ID: 00001111-aaaa-2222-bbbb-3333cccc4444. Tenant ID: aaaabbbb-0000-cccc-1111-dddd2222eeee. User Principal Name: unavailableUpn. Object ID (user): aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb
DefaultAzureCredential acquired a token from AzureCliCredential

Az előző kimenetben figyelje meg, hogy:

• EnvironmentCredential, ManagedIdentityCredentialés SharedTokenCacheCredential ebben a sorrendben nem sikerült beszerezni a Microsoft Entra hozzáférési jogkivonatot.
• A AzureCliCredential.get_token hívás sikeres, és a kimenet azt is jelzi, hogy DefaultAzureCredential jogkivonatot szerzett be a AzureCliCredential-től. Mivel AzureCliCredential sikeres volt, azon túl további hitelesítő adatok nem kerültek próbára.

Feljegyzés

Az előző példában a naplózási szint a következőre logging.DEBUGvan állítva: . Legyen óvatos a naplózási szint használatakor, mivel bizalmas információkat képes kiadni. Ebben az esetben például az ügyfél-azonosító, a bérlőazonosító és a fejlesztő Azure-beli felhasználói főelemének objektumazonosítója. Az egyértelműség érdekében az összes nyomkövetési információ el lett távolítva a kimenetből.