Biblioteka klienta tożsamości platformy Azure dla języka Python — wersja 1.14.1

Biblioteka tożsamości platformy Azure zapewnia obsługę uwierzytelniania tokenów usługi Azure Active Directory (Azure AD) w zestawie Azure SDK. Udostępnia zestaw TokenCredential implementacji, których można użyć do konstruowania klientów zestawu Azure SDK, którzy obsługują uwierzytelnianie tokenów Azure AD.

Kod | źródłowyPakiet (PyPI) | Pakiet (Conda) | Dokumentacja referencyjna interfejsu | APIdokumentacja Azure AD

Wprowadzenie

Instalowanie pakietu

Instalowanie tożsamości platformy Azure za pomocą narzędzia pip:

pip install azure-identity

Wymagania wstępne

• Subskrypcja platformy Azure
• Środowisko Python 3.7 lub najnowsza wersja języka Python 3 (ta biblioteka nie obsługuje wersji end-of-life)

Uwierzytelnianie podczas programowania lokalnego

Podczas lokalnego debugowania i wykonywania kodu deweloperzy zwykle używają własnych kont do uwierzytelniania wywołań do usług platformy Azure. Biblioteka tożsamości platformy Azure obsługuje uwierzytelnianie za pomocą narzędzi deweloperskich w celu uproszczenia programowania lokalnego.

Uwierzytelnianie za pośrednictwem Visual Studio Code

Deweloperzy korzystający z Visual Studio Code mogą używać rozszerzenia konta platformy Azure do uwierzytelniania za pośrednictwem edytora. Aplikacje korzystające z DefaultAzureCredential tego konta lub VisualStudioCodeCredential mogą następnie używać tego konta do uwierzytelniania wywołań w aplikacji podczas uruchamiania lokalnego.

Aby uwierzytelnić się w Visual Studio Code, upewnij się, że rozszerzenie konta platformy Azure jest zainstalowane. Po zainstalowaniu otwórz paletę poleceń i uruchom polecenie Azure: Sign In .

Jest to znany problem , który VisualStudioCodeCredential nie działa z wersjami rozszerzenia konta platformy Azure nowszymi niż 0.9.11. Długoterminowe rozwiązanie tego problemu jest w toku. W międzyczasie rozważ uwierzytelnienie za pośrednictwem interfejsu wiersza polecenia platformy Azure.

Uwierzytelnianie za pośrednictwem interfejsu wiersza polecenia platformy Azure

DefaultAzureCredential i AzureCliCredential może uwierzytelniać się jako użytkownik zalogowany w interfejsie wiersza polecenia platformy Azure. Aby zalogować się do interfejsu wiersza polecenia platformy Azure, uruchom polecenie az login. W systemie z domyślną przeglądarką internetową interfejs wiersza polecenia platformy Azure uruchomi przeglądarkę w celu uwierzytelnienia użytkownika.

Jeśli domyślna przeglądarka nie jest dostępna, az login użyje przepływu uwierzytelniania kodu urządzenia. Ten przepływ można również wybrać ręcznie, uruchamiając polecenie az login --use-device-code.

Uwierzytelnianie za pośrednictwem Azure Developer CLI

Deweloperzy kodujący poza środowiskiem IDE mogą również używać Azure Developer CLI do uwierzytelniania. Aplikacje korzystające DefaultAzureCredential z elementu lub AzureDeveloperCliCredential mogą następnie używać tego konta do uwierzytelniania wywołań w aplikacji podczas uruchamiania lokalnego.

Aby przeprowadzić uwierzytelnianie za pomocą Azure Developer CLI, użytkownicy mogą uruchomić polecenie azd auth login. W przypadku użytkowników działających w systemie z domyślną przeglądarką internetową Azure Developer CLI uruchomi przeglądarkę w celu uwierzytelnienia użytkownika.

W przypadku systemów bez domyślnej przeglądarki azd auth login --use-device-code internetowej polecenie użyje przepływu uwierzytelniania kodu urządzenia.

Kluczowe pojęcia

Referencja

Poświadczenie to klasa, która zawiera lub może uzyskać dane wymagane do uwierzytelnienia żądań przez klienta usługi. Klienci usług w zestawie Azure SDK akceptują wystąpienie poświadczeń podczas konstruowania i używają tego poświadczenia do uwierzytelniania żądań.

Biblioteka tożsamości platformy Azure koncentruje się na uwierzytelnianiu OAuth przy użyciu Azure AD. Oferuje różne klasy poświadczeń umożliwiające uzyskanie Azure AD tokenu dostępu. Zapoznaj się z sekcją poniżej, aby uzyskać listę klas poświadczeń tej biblioteki.

DefaultAzureCredential

DefaultAzureCredential jest odpowiednia dla większości aplikacji, które będą uruchamiane na platformie Azure, ponieważ łączy typowe poświadczenia produkcyjne z poświadczeniami programowania. DefaultAzureCredential próbuje uwierzytelnić się za pomocą następujących mechanizmów, w tej kolejności, zatrzymując się po pomyślnym zakończeniu:

Uwaga: DefaultAzureCredential ma na celu uproszczenie rozpoczynania pracy z biblioteką przez obsługę typowych scenariuszy z rozsądnymi zachowaniami domyślnymi. Deweloperzy, którzy chcą mieć większą kontrolę lub których scenariusz nie jest obsługiwany przez ustawienia domyślne, powinni używać innych typów poświadczeń.

1. Środowiska - DefaultAzureCredential Program odczytuje informacje o koncie określone za pośrednictwem i używa ich do uwierzytelniania.
2. Tożsamość obciążenia — jeśli aplikacja zostanie wdrożona w Azure Kubernetes Service z włączoną tożsamością zarządzaną, DefaultAzureCredential uwierzytelni ją.
3. Tożsamość zarządzana — jeśli aplikacja zostanie wdrożona na hoście platformy Azure z włączoną tożsamością zarządzaną, DefaultAzureCredential uwierzytelni ją.
4. Interfejs wiersza polecenia platformy Azure — jeśli użytkownik zalogował się za pomocą polecenia interfejsu wiersza polecenia az login platformy Azure, DefaultAzureCredential zostanie uwierzytelniony jako ten użytkownik.
5. Azure PowerShell — jeśli użytkownik zalogował się za pomocą polecenia Azure PowerShellConnect-AzAccount, DefaultAzureCredential zostanie uwierzytelniony jako ten użytkownik.
6. Azure Developer CLI — jeśli deweloper uwierzytelnił się za pomocą polecenia Azure Developer CLIazd auth login, DefaultAzureCredential zostanie uwierzytelniony przy użyciu tego konta.
7. Interaktywna przeglądarka — jeśli ta opcja jest włączona, DefaultAzureCredential interakcyjne uwierzytelnia użytkownika za pośrednictwem domyślnej przeglądarki. Ten typ poświadczeń jest domyślnie wyłączony.

Uwaga dotycząca VisualStudioCodeCredential

Ze względu na znany problemVisualStudioCodeCredential został usunięty z łańcucha tokenówDefaultAzureCredential. Po rozwiązaniu problemu w przyszłej wersji ta zmiana zostanie przywrócona.

Przykłady

Poniżej przedstawiono następujące przykłady:

• Uwierzytelnianie przy użyciu elementu DefaultAzureCredential
• Definiowanie niestandardowego przepływu uwierzytelniania za pomocą elementu ChainedTokenCredential
• Poświadczenia asynchroniczne

Uwierzytelnianie za pomocą polecenia DefaultAzureCredential

Więcej informacji na temat konfigurowania środowiska w celu korzystania z niego DefaultAzureCredential można znaleźć w dokumentacji referencyjnej klasy.

W tym przykładzie pokazano uwierzytelnianie BlobServiceClient elementu z biblioteki azure-storage-blob przy użyciu polecenia DefaultAzureCredential.

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

default_credential = DefaultAzureCredential()

client = BlobServiceClient(account_url, credential=default_credential)

Włączanie uwierzytelniania interakcyjnego za pomocą polecenia DefaultAzureCredential

Uwierzytelnianie interakcyjne jest domyślnie wyłączone DefaultAzureCredential i można je włączyć za pomocą argumentu słowa kluczowego:

DefaultAzureCredential(exclude_interactive_browser_credential=False)

Po DefaultAzureCredential włączeniu tej opcji następuje interaktywne uwierzytelnianie za pośrednictwem domyślnej przeglądarki internetowej systemu, gdy żadne inne poświadczenia nie są dostępne.

Określanie tożsamości zarządzanej przypisanej przez użytkownika dla DefaultAzureCredential

Wiele hostów platformy Azure umożliwia przypisanie tożsamości zarządzanej przypisanej przez użytkownika. Aby skonfigurować DefaultAzureCredential uwierzytelnianie tożsamości przypisanej przez użytkownika, użyj argumentu słowa kluczowego managed_identity_client_id :

DefaultAzureCredential(managed_identity_client_id=client_id)

Alternatywnie ustaw zmienną środowiskową AZURE_CLIENT_ID na identyfikator klienta tożsamości.

Definiowanie niestandardowego przepływu uwierzytelniania za pomocą polecenia ChainedTokenCredential

DefaultAzureCredential Jest to najszybszy sposób rozpoczęcia tworzenia aplikacji dla platformy Azure. W przypadku bardziej zaawansowanych scenariuszy funkcja ChainedTokenCredential łączy wiele wystąpień poświadczeń do wypróbowania sekwencyjnie podczas uwierzytelniania. Spowoduje to wypróbowanie każdego poświadczeń łańcuchowych po kolei, dopóki jeden nie udostępni tokenu lub nie zostanie uwierzytelniony z powodu błędu.

W poniższym przykładzie pokazano tworzenie poświadczeń, które najpierw spróbują uwierzytelnić się przy użyciu tożsamości zarządzanej. Poświadczenie wróci do uwierzytelnienia za pośrednictwem interfejsu wiersza polecenia platformy Azure, gdy tożsamość zarządzana jest niedostępna. W tym przykładzie użyto elementu EventHubProducerClient z biblioteki klienta 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)

Poświadczenia asynchroniczne

Ta biblioteka zawiera zestaw asynchronicznych interfejsów API. Aby użyć poświadczeń asynchronicznych w pliku azure.identity.aio, należy najpierw zainstalować transport asynchroniczny, taki jak aiohttp. Aby uzyskać więcej informacji, zobacz dokumentację azure-core.

Poświadczenia asynchroniczne powinny być zamykane, gdy nie są już potrzebne. Każde poświadczenie asynchroniczne jest menedżerem kontekstu asynchronicznego i definiuje metodę asynchroniczna close . Na przykład:

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

W tym przykładzie pokazano uwierzytelnianie asynchroniczne SecretClient z usługi azure-keyvault-secrets przy użyciu poświadczeń asynchronicznych.

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)

Obsługa tożsamości zarządzanej

Uwierzytelnianie tożsamości zarządzanej jest obsługiwane za pośrednictwem elementu DefaultAzureCredential lub ManagedIdentityCredential bezpośrednio dla następujących usług platformy Azure:

• Azure App Service i Azure Functions
• Azure Arc
• Azure Cloud Shell
• Azure Kubernetes Service
• Azure Service Fabric
• Azure Virtual Machines
• Zestawy skalowania usługi Azure Virtual Machines

Przykłady

Uwierzytelnianie przy użyciu tożsamości zarządzanej przypisanej przez użytkownika

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)

Uwierzytelnianie przy użyciu tożsamości zarządzanej przypisanej przez system

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

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

Konfiguracja chmury

Poświadczenia są domyślnie uwierzytelniane w punkcie końcowym Azure AD dla chmury publicznej platformy Azure. Aby uzyskać dostęp do zasobów w innych chmurach, takich jak Azure Government lub chmura prywatna, skonfiguruj poświadczenia za pomocą argumentu authority . AzureAuthorityHosts definiuje urzędy dla dobrze znanych chmur:

from azure.identity import AzureAuthorityHosts

DefaultAzureCredential(authority=AzureAuthorityHosts.AZURE_GOVERNMENT)

Jeśli urząd dla chmury nie znajduje się na liście , AzureAuthorityHostsmożesz jawnie określić jego adres URL:

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

Alternatywą dla określenia argumentu jest również ustawienie AZURE_AUTHORITY_HOST zmiennej authority środowiskowej na adres URL urzędu chmury. Takie podejście jest przydatne podczas konfigurowania wielu poświadczeń w celu uwierzytelniania w tej samej chmurze:

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

Nie wszystkie poświadczenia wymagają tej konfiguracji. Poświadczenia uwierzytelniające się za pomocą narzędzia programistycznego, takiego jak AzureCliCredential, używają konfiguracji tego narzędzia. Podobnie akceptuje argument, VisualStudioCodeCredential ale domyślnie jest zgodny z authority ustawieniem "Azure: Cloud" programu VS Code zgodnym z urzędem.

Klasy poświadczeń

Uwierzytelnianie aplikacji hostowanych na platformie Azure

Referencje	Użycie
DefaultAzureCredential	Zapewnia uproszczone środowisko uwierzytelniania umożliwiające szybkie rozpoczęcie tworzenia aplikacji uruchamianych na platformie Azure.
ChainedTokenCredential	Umożliwia użytkownikom definiowanie niestandardowych przepływów uwierzytelniania, które komponują wiele poświadczeń.
EnvironmentCredential	Uwierzytelnia jednostkę usługi lub użytkownika za pomocą informacji o poświadczeniach określonych w zmiennych środowiskowych.
ManagedIdentityCredential	Uwierzytelnia tożsamość zarządzaną zasobu platformy Azure.
WorkloadIdentityCredential	Obsługuje Azure AD tożsamość obciążenia na platformie Kubernetes.

Uwierzytelnianie jednostek usługi

Referencje	Użycie	Odwołanie
CertificateCredential	Uwierzytelnia jednostkę usługi przy użyciu certyfikatu.	Uwierzytelnianie jednostki usługi
ClientAssertionCredential	Uwierzytelnia jednostkę usługi przy użyciu podpisanej asercji klienta.
ClientSecretCredential	Uwierzytelnia jednostkę usługi przy użyciu wpisu tajnego.	Uwierzytelnianie jednostki usługi

Uwierzytelnianie użytkowników

Referencje	Użycie	Odwołanie
AuthorizationCodeCredential	Uwierzytelnia użytkownika przy użyciu wcześniej uzyskanego kodu autoryzacji.	Kod uwierzytelniania OAuth2
DeviceCodeCredential	Interakcyjnie uwierzytelnia użytkownika na urządzeniach z ograniczonym interfejsem użytkownika.	Uwierzytelnianie kodu urządzenia
InteractiveBrowserCredential	Interakcyjnie uwierzytelnia użytkownika za pomocą domyślnej przeglądarki systemowej.	Kod uwierzytelniania OAuth2
OnBehalfOfCredential	Propaguje tożsamość i uprawnienia delegowanego użytkownika za pośrednictwem łańcucha żądań.	Uwierzytelnianie w imieniu
UsernamePasswordCredential	Uwierzytelnia użytkownika przy użyciu nazwy użytkownika i hasła (nie obsługuje uwierzytelniania wieloskładnikowego).	Nazwa użytkownika i uwierzytelnianie hasłem

Uwierzytelnianie za pomocą narzędzi programistycznych

Referencje	Użycie	Odwołanie
AzureCliCredential	Uwierzytelnia się w środowisku projektowym przy użyciu interfejsu wiersza polecenia platformy Azure.	Uwierzytelnianie interfejsu wiersza polecenia platformy Azure
AzureDeveloperCliCredential	Uwierzytelnia się w środowisku projektowym przy użyciu Azure Developer CLI.	dokumentacja Azure Developer CLI
AzurePowerShellCredential	Uwierzytelnia się w środowisku projektowym przy użyciu Azure PowerShell.	Uwierzytelnianie Azure PowerShell
VisualStudioCodeCredential	Uwierzytelnia się jako użytkownik zalogowany do rozszerzenia konta platformy Azure Visual Studio Code.	Rozszerzenie konta platformy Azure programu VS Code

Zmienne środowiskowe

DomyślneAzureCredential i EnvironmentCredential można skonfigurować przy użyciu zmiennych środowiskowych. Każdy typ uwierzytelniania wymaga wartości dla określonych zmiennych:

Jednostka usługi z wpisem tajnym

Nazwa zmiennej	Wartość
AZURE_CLIENT_ID	Identyfikator aplikacji Azure AD
AZURE_TENANT_ID	Identyfikator dzierżawy Azure AD aplikacji
AZURE_CLIENT_SECRET	jeden z wpisów tajnych klienta aplikacji

Jednostka usługi z certyfikatem

Nazwa zmiennej	Wartość
AZURE_CLIENT_ID	Identyfikator aplikacji Azure AD
AZURE_TENANT_ID	Identyfikator dzierżawy Azure AD aplikacji
AZURE_CLIENT_CERTIFICATE_PATH	ścieżka do pliku certyfikatu PEM lub PKCS12, w tym klucza prywatnego
AZURE_CLIENT_CERTIFICATE_PASSWORD	hasło pliku certyfikatu, jeśli istnieje

Nazwa użytkownika i hasło

Nazwa zmiennej	Wartość
AZURE_CLIENT_ID	Identyfikator aplikacji Azure AD
AZURE_USERNAME	nazwa użytkownika (zazwyczaj adres e-mail)
AZURE_PASSWORD	hasło tego użytkownika

Konfiguracja jest podejmowana w powyższej kolejności. Jeśli na przykład wartości klucza tajnego klienta i certyfikatu są obecne, zostanie użyty klucz tajny klienta.

Buforowanie tokenów

Buforowanie tokenów to funkcja udostępniana przez bibliotekę tożsamości platformy Azure, która umożliwia aplikacjom wykonywanie następujących działań:

• Tokeny pamięci podręcznej w pamięci (wartość domyślna) lub na dysku (zgoda).
• Zwiększ odporność i wydajność.
• Zmniejsz liczbę żądań wysyłanych do Azure AD w celu uzyskania tokenów dostępu.

Biblioteka tożsamości platformy Azure oferuje buforowanie dysków w pamięci i trwałym. Aby uzyskać więcej informacji, zobacz dokumentację buforowania tokenów.

Rozwiązywanie problemów

Aby uzyskać szczegółowe informacje na temat diagnozowania różnych scenariuszy awarii, zobacz przewodnik rozwiązywania problemów .

Obsługa błędów

Poświadczenia są wywoływane CredentialUnavailableError , gdy nie mogą próbować uwierzytelniania, ponieważ nie mają wymaganych danych lub stanu. Na przykład environmentCredential zgłosi ten wyjątek, gdy jest niekompletna.

Poświadczenia są wywoływane azure.core.exceptions.ClientAuthenticationError , gdy nie można uwierzytelnić. ClientAuthenticationErrormessage ma atrybut, który opisuje, dlaczego uwierzytelnianie nie powiodło się. W przypadku zgłoszenia przez DefaultAzureCredential program lub ChainedTokenCredentialkomunikat zbiera komunikaty o błędach z każdego poświadczenia w łańcuchu.

Aby uzyskać więcej informacji na temat obsługi określonych błędów Azure AD, zobacz dokumentację kodu błędu Azure AD.

Rejestrowanie

Ta biblioteka używa standardowej biblioteki rejestrowania do rejestrowania. Poświadczenia rejestrują podstawowe informacje, w tym sesje HTTP (adresy URL, nagłówki itp.) na poziomie INFORMACJI. Te wpisy dziennika nie zawierają wpisów tajnych uwierzytelniania.

Szczegółowe rejestrowanie na poziomie DEBUG, w tym treści żądań/odpowiedzi i wartości nagłówka, nie jest domyślnie włączone. Można go włączyć za pomocą argumentu logging_enable . Na przykład:

credential = DefaultAzureCredential(logging_enable=True)

UWAGA: dzienniki poziomu debugowania z poświadczeń zawierają poufne informacje. Te dzienniki muszą być chronione, aby uniknąć naruszenia zabezpieczeń konta.

Następne kroki

Obsługa biblioteki klienta

Biblioteki klienta i zarządzania wymienione na stronie wydania zestawu Azure SDK, które obsługują Azure AD uwierzytelniania akceptują poświadczenia z tej biblioteki. Więcej informacji na temat używania tych bibliotek można dowiedzieć się w swojej dokumentacji, która jest połączona ze stroną wydania.

Znane problemy

Ta biblioteka nie obsługuje Azure AD B2C.

W przypadku innych otwartych problemów zapoznaj się z repozytorium GitHub biblioteki.

Wyraź opinię

Jeśli wystąpią usterki lub masz sugestie, otwórz problem.

Współtworzenie

W tym projekcie zachęcamy do współtworzenia i zgłaszania sugestii. Współtworzenie w większości przypadków wymaga zgody na umowę licencyjną dotyczącą współautorów (CLA, Contributor License Agreement), zgodnie z którą współautor ma prawo udzielić i faktycznie udziela nam praw do używania wytworzonej przez siebie zawartości. Aby uzyskać szczegółowe informacje, odwiedź stronę https://cla.microsoft.com.

Po przesłaniu żądania ściągnięcia robot CLA automatycznie określi, czy musisz przekazać umowę CLA, i doda odpowiednie informacje do tego żądania (na przykład etykietę czy komentarz). Po prostu postępuj zgodnie z instrukcjami robota. Musisz to zrobić tylko raz we wszystkich repozytoriach przy użyciu naszego cla.

W tym projekcie przyjęto Kodeks postępowania oprogramowania Open Source firmy Microsoft. Aby uzyskać więcej informacji, zobacz artykuł Code of Conduct FAQ (Często zadawane pytania dotyczące kodeksu postępowania). Jeśli będziesz mieć jeszcze jakieś pytania lub komentarze, wyślij wiadomość e-mail na adres opencode@microsoft.com.