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ń.
- Środowiska -
DefaultAzureCredential
Program odczytuje informacje o koncie określone za pośrednictwem i używa ich do uwierzytelniania. - 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ą. - 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ą. - 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. - Azure PowerShell — jeśli użytkownik zalogował się za pomocą polecenia Azure PowerShell
Connect-AzAccount
,DefaultAzureCredential
zostanie uwierzytelniony jako ten użytkownik. - Azure Developer CLI — jeśli deweloper uwierzytelnił się za pomocą polecenia Azure Developer CLI
azd auth login
,DefaultAzureCredential
zostanie uwierzytelniony przy użyciu tego konta. - 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 , AzureAuthorityHosts
moż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ć. ClientAuthenticationError
message
ma atrybut, który opisuje, dlaczego uwierzytelnianie nie powiodło się. W przypadku zgłoszenia przez DefaultAzureCredential
program lub ChainedTokenCredential
komunikat 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.