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

Knihovna Azure Identity poskytuje pověření– veřejné třídy, které implementují protokol 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 ID Microsoft Entra. Tyto přihlašovací údaje je možné zřetězit dohromady, aby tvořily seřazenou posloupnost ověřovacích mechanismů, které mají být použity.

Jak fungují řetězené přihlašovací údaje

Za běhu se řetězec přihlašovacích údajů snaží ověřit pomocí prvního přihlašovacího údaje sekvence. 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:

diagram, který zobrazuje posloupnost řetězu přihlašovacích údajů

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

Zřetězené přihlašovací údaje mohou 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:

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

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 zřetězené přihlašovací údaje

Existují dvě rozdílné filozofie pro řetězení přihlašovacích údajů:

"Rozebrat" řetěz: Začněte s předkonfigurovaným řetězem a odstraňte, co nepotřebujete. Tento přístup najdete v části Přehled DefaultAzureCredential.
"Sestavte" řetězec: Začněte prázdným řetězem a zahrňte pouze to, co potřebujete. Tento přístup naleznete v části Přehled ChainedTokenCredential.

Přehled výchozí pověření Azure

DefaultAzureCredential je názorově vyhraněný a 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	Ověření	Popis	Povoleno ve výchozím nastavení?
1	Prostředí	Načte kolekci proměnných prostředí a určí, jestli je pro aplikaci nakonfigurovaný aplikační služební hlavní objekt (uživatel aplikace). Pokud ano, `DefaultAzureCredential` použije tyto hodnoty k ověření aplikace v Azure. Tato metoda se nejčastěji používá v serverových prostředích, ale dá se použít také při místním vývoji.	Ano
2	Identita úloh	Pokud je aplikace nasazená na hostitele Azure s povolenou identitou úloh, ověřte tento účet.	Ano
3	Spravovaná identita	Pokud je aplikace nasazená na hostitele Azure s povolenou spravovanou identitou, ověřte ji v Azure pomocí této spravované identity.	Ano
4	Mezipaměť sdílených tokenů	Pouze na Windows, pokud se vývojář ověřil v Azure přihlášením do Visual Studio, ověřte aplikaci v Azure pomocí stejného účtu.	Ano
5	Visual Studio Code	Pokud se vývojář ověřil prostřednictvím rozšíření Azure Resources pro Visual Studio Code a je nainstalován balíček azure-identity-broker, ověřte tento účet.	Ano
6	Azure CLI	Pokud se vývojář ověřil v Azure pomocí příkazu Azure CLI `az login` , ověřte aplikaci v Azure pomocí stejného účtu.	Ano
7	Azure PowerShell	Pokud se vývojář ověřil v Azure pomocí rutiny Azure PowerShellu `Connect-AzAccount` , ověřte aplikaci v Azure pomocí stejného účtu.	Ano
8	Azure Developer CLI	Pokud se vývojář ověřil v Azure pomocí příkazu Azure Developer CLI `azd auth login` , ověřte ho pomocí daného účtu.	Ano
9	Interaktivní prohlížeč	Pokud je tato možnost povolená, interaktivně ověřte vývojáře prostřednictvím výchozího prohlížeče aktuálního systému.	Ne
10	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, aby byl nainstalován balíček azure-identity-broker, protože se používá instance `InteractiveBrowserBrokerCredential`.	Ano

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

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
)

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í jednotlivých přihlašovacích údajů

Chcete-li vyloučit jednotlivé přihlašovací údaje z DefaultAzureCredential, použijte exclude s předponou . Příklad:

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

V předchozí ukázce kódu EnvironmentCredential a WorkloadIdentityCredential jsou odebrány z řetězce přihlašovacích údajů. V důsledku toho budou prvním pokusem přihlašovací údaje ManagedIdentityCredential. Upravený řetězec vypadá takto:

Diagram znázorňující tok ověřování pro instanci DefaultAzureCredential po použití parametrů klíčového slova s předponou exclude v konstruktoru k odebrání přihlašovacích údajů prostředí a přihlašovacích údajů identity úlohy

Poznámka:

InteractiveBrowserCredential je ve výchozím nastavení vyloučena, a proto se v předchozím diagramu nezobrazuje. Chcete-li zahrnout InteractiveBrowserCredential, nastavte parametr klíčového slova exclude_interactive_browser_credential na False, když voláte konstruktor DefaultAzureCredential.

Vzhledem k tomu, že se parametry klíčových slov s předponou exclude nastavují na True (konfigurují se vyloučení přihlašovacích údajů), výhody použití DefaultAzureCredential se snižují. V takových případech ChainedTokenCredential je lepší volbou a vyžaduje méně kódu. Pro ilustraci se tyto dvě ukázky kódu chovají stejným způsobem:

DefaultAzureCredential
ChainedTokenCredential

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

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

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:

Diagram znázorňující defaultAzureCredential s AZURE_TOKEN_CREDENTIALS nastaveným na

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

Diagram znázorňující defaultAzureCredential s AZURE_TOKEN_CREDENTIALS nastaveným na

Důležité

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

Pokud chcete zajistit, aby byla proměnná prostředí definovaná a nastavená na podporovaný řetězec, nastavte parametr require_envvar v True konstruktoru:

credential = DefaultAzureCredential(require_envvar=True)

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
InteractiveBrowserCredential
ManagedIdentityCredential
VisualStudioCodeCredential
WorkloadIdentityCredential

Důležité

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

Pokud chcete zajistit, aby byla proměnná prostředí definovaná a nastavená na podporovaný řetězec, nastavte parametr require_envvar na True v konstruktoru takto.

credential = DefaultAzureCredential(require_envvar=True)

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:

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

Předchozí ukázka 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 pokusí AzureCliCredential, a pokud to bude nutné, následuje AzureDeveloperCliCredential. V grafické podobě řetězec vypadá takto:

diagram znázorňující tok ověřování pro instanci ChainedTokenCredential, která se skládá z Azure CLI a přihlašovacích údajů Azure Developer CLI

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šším způsobem, jak začít s knihovnou identit Azure, ale toto pohodlí má své kompromisy. Po nasazení aplikace do Azure byste měli porozumět požadavkům na ověřování aplikace. Z tohoto důvodu nahraďte DefaultAzureCredential konkrétní implementací TokenCredential, například ManagedIdentityCredential.

Tady je důvod:

Problémy s laděním: Při selhání ověřování může být náročné ladit a identifikovat problémové 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ýkonnostní režie: Proces postupného zkoušení více přihlašovacích údajů může představovat výkonnostní 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í, pokud není výslovně zakázáno prostřednictvím vlastnosti s předponou exclude.
Nepředvídatelné 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.

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. Volitelně můžete protokoly filtrovat jenom na události generované z klientské knihovny Azure Identity. Příklad:

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)}"
)

Pro účely ilustrace předpokládejme, že k ověření požadavku na účet úložiště objektů blob se používá formulář DefaultAzureCredential bez parametrů. Aplikace běží v místním vývojovém prostředí a vývojář se ověřil v Azure pomocí Azure CLI. Předpokládejme také, že úroveň protokolování je nastavena na logging.DEBUG. Při spuštění aplikace se ve výstupu zobrazí následující relevantní položky:

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.
VisualStudioCodeCredential.get_token failed: VisualStudioCodeCredential authentication unavailable. No Azure account information found in Visual Studio Code.
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

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

EnvironmentCredential, ManagedIdentityCredential, SharedTokenCacheCredential a VisualStudioCodeCredential se nepodařilo získat přístupový token Microsoft Entra, každý z nich v daném pořadí.
Volání AzureCliCredential.get_token proběhne úspěšně a výstup také indikuje, že DefaultAzureCredential získal token z AzureCliCredential. Poté, co AzureCliCredential uspělo, nebyly zkoušeny žádné další přihlašovací údaje.