Azure Identity-ügyfélkódtár Pythonhoz – 1.14.1-es verzió

  • Cikk

Az Azure Identity-kódtár azure Active Directory-jogkivonat-hitelesítést (Azure AD) biztosít az Azure SDK-ban. Implementációk készletét TokenCredential biztosítja, amelyekkel olyan Azure SDK-ügyfelek hozhatók létre, amelyek támogatják Azure AD jogkivonat-hitelesítést.

Forráskód | Csomag (PyPI) | Csomag (Conda) | API-referenciadokumentáció | Azure AD dokumentációja

Első lépések

A csomag telepítése

Az Azure Identity telepítése pip használatával:

pip install azure-identity

Előfeltételek

  • Azure-előfizetés
  • Python 3.7 vagy a Python 3 legújabb verziója (ez a kódtár nem támogatja az életciklus végét)

Hitelesítés a helyi fejlesztés során

A kód helyi hibakeresése és végrehajtása során a fejlesztők általában a saját fiókjukat használják az Azure-szolgáltatásokba irányuló hívások hitelesítéséhez. Az Azure Identity-kódtár a helyi fejlesztés egyszerűsítése érdekében támogatja a fejlesztői eszközök hitelesítését.

Hitelesítés a Visual Studio Code-on keresztül

A Visual Studio Code-ot használó fejlesztők az Azure Account bővítményt használhatják a szerkesztőn keresztüli hitelesítéshez. Azok az alkalmazások, amelyek ezt a fiókot használják DefaultAzureCredential vagy VisualStudioCodeCredential használhatják, helyi futtatáskor hitelesíthetik a hívásokat az alkalmazásban.

A Visual Studio Code-ban való hitelesítéshez győződjön meg arról, hogy az Azure-fiók bővítmény telepítve van. A telepítés után nyissa meg a parancskatalógust , és futtassa az Azure: Sign In parancsot.

Ismert probléma, amely VisualStudioCodeCredential nem működik a 0.9.11-nél újabb Azure-fiókbővítmény-verziókkal. A probléma hosszú távú megoldása folyamatban van. Addig is fontolja meg a hitelesítést az Azure CLI-vel.

Hitelesítés az Azure CLI-vel

DefaultAzureCredential és AzureCliCredential hitelesítést végezhet az Azure CLI-be bejelentkezett felhasználóként. Az Azure CLI-be való bejelentkezéshez futtassa a parancsot az login. Az alapértelmezett webböngészővel rendelkező rendszereken az Azure CLI elindítja a böngészőt a felhasználó hitelesítéséhez.

Ha nem érhető el alapértelmezett böngésző, az login az eszközkód hitelesítési folyamatát fogja használni. Ez a folyamat manuálisan is kiválasztható a futtatásával az login --use-device-code.

Hitelesítés a Azure Developer CLI

Az IDE-n kívüli kódolást használó fejlesztők az Azure Developer CLI is használhatják a hitelesítéshez. Az vagy a-t használó alkalmazások ezután ezt a DefaultAzureCredentialAzureDeveloperCliCredential fiókot használhatják az alkalmazáson belüli hívások helyi futtatásakor történő hitelesítéséhez.

A Azure Developer CLI való hitelesítéshez a felhasználók futtathatják a parancsotazd auth login. Az alapértelmezett webböngészővel rendelkező rendszeren futó felhasználók esetében a Azure Developer CLI elindítja a böngészőt a felhasználó hitelesítéséhez.

Az alapértelmezett webböngészővel nem rendelkező rendszerek esetében a azd auth login --use-device-code parancs az eszközkód hitelesítési folyamatát fogja használni.

Fő fogalmak

Igazolás

A hitelesítő adatok olyan osztályok, amelyek tartalmazzák vagy lekérhetik a kérések hitelesítéséhez szükséges adatokat a szolgáltatásügyfél számára. A szolgáltatásügyfelek az Azure SDK-ban elfogadják a hitelesítőadat-példányt a létrehozásakor, és ezt a hitelesítő adatot használják a kérések hitelesítéséhez.

Az Azure Identity-kódtár a Azure AD használatával történő OAuth-hitelesítésre összpontosít. Különböző hitelesítőadat-osztályokat kínál, amelyek képesek egy Azure AD hozzáférési jogkivonat beszerzésére. A kódtár hitelesítőadatosztályainak listáját az alábbi szakaszban találja.

AlapértelmezettAzureCredential

DefaultAzureCredential az Azure-ban futtatott legtöbb alkalmazáshoz megfelelő, mivel a gyakori éles hitelesítő adatokat a fejlesztési hitelesítő adatokkal kombinálja. DefaultAzureCredential a következő mechanizmusokon keresztül kísérli meg a hitelesítést, ebben a sorrendben leállítva, ha az egyik sikeres:

Megjegyzés: DefaultAzureCredential célja, hogy leegyszerűsítse a kódtár használatának első lépéseit az ésszerű alapértelmezett viselkedéssel rendelkező gyakori forgatókönyvek kezelésével. Azoknak a fejlesztőknek, akik több vezérlést szeretnének, vagy akiknek a forgatókönyvét nem szolgálják ki az alapértelmezett beállítások, más hitelesítőadat-típusokat kell használniuk.

AlapértelmezettAzureCredential hitelesítési folyamat

  1. Környezet - DefaultAzureCredential megadott fiókadatokat, és hitelesíti azokat.
  2. Számítási feladat identitása – Ha az alkalmazás Azure Kubernetes Service van üzembe helyezve, és engedélyezve van a felügyelt identitás, DefaultAzureCredential azzal hitelesíti magát.
  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, DefaultAzureCredential azzal hitelesíti magát.
  4. Azure CLI – Ha egy felhasználó az Azure CLI-paranccsal az login jelentkezett be, DefaultAzureCredential akkor a felhasználóként fog hitelesítést végezni.
  5. Azure PowerShell – Ha egy felhasználó Azure PowerShell parancsán Connect-AzAccount keresztül jelentkezett be, DefaultAzureCredential akkor a felhasználóként fog hitelesíteni.
  6. Azure Developer CLI – Ha a fejlesztő a Azure Developer CLI azd auth login paranccsal hitelesített, a rendszer ezzel a DefaultAzureCredential fiókkal hitelesíti magát.
  7. Interaktív böngésző – Ha engedélyezve van, DefaultAzureCredential interaktív módon hitelesíti a felhasználót az alapértelmezett böngészőn keresztül. Ez a hitelesítőadat-típus alapértelmezés szerint le van tiltva.

Megjegyzés a következőről: VisualStudioCodeCredential

Egy ismert problémaVisualStudioCodeCredential miatt a rendszer eltávolította a DefaultAzureCredential jogkivonatláncból. Ha a probléma egy későbbi kiadásban megoldódik, a rendszer visszaállítja ezt a módosítást.

Példák

Az alábbi példákat találja:

Hitelesítés a DefaultAzureCredential

A környezet konfigurálásával kapcsolatos további részletek az DefaultAzureCredential osztály referenciadokumentációjában találhatók.

Ez a példa az azure-storage-blob kódtárból való hitelesítését BlobServiceClient mutatja be a használatávalDefaultAzureCredential.

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

default_credential = DefaultAzureCredential()

client = BlobServiceClient(account_url, credential=default_credential)

Interaktív hitelesítés engedélyezése a használatával DefaultAzureCredential

Az interaktív hitelesítés alapértelmezés szerint le van tiltva DefaultAzureCredential , és egy kulcsszóargumentummal engedélyezhető:

DefaultAzureCredential(exclude_interactive_browser_credential=False)

Ha engedélyezve van, a rendszer alapértelmezett webböngészőjének használatával történő interaktív hitelesítésre kerül vissza, DefaultAzureCredential ha nem áll rendelkezésre más hitelesítő adat.

Felhasználó által hozzárendelt felügyelt identitás megadása a következőhöz: DefaultAzureCredential

Számos Azure-gazdagép engedélyezi a felhasználó által hozzárendelt felügyelt identitás hozzárendelését. A felhasználó által hozzárendelt identitás hitelesítésének konfigurálásához DefaultAzureCredential használja a managed_identity_client_id kulcsszóargumentumot:

DefaultAzureCredential(managed_identity_client_id=client_id)

Másik lehetőségként állítsa a környezeti változót AZURE_CLIENT_ID az identitás ügyfél-azonosítójára.

Egyéni hitelesítési folyamat definiálása a használatával ChainedTokenCredential

DefaultAzureCredential Általában ez a leggyorsabb módja az Alkalmazások fejlesztésének az Azure-hoz való fejlesztésének. A speciálisabb forgatókönyvek esetén a ChainedTokenCredential több hitelesítőadat-példányt kapcsol össze, amelyek hitelesítése során egymás után próbálkoznak. Az egyes láncolt hitelesítő adatokat egymás után próbálja ki, amíg egy jogkivonatot nem ad meg, vagy egy hiba miatt nem sikerül a hitelesítés.

Az alábbi példa bemutatja egy hitelesítő adat létrehozását, amely először megkísérel hitelesíteni a felügyelt identitással. Ha egy felügyelt identitás nem érhető el, a hitelesítő adatok visszaállnak az Azure CLI-vel történő hitelesítésre. Ez a példa az EventHubProducerClientazure-eventhub ügyfélkódtárból származik.

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)

Aszinkron hitelesítő adatok

Ez a kódtár aszinkron API-k készletét tartalmazza. Az azure.identity.aio aszinkron hitelesítő adatainak használatához először telepítenie kell egy aszinkron átvitelt, például az aiohttp-t. További információt az Azure-core dokumentációjában talál.

Az aszinkron hitelesítő adatokat be kell zárni, ha már nincs rájuk szükség. Minden aszinkron hitelesítő adat egy aszinkron környezetkezelő, és definiál egy aszinkron close metódust. Például:

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

Ez a példa az azure-keyvault-secrets aszinkron SecretClient hitelesítését mutatja be aszinkron hitelesítő adatokkal.

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)

Felügyelt identitás támogatása

A felügyelt identitás hitelesítése a következő Azure-szolgáltatások vagy közvetlenül a használatával DefaultAzureCredentialManagedIdentityCredential támogatott:

Példák

Hitelesítés felhasználó által hozzárendelt felügyelt identitással

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)

Hitelesítés rendszer által hozzárendelt felügyelt identitással

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

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

Felhő konfigurálása

Az azure-beli nyilvános felhő Azure AD végpontjának hitelesítéséhez használt hitelesítő adatok alapértelmezés szerint. Más felhőkben, például Azure Government vagy magánfelhőben lévő erőforrások eléréséhez konfigurálja a hitelesítő adatokat az authority argumentummal. Az AzureAuthorityHosts a jól ismert felhők szolgáltatóit határozza meg:

from azure.identity import AzureAuthorityHosts

DefaultAzureCredential(authority=AzureAuthorityHosts.AZURE_GOVERNMENT)

Ha a felhő szolgáltatója nem szerepel a AzureAuthorityHostslistában, explicit módon megadhatja annak URL-címét:

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

Az argumentum megadása authority helyett a környezeti változót AZURE_AUTHORITY_HOST a felhő szolgáltatójának URL-címére is beállíthatja. Ez a módszer akkor hasznos, ha több hitelesítő adatot konfigurál egy felhőben való hitelesítéshez:

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

Nem minden hitelesítő adat igényli ezt a konfigurációt. Az olyan hitelesítő adatok, amelyek egy fejlesztőeszközön (például AzureCliCredential) keresztül hitelesíthetők, az eszköz konfigurációját használják. Hasonlóképpen elfogad egy authority argumentumot, VisualStudioCodeCredential de alapértelmezés szerint a VS Code "Azure: Cloud" beállításának megfelelő szolgáltató.

Hitelesítő adatok osztályai

Az Azure által üzemeltetett alkalmazások hitelesítése

Hitelesítő adat Használat
DefaultAzureCredential Egyszerűsített hitelesítési élményt nyújt az Azure-ban futó alkalmazások fejlesztésének gyors megkezdéséhez.
ChainedTokenCredential Lehetővé teszi, hogy a felhasználók egyéni hitelesítési folyamatokat definiáljanak, amelyek több hitelesítő adatot írnak.
EnvironmentCredential Egy szolgáltatásnevet vagy felhasználót hitelesít a környezeti változókban megadott hitelesítő adatokon keresztül.
ManagedIdentityCredential Hitelesíti egy Azure-erőforrás felügyelt identitását.
WorkloadIdentityCredential Támogatja Azure AD számítási feladatok identitását a Kubernetesben.

Szolgáltatásnevek hitelesítése

Hitelesítő adat Használat Referencia
CertificateCredential Tanúsítvány használatával hitelesíti a szolgáltatásnevet. Szolgáltatásnév hitelesítése
ClientAssertionCredential Hitelesíti a szolgáltatásnevet egy aláírt ügyfél-helyességi feltétellel.
ClientSecretCredential Titkos kóddal hitelesíti a szolgáltatásnevet. Szolgáltatásnév hitelesítése

Felhasználók hitelesítése

Hitelesítő adat Használat Referencia
AuthorizationCodeCredential Hitelesíti a felhasználót egy korábban beszerzett engedélyezési kóddal. OAuth2 hitelesítési kód
DeviceCodeCredential Interaktívan hitelesíti a felhasználókat korlátozott felhasználói felülettel rendelkező eszközökön. Eszközkód hitelesítése
InteractiveBrowserCredential Interaktívan hitelesíti a felhasználót az alapértelmezett rendszerböngészővel. OAuth2 hitelesítési kód
OnBehalfOfCredential Propagálja a delegált felhasználói identitást és engedélyeket a kérelemláncon keresztül. A hitelesítés nevében
UsernamePasswordCredential Felhasználó hitelesítése felhasználónévvel és jelszóval (nem támogatja a többtényezős hitelesítést). Felhasználónév és jelszó hitelesítése

Hitelesítés fejlesztői eszközökkel

Hitelesítő adat Használat Referencia
AzureCliCredential Fejlesztési környezetben hitelesíti magát az Azure CLI-vel. Azure CLI-hitelesítés
AzureDeveloperCliCredential Fejlesztési környezetben hitelesíti magát a Azure Developer CLI. Azure Developer CLI referencia
AzurePowerShellCredential Fejlesztési környezetben hitelesíti magát a Azure PowerShell. Azure PowerShell hitelesítés
VisualStudioCodeCredential Hitelesítés a Visual Studio Code Azure-fiókbővítménybe bejelentkezett felhasználóként. VS Code Azure-fiókbővítmény

Környezeti változók

AlapértelmezettAzureCredential és EnvironmentCredential környezeti változókkal konfigurálható. Minden hitelesítési típushoz szükség van bizonyos változók értékeire:

Szolgáltatásnév titkos kóddal

Változó neve Érték
AZURE_CLIENT_ID Egy Azure AD-alkalmazás azonosítója
AZURE_TENANT_ID Az alkalmazás Azure AD bérlőjének azonosítója
AZURE_CLIENT_SECRET az alkalmazás egyik titkos ügyfélkulcsa

Szolgáltatásnév tanúsítvánnyal

Változó neve Érték
AZURE_CLIENT_ID Egy Azure AD-alkalmazás azonosítója
AZURE_TENANT_ID Az alkalmazás Azure AD bérlőjének azonosítója
AZURE_CLIENT_CERTIFICATE_PATH PEM- vagy PKCS12-tanúsítványfájl elérési útja, beleértve a titkos kulcsot
AZURE_CLIENT_CERTIFICATE_PASSWORD a tanúsítványfájl jelszava, ha van ilyen

Felhasználónév és jelszó

Változó neve Érték
AZURE_CLIENT_ID Egy Azure AD-alkalmazás azonosítója
AZURE_USERNAME felhasználónév (általában egy e-mail-cím)
AZURE_PASSWORD a felhasználó jelszava

A rendszer a fenti sorrendben kísérli meg a konfigurációt. Ha például egy titkos ügyfélkód és egy tanúsítvány értékei is jelen vannak, a rendszer az ügyfélkulcsot fogja használni.

Jogkivonatok gyorsítótárazása

A jogkivonatok gyorsítótárazása az Azure Identity-kódtár által biztosított szolgáltatás, amely lehetővé teszi az alkalmazások számára a következőket:

  • Gyorsítótár-jogkivonatok a memóriában (alapértelmezett) vagy a lemezen (opt-in).
  • A rugalmasság és a teljesítmény javítása.
  • Csökkentse a hozzáférési jogkivonatok beszerzéséhez Azure AD küldött kérések számát.

Az Azure Identity-kódtár memórián belüli és állandó lemez-gyorsítótárazást is kínál. További részletekért tekintse meg a jogkivonatok gyorsítótárazási dokumentációját.

Hibaelhárítás

A különböző hibaforgatókönyvek diagnosztizálásával kapcsolatos részletekért tekintse meg a hibaelhárítási útmutatót .

Hibakezelés

A hitelesítő adatok akkor keletkeznek CredentialUnavailableError , ha nem próbálják meg a hitelesítést, mert nem rendelkeznek a szükséges adatokkal vagy állapotokkal. Az EnvironmentCredential például akkor emeli ki ezt a kivételt, ha nem teljes.

A hitelesítő adatok akkor keletkeznek azure.core.exceptions.ClientAuthenticationError , ha nem tudnak hitelesítést végezni. ClientAuthenticationError attribútummal message rendelkezik, amely leírja, hogy miért hiúsult meg a hitelesítés. A vagy ChainedTokenCredentialáltal DefaultAzureCredential kiváltott üzenet hibaüzeneteket gyűjt a lánc egyes hitelesítő adataiból.

Az adott Azure AD hibák kezelésével kapcsolatos további információkért tekintse meg az Azure AD hibakód dokumentációját.

Naplózás

Ez a kódtár a szabványos naplózási kódtárat használja a naplózáshoz. A hitelesítő adatok alapvető információkat naplóznak, beleértve a HTTP-munkameneteket (URL-címeket, fejléceket stb.) info szinten. Ezek a naplóbejegyzések nem tartalmaznak hitelesítési titkos kódokat.

A részletes HIBAKERESÉSi szint naplózása, beleértve a kérelem-/választörzseket és a fejlécértékeket, alapértelmezés szerint nincs engedélyezve. Az argumentummal logging_enable engedélyezhető. Például:

credential = DefaultAzureCredential(logging_enable=True)

FIGYELEM: A hitelesítő adatok hibakeresési szintű naplói bizalmas információkat tartalmaznak. Ezeket a naplókat védeni kell a fiókbiztonság veszélyeztetésének elkerülése érdekében.

Következő lépések

Ügyfélkódtár támogatása

Az Azure SDK kiadási oldalán felsorolt ügyfél- és felügyeleti kódtárak, amelyek támogatják Azure AD hitelesítést, fogadják el a hitelesítő adatokat ebből a kódtárból. A kódtárak használatáról a kiadási oldalról csatolt dokumentációban talál további információt.

Ismert problémák

Ez a kódtár nem támogatja Azure AD B2C-t.

Egyéb nyitott problémák esetén tekintse meg a könyvtár GitHub-adattárát.

Visszajelzés küldése

Ha hibákat tapasztal, vagy javaslatai vannak, nyisson meg egy problémát.

Közreműködés

A projektben szívesen fogadjuk a hozzájárulásokat és a javaslatokat. A legtöbb hozzájáruláshoz el kell fogadnia egy Közreműködői licencszerződést (CLA-t), amelyben kijelenti, hogy jogosult arra, hogy ránk ruházza hozzájárulása felhasználási jogát, és ezt ténylegesen meg is teszi. További részletekért lásd: https://cla.microsoft.com.

A lekéréses kérelmek elküldésekor egy CLA-robot automatikusan meghatározza, hogy kell-e biztosítania CLA-t, és megfelelően kitölti a lekéréses kérelmet (például címke, megjegyzés). Egyszerűen csak kövesse a robot által megadott utasításokat. Ezt csak egyszer kell elvégeznie az összes adattárban a CLA használatával.

A projekt a Microsoft nyílt forráskódú projekteket szabályozó etikai kódexe, a Microsoft Open Source Code of Conduct hatálya alá esik. További információkért keresse fel a Viselkedési szabályzattal kapcsolatos gyakori kérdések oldalát, illetve küldje el kérdéseit vagy észrevételeit a következő címre: opencode@microsoft.com.

Megjelenések