Klientská knihovna Azure Identity pro Python – verze 1.14.1

Knihovna identit Azure poskytuje podporu ověřování tokenů Azure Active Directory (Azure AD) napříč sadou Azure SDK. Poskytuje sadu TokenCredential implementací, které je možné použít k vytváření klientů sady Azure SDK, kteří podporují ověřování tokenů Azure AD.

Zdrojový kód | Balíček (PyPI) | Balíček (Conda) | Referenční dokumentace k | rozhraní APIAzure AD dokumentace

Začínáme

Instalace balíčku

Instalace identity Azure pomocí pipu:

pip install azure-identity

Požadavky

• Předplatné Azure
• Python 3.7 nebo nedávná verze Pythonu 3 (tato knihovna nepodporuje verze s ukončenou životností)

Ověřování během místního vývoje

Při místním ladění a spouštění kódu je typické, že vývojáři používají k ověřování volání služeb Azure vlastní účty. Knihovna identit Azure podporuje ověřování prostřednictvím vývojářských nástrojů, aby se zjednodušil místní vývoj.

Ověřování prostřednictvím editoru Visual Studio Code

Vývojáři používající Visual Studio Code můžou k ověřování prostřednictvím editoru použít rozšíření účtu Azure . Aplikace používající DefaultAzureCredential nebo VisualStudioCodeCredential pak můžou tento účet použít k ověřování volání ve své aplikaci při místním spuštění.

Pokud chcete provést ověření v editoru Visual Studio Code, ujistěte se, že je nainstalované rozšíření účtu Azure. Po instalaci otevřete paletu příkazů a spusťte příkaz Azure: Přihlásit se .

Jedná se o známý problém , který VisualStudioCodeCredential nefunguje s verzemi rozšíření účtu Azure novějšími než 0.9.11. Probíhá dlouhodobé řešení tohoto problému. Mezitím zvažte ověřování přes Azure CLI.

Ověřování pomocí Azure CLI

DefaultAzureCredential a AzureCliCredential může se ověřit jako uživatel přihlášený k Azure CLI. Pokud se chcete přihlásit k Azure CLI, spusťte příkaz az login. V systému s výchozím webovým prohlížečem azure CLI spustí prohlížeč pro ověření uživatele.

Pokud není k dispozici žádný výchozí prohlížeč, az login použije tok ověřování kódu zařízení. Tento tok je také možné vybrat ručně spuštěním příkazu az login --use-device-code.

Ověřování prostřednictvím Azure Developer CLI

Vývojáři, kteří kódují mimo integrované vývojové prostředí, můžou k ověření použít také Azure Developer CLI. Aplikace používající DefaultAzureCredential nebo AzureDeveloperCliCredential pak můžou tento účet použít k ověřování volání ve své aplikaci při místním spuštění.

Pokud se uživatelé chtějí ověřit pomocí Azure Developer CLI, můžou spustit příkaz azd auth login. Pro uživatele spuštěné v systému s výchozím webovým prohlížečem spustí Azure Developer CLI prohlížeč pro ověření uživatele.

V systémech bez výchozího webového azd auth login --use-device-code prohlížeče použije příkaz tok ověřování kódu zařízení.

Klíčové koncepty

Reference

Přihlašovací údaje jsou třída, která obsahuje nebo může získat data potřebná pro klienta služby k ověřování požadavků. Klienti služeb napříč sadou Azure SDK při vytváření přijímají instanci přihlašovacích údajů a používají tyto přihlašovací údaje k ověřování požadavků.

Knihovna identit Azure se zaměřuje na ověřování OAuth pomocí Azure AD. Nabízí různé třídy přihlašovacích údajů, které jsou schopné získat přístupový token Azure AD. Seznam tříd této knihovny najdete níže v části Třídy pověření Třídy přihlašovacích údajů.

VýchozíAzureCredential

DefaultAzureCredential je vhodný pro většinu aplikací, které poběží v Azure, protože kombinuje běžné produkční přihlašovací údaje s přihlašovacími údaji pro vývoj. DefaultAzureCredential se pokusí provést ověření pomocí následujících mechanismů v tomto pořadí a zastaví se, jakmile bude úspěšný:

Poznámka: DefaultAzureCredential Má zjednodušit zahájení práce s knihovnou tím, že zpracovává běžné scénáře s přiměřeným výchozím chováním. Vývojáři, kteří chtějí mít větší kontrolu nebo jejichž scénář není obsluhován výchozím nastavením, by měli používat jiné typy přihlašovacích údajů.

1. Prostředí - DefaultAzureCredential přečte informace o účtu zadané prostřednictvím a použije je k ověření.
2. Identita úlohy – pokud je aplikace nasazená do Azure Kubernetes Service s povolenou spravovanou identitou, DefaultAzureCredential ověří se pomocí ní.
3. Spravovaná identita – pokud je aplikace nasazená na hostitele Azure s povolenou spravovanou identitou, DefaultAzureCredential ověří se pomocí ní.
4. Azure CLI – Pokud se uživatel přihlásil pomocí příkazu Azure CLI az login , DefaultAzureCredential ověří se jako tento uživatel.
5. Azure PowerShell – pokud se uživatel přihlásil pomocí příkazu Azure PowerShellConnect-AzAccount, DefaultAzureCredential ověří se jako tento uživatel.
6. Azure Developer CLI – Pokud se vývojář ověřil pomocí příkazu Azure Developer CLIazd auth login, ověří se DefaultAzureCredential pomocí daného účtu.
7. Interaktivní prohlížeč – pokud je povoleno, DefaultAzureCredential bude interaktivně ověřovat uživatele prostřednictvím výchozího prohlížeče. Tento typ přihlašovacích údajů je ve výchozím nastavení zakázaný.

Poznámka k tématu VisualStudioCodeCredential

Kvůli známému problémuVisualStudioCodeCredential byl odebrán z řetězu tokenůDefaultAzureCredential. Jakmile se problém vyřeší v budoucí verzi, bude tato změna vrácena.

Příklady

Níže jsou uvedené následující příklady:

• Ověření pomocí DefaultAzureCredential
• Definování vlastního toku ověřování pomocí ChainedTokenCredential
• Asynchronní přihlašovací údaje

Ověření pomocí DefaultAzureCredential

Další podrobnosti o konfiguraci prostředí pro použití DefaultAzureCredential najdete v referenční dokumentaci ke třídě.

Tento příklad ukazuje ověření BlobServiceClient z knihovny azure-storage-blob pomocí DefaultAzureCredential.

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

default_credential = DefaultAzureCredential()

client = BlobServiceClient(account_url, credential=default_credential)

Povolení interaktivního ověřování pomocí DefaultAzureCredential

Interaktivní ověřování je ve výchozím nastavení zakázané a je možné ho DefaultAzureCredential povolit pomocí argumentu klíčového slova:

DefaultAzureCredential(exclude_interactive_browser_credential=False)

Pokud je tato možnost povolená, DefaultAzureCredential vrátí se zpět k interaktivnímu ověřování prostřednictvím výchozího webového prohlížeče systému, pokud nejsou k dispozici žádné další přihlašovací údaje.

Zadejte spravovanou identitu přiřazenou uživatelem pro DefaultAzureCredential

Mnoho hostitelů Azure umožňuje přiřazení spravované identity přiřazené uživatelem. Pokud chcete nakonfigurovat DefaultAzureCredential ověřování identity přiřazené uživatelem, použijte argument klíčového managed_identity_client_id slova:

DefaultAzureCredential(managed_identity_client_id=client_id)

Případně nastavte proměnnou AZURE_CLIENT_ID prostředí na ID klienta identity.

Definování vlastního toku ověřování pomocí ChainedTokenCredential

DefaultAzureCredential je obecně nejrychlejší způsob, jak začít s vývojem aplikací pro Azure. Pro pokročilejší scénáře chainedTokenCredential propojí více instancí přihlašovacích údajů, které se mají vyzkoušet postupně při ověřování. Vyzkouší jednotlivé zřetězený přihlašovací údaje, dokud jeden z nich nezadá token nebo se nepovede ověřit kvůli chybě.

Následující příklad ukazuje vytvoření přihlašovacích údajů, které se nejprve pokusí ověřit pomocí spravované identity. Pokud spravovaná identita není dostupná, přihlašovací údaje se vrátí k ověřování prostřednictvím Azure CLI. V tomto příkladu se EventHubProducerClient používá klientská knihovna azure-eventhub .

from azure.eventhub import EventHubProducerClient
from azure.identity import AzureCliCredential, ChainedTokenCredential, ManagedIdentityCredential

managed_identity = ManagedIdentityCredential()
azure_cli = AzureCliCredential()
credential_chain = ChainedTokenCredential(managed_identity, azure_cli)

client = EventHubProducerClient(namespace, eventhub_name, credential_chain)

Asynchronní přihlašovací údaje

Tato knihovna obsahuje sadu asynchronních rozhraní API. Pokud chcete používat asynchronní přihlašovací údaje v azure.identity.aio, musíte nejprve nainstalovat asynchronní přenos, například aiohttp. Další informace najdete v dokumentaci k azure-core.

Asynchronní přihlašovací údaje by se měly zavřít, když už nejsou potřeba. Každý asynchronní přihlašovací údaj je asynchronní kontextový správce a definuje asynchronní close metodu. Příklad:

from azure.identity.aio import DefaultAzureCredential

# call close when the credential is no longer needed
credential = DefaultAzureCredential()
...
await credential.close()

# alternatively, use the credential as an async context manager
credential = DefaultAzureCredential()
async with credential:
  ...

Tento příklad ukazuje ověřování asynchronního SecretClient z azure-keyvault-secrets pomocí asynchronních přihlašovacích údajů.

from azure.identity.aio import DefaultAzureCredential
from azure.keyvault.secrets.aio import SecretClient

default_credential = DefaultAzureCredential()
client = SecretClient("https://my-vault.vault.azure.net", default_credential)

Podpora spravovaných identit

Ověřování spravované identity se podporuje prostřednictvím DefaultAzureCredentialManagedIdentityCredential nebo přímo pro následující služby Azure:

• Azure App Service a Azure Functions
• Azure Arc
• Azure Cloud Shell
• Azure Kubernetes Service
• Azure Service Fabric
• Azure Virtual Machines
• Azure Virtual Machines Scale Sets

Příklady

Ověřování pomocí spravované identity přiřazené uživatelem

from azure.identity import ManagedIdentityCredential
from azure.keyvault.secrets import SecretClient

credential = ManagedIdentityCredential(client_id=managed_identity_client_id)
client = SecretClient("https://my-vault.vault.azure.net", credential)

Ověřování pomocí spravované identity přiřazené systémem

from azure.identity import ManagedIdentityCredential
from azure.keyvault.secrets import SecretClient

credential = ManagedIdentityCredential()
client = SecretClient("https://my-vault.vault.azure.net", credential)

Konfigurace cloudu

Přihlašovací údaje se ve výchozím nastavení ověřují v koncovém bodu Azure AD pro veřejný cloud Azure. Pokud chcete získat přístup k prostředkům v jiných cloudech, jako je Azure Government nebo privátní cloud, nakonfigurujte přihlašovací údaje pomocí argumentu authority . AzureAuthorityHosts definuje autority pro dobře známé cloudy:

from azure.identity import AzureAuthorityHosts

DefaultAzureCredential(authority=AzureAuthorityHosts.AZURE_GOVERNMENT)

Pokud autorita pro váš cloud není uvedená v AzureAuthorityHosts, můžete explicitně zadat její adresu URL:

DefaultAzureCredential(authority="https://login.partner.microsoftonline.cn")

Jako alternativu k zadání argumentu authority můžete také nastavit AZURE_AUTHORITY_HOST proměnnou prostředí na adresu URL autority vašeho cloudu. Tento přístup je užitečný při konfiguraci více přihlašovacích údajů pro ověřování ve stejném cloudu:

AZURE_AUTHORITY_HOST=https://login.partner.microsoftonline.cn

Tuto konfiguraci nevyžadují všechny přihlašovací údaje. Přihlašovací údaje, které se ověřují prostřednictvím vývojového nástroje, jako AzureCliCredentialje , používají konfiguraci tohoto nástroje. Podobně akceptuje authority argument, VisualStudioCodeCredential ale ve výchozím nastavení se nastaví autorita odpovídající nastavení Azure: Cloud ve VS Code.

Třídy přihlašovacích údajů

Ověřování aplikací hostovaných v Azure

Přihlašovací údaj	Využití
DefaultAzureCredential	Poskytuje zjednodušené prostředí ověřování pro rychlé zahájení vývoje aplikací spuštěných v Azure.
ChainedTokenCredential	Umožňuje uživatelům definovat vlastní toky ověřování, které sestaví více přihlašovacích údajů.
EnvironmentCredential	Ověřuje instanční objekt nebo uživatele prostřednictvím informací o přihlašovacích údajích zadaných v proměnných prostředí.
ManagedIdentityCredential	Ověřuje spravovanou identitu prostředku Azure.
WorkloadIdentityCredential	Podporuje Azure AD identitu úloh v Kubernetes.

Ověřování instančních objektů

Přihlašovací údaj	Využití	Reference
CertificateCredential	Ověřuje instanční objekt pomocí certifikátu.	Ověřování instančního objektu
ClientAssertionCredential	Ověřuje instanční objekt pomocí podepsaného kontrolního výrazu klienta.
ClientSecretCredential	Ověřuje instanční objekt pomocí tajného kódu.	Ověřování instančního objektu

Ověřování uživatelů

Přihlašovací údaj	Využití	Reference
AuthorizationCodeCredential	Ověří uživatele pomocí dříve získaného autorizačního kódu.	Ověřovací kód OAuth2
DeviceCodeCredential	Interaktivně ověřuje uživatele na zařízeních s omezeným uživatelským rozhraním.	Ověřování kódu zařízení
InteractiveBrowserCredential	Interaktivně ověřuje uživatele pomocí výchozího systémového prohlížeče.	Ověřovací kód OAuth2
OnBehalfOfCredential	Rozšíří delegovanou identitu uživatele a oprávnění prostřednictvím řetězu požadavků.	Ověřování on-behalf-of
UsernamePasswordCredential	Ověřuje uživatele pomocí uživatelského jména a hesla (nepodporuje vícefaktorové ověřování).	Ověřování pomocí uživatelského jména a hesla

Ověřování prostřednictvím vývojových nástrojů

Přihlašovací údaj	Využití	Reference
AzureCliCredential	Ověřuje se ve vývojovém prostředí pomocí Azure CLI.	Ověřování Azure CLI
AzureDeveloperCliCredential	Ověřuje se ve vývojovém prostředí pomocí Azure Developer CLI.	Referenční informace k Azure Developer CLI
AzurePowerShellCredential	Ověřuje se ve vývojovém prostředí pomocí Azure PowerShell.	Azure PowerShell ověřování
VisualStudioCodeCredential	Ověří se jako uživatel přihlášený k rozšíření Azure Account pro Visual Studio Code.	Rozšíření VS Code pro účet Azure

Proměnné prostředí

DefaultAzureCredential a EnvironmentCredential je možné nakonfigurovat s proměnnými prostředí. Každý typ ověřování vyžaduje hodnoty pro konkrétní proměnné:

Instanční objekt s tajným kódem

Název proměnné	Hodnota
AZURE_CLIENT_ID	ID aplikace Azure AD
AZURE_TENANT_ID	ID tenanta Azure AD aplikace
AZURE_CLIENT_SECRET	jeden z tajných klíčů klienta aplikace

Instanční objekt s certifikátem

Název proměnné	Hodnota
AZURE_CLIENT_ID	ID aplikace Azure AD
AZURE_TENANT_ID	ID tenanta Azure AD aplikace
AZURE_CLIENT_CERTIFICATE_PATH	cesta k souboru certifikátu PEM nebo PKCS12 včetně privátního klíče
AZURE_CLIENT_CERTIFICATE_PASSWORD	heslo souboru certifikátu, pokud existuje

Uživatelské jméno a heslo

Název proměnné	Hodnota
AZURE_CLIENT_ID	ID aplikace Azure AD
AZURE_USERNAME	uživatelské jméno (obvykle e-mailová adresa)
AZURE_PASSWORD	heslo daného uživatele

Pokus o konfiguraci se provede ve výše uvedeném pořadí. Pokud jsou například k dispozici hodnoty tajného klíče klienta i certifikátu, použije se tajný klíč klienta.

Ukládání tokenů do mezipaměti

Ukládání tokenů do mezipaměti je funkce, kterou poskytuje knihovna identit Azure, která aplikacím umožňuje:

• Tokeny mezipaměti v paměti (výchozí) nebo na disku (výslovný souhlas).
• Zvyšte odolnost a výkon.
• Snižte počet požadavků na Azure AD za účelem získání přístupových tokenů.

Knihovna identit Azure nabízí ukládání do mezipaměti v paměti i trvalé ukládání do mezipaměti na disku. Další podrobnosti najdete v dokumentaci k ukládání tokenů do mezipaměti.

Poradce při potížích

Podrobnosti o tom, jak diagnostikovat různé scénáře selhání, najdete v průvodci odstraňováním potíží.

Zpracování chyb

Přihlašovací údaje se zobrazí CredentialUnavailableError , když se nemůžou pokusit o ověření, protože nemají požadovaná data nebo stav. Například EnvironmentCredential vyvolá tuto výjimku, když není kompletní.

Přihlašovací údaje se zobrazí azure.core.exceptions.ClientAuthenticationError , když se jim nepodaří ověřit. ClientAuthenticationErrormessage má atribut, který popisuje, proč ověřování selhalo. Při vyvolání nástrojem DefaultAzureCredential nebo ChainedTokenCredentialtato zpráva shromažďuje chybové zprávy z jednotlivých přihlašovacích údajů v řetězci.

Další informace o zpracování konkrétních chyb Azure AD najdete v dokumentaci ke kódu chyb Azure AD.

protokolování

Tato knihovna používá k protokolování standardní knihovnu protokolování . Přihlašovací údaje protokolují základní informace, včetně relací HTTP (adres URL, hlaviček atd.) na úrovni INFO. Tyto položky protokolu neobsahují tajné kódy ověřování.

Podrobné protokolování úrovně LADĚNÍ, včetně těl požadavků/odpovědí a hodnot hlaviček, není ve výchozím nastavení povolené. Dá se povolit pomocí argumentu logging_enable . Příklad:

credential = DefaultAzureCredential(logging_enable=True)

UPOZORNĚNÍ: Protokoly na úrovni ladění z přihlašovacích údajů obsahují citlivé informace. Tyto protokoly musí být chráněné, aby nedošlo k ohrožení zabezpečení účtu.

Další kroky

Podpora klientské knihovny

Klientské knihovny a knihovny pro správu uvedené na stránce verze sady Azure SDK, které podporují ověřování Azure AD přijímat přihlašovací údaje z této knihovny. Další informace o používání těchto knihoven najdete v jejich dokumentaci, která je propojená na stránce vydané verze.

Známé problémy

Tato knihovna nepodporuje Azure AD B2C.

Další otevřené problémy najdete v úložišti GitHubu v knihovně.

Poskytnutí zpětné vazby

Pokud narazíte na chyby nebo máte návrhy, otevřete problém.

Přispívání

Tento projekt vítá příspěvky a návrhy. Většina příspěvků vyžaduje souhlas s licenční smlouvou s přispěvatelem (CLA), která stanoví, že máte právo udělit nám práva k používání vašeho příspěvku a skutečně tak činíte. Podrobnosti najdete tady: https://cla.microsoft.com

Při odesílání žádosti o přijetí změn robot CLA automaticky určí, jestli je potřeba poskytnout smlouvu CLA, a příslušným způsobem žádost o přijetí změn upraví (např. přidáním jmenovky nebo komentáře). Stačí postupovat podle pokynů robota. Pomocí našeho cla to budete muset udělat ve všech úložišťch jenom jednou.

Tento projekt přijal pravidla chování pro Microsoft Open Source. Další informace najdete v nejčastějších dotazech k pravidlům chování. V případě jakýchkoli dotazů nebo připomínek kontaktujte opencode@microsoft.com.