Łańcuchy poświadczeń w bibliotece tożsamości platformy Azure dla języka Python
Biblioteka tożsamości platformy Azure udostępnia poświadczenia — klasy publiczne, które implementują protokół TokenCredent ial biblioteki Azure Core. Poświadczenie reprezentuje odrębny przepływ uwierzytelniania na potrzeby uzyskiwania tokenu dostępu z identyfikatora Entra firmy Microsoft. Te poświadczenia można połączyć w łańcuch, aby utworzyć uporządkowaną sekwencję mechanizmów uwierzytelniania, które należy zastosować.
Jak działa poświadczenie łańcuchowe
Podczas wykonywania łańcuch poświadczeń najpierw próbuje uwierzytelnić się przy użyciu pierwszego poświadczenia w sekwencji. Jeśli to poświadczenie nie może uzyskać tokenu dostępu, zostanie podjęta próba następnego poświadczenia w sekwencji itd., dopóki token dostępu nie zostanie pomyślnie uzyskany. Poniższy diagram sekwencji ilustruje to zachowanie:
Dlaczego warto używać łańcuchów poświadczeń
Poświadczenie łańcuchowe może oferować następujące korzyści:
Świadomość środowiska: automatycznie wybiera najbardziej odpowiednie poświadczenia na podstawie środowiska, w którym działa aplikacja. Bez niego musisz napisać kod podobny do następującego:
# 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()
Bezproblemowe przejścia: Aplikacja może przejść z lokalnego programowania do środowiska przejściowego lub produkcyjnego bez zmiany kodu uwierzytelniania.
Ulepszona odporność: obejmuje mechanizm rezerwowy, który przechodzi do następnego poświadczenia, gdy poprzednia próba uzyskania tokenu dostępu zakończy się niepowodzeniem.
Jak wybrać poświadczenie łańcuchowe
Istnieją dwie odmienne filozofie łańcuchowania poświadczeń:
- "Rozerwanie" łańcucha: Zacznij od wstępnie skonfigurowanego łańcucha i wyklucz to, czego nie potrzebujesz. W przypadku tego podejścia zobacz sekcję Omówienie DefaultAzureCredential.
- "Utwórz" łańcuch: zacznij od pustego łańcucha i uwzględnij tylko potrzebne elementy. Aby zapoznać się z tym podejściem, zobacz sekcję Omówienie ChainedTokenCredential.
Omówienie DefaultAzureCredential
DefaultAzureCredential jest opiniowanym, wstępnie skonfigurowanym łańcuchem poświadczeń. Jest ona przeznaczona do obsługi wielu środowisk wraz z najczęściej używanymi przepływami uwierzytelniania i narzędziami deweloperskich. W postaci graficznej podstawowy łańcuch wygląda następująco:
Kolejność, w jakiej DefaultAzureCredential
próbuje poświadczeń, jest następująca.
Zamówienie | Uprawnienia | opis | Włączone domyślnie? |
---|---|---|---|
1 | Środowisko | Odczytuje kolekcję zmiennych środowiskowych, aby określić, czy dla aplikacji skonfigurowano uprawnienia serwisowe aplikacji (użytkownika technicznego). Jeśli tak, DefaultAzureCredential użyj tych wartości do uwierzytelniania aplikacji na platformie Azure. Ta metoda jest najczęściej używana w środowiskach serwera, ale może być również używana podczas opracowywania lokalnie. |
Tak |
2 | Tożsamość zadania | Jeśli aplikacja zostanie wdrożona na hoście platformy Azure z włączoną tożsamością obciążenia, uwierzytelnij to konto. | Tak |
3 | Tożsamość zarządzana | Jeśli aplikacja zostanie wdrożona na hoście platformy Azure z włączoną tożsamością zarządzaną, uwierzytelnij aplikację na platformie Azure przy użyciu tej tożsamości zarządzanej. | Tak |
4 | Udostępniona pamięć podręczna tokenów | Tylko w systemie Windows, jeśli deweloper uwierzytelnił się na platformie Azure, logując się do programu Visual Studio, uwierzytelniaj aplikację na platformie Azure przy użyciu tego samego konta. | Tak |
5 | Azure CLI | Jeśli deweloper został uwierzytelniony w Azure przy użyciu polecenia az login w Azure CLI, uwierzytelnij aplikację do Azure używając tego samego konta. |
Tak |
6 | Azure PowerShell | Jeśli deweloper uwierzytelnił się na platformie Azure przy użyciu polecenia cmdlet programu Azure PowerShell Connect-AzAccount , uwierzytelnij aplikację na platformie Azure przy użyciu tego samego konta. |
Tak |
7 | Interfejs wiersza polecenia dla deweloperów platformy Azure | Jeśli deweloper uwierzytelnił się na platformie Azure przy użyciu polecenia azd auth login Azure Developer CLI, uwierzytelnij się przy użyciu tego konta. |
Tak |
8 | Przeglądarka interaktywna | Jeśli to ustawienie jest włączone, uwierzytelniaj dewelopera interaktywnie za pomocą domyślnej przeglądarki systemowej. | Nie. |
W najprostszej formie można użyć wersji DefaultAzureCredential
bez parametrów w następujący sposób:
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 dostosować DefaultAzureCredential
Aby usunąć poświadczenie z DefaultAzureCredential
, użyj odpowiedniego opatrzonego przedrostkiem exclude
parametru słowa kluczowego. Na przykład:
credential = DefaultAzureCredential(
exclude_environment_credential=True,
exclude_workload_identity_credential=True,
managed_identity_client_id=user_assigned_client_id
)
W poprzednim przykładzie EnvironmentCredential
i WorkloadIdentityCredential
są usuwane z łańcucha poświadczeń. W rezultacie jako pierwsze zostanie podjęta próba uzyskania poświadczenia ManagedIdentityCredential
. Zmodyfikowany łańcuch wygląda następująco:
Uwaga
InteractiveBrowserCredential
jest domyślnie wykluczony i dlatego nie jest wyświetlany na powyższym diagramie. Aby uwzględnić InteractiveBrowserCredential
, ustaw parametr słowa kluczowego exclude_interactive_browser_credential
na wartość False
podczas wywoływania konstruktora DefaultAzureCredential
.
W miarę jak większa liczba parametrów ze słowem kluczowym z prefiksem jest ustawiana na True
(konfigurowane są wykluczenia poświadczeń), korzyści z użycia DefaultAzureCredential
maleją. W takich przypadkach ChainedTokenCredential
jest lepszym wyborem i wymaga mniej kodu. Aby zilustrować, te dwa przykłady kodu zachowują się tak samo:
credential = DefaultAzureCredential(
exclude_environment_credential=True,
exclude_workload_identity_credential=True,
exclude_shared_token_cache_credential=True,
exclude_azure_powershell_credential=True,
exclude_azure_developer_cli_credential=True,
managed_identity_client_id=user_assigned_client_id
)
ChainedTokenCredential — omówienie
ChainedTokenCredential to pusty łańcuch, do którego dodasz poświadczenia zgodnie z potrzebami aplikacji. Na przykład:
credential = ChainedTokenCredential(
AzureCliCredential(),
AzureDeveloperCliCredential()
)
Przykładowy kod powyżej tworzy dostosowany łańcuch poświadczeń składający się z dwóch poświadczeń używanych podczas rozwoju. Najpierw podejmuje się próbę z AzureCliCredential
, a następnie z AzureDeveloperCliCredential
, w razie potrzeby. W formie graficznej łańcuch wygląda następująco:
Napiwek
Aby uzyskać lepszą wydajność, zoptymalizuj kolejność poświadczeń w ChainedTokenCredential
z większości do najmniej używanych poświadczeń.
Wskazówki dotyczące użycia DefaultAzureCredential
DefaultAzureCredential
jest niewątpliwie najprostszym sposobem rozpoczęcia pracy z biblioteką tożsamości platformy Azure, ale ta wygoda wiąże się z pewnymi kompromisami. Po wdrożeniu aplikacji na platformie Azure należy zrozumieć wymagania dotyczące uwierzytelniania aplikacji. Z tego powodu zastąp DefaultAzureCredential
określoną implementacją TokenCredential
, taką jak ManagedIdentityCredential
.
Poniżej przedstawiono przyczyny:
- Wyzwania związane z debugowaniem: w przypadku niepowodzenia uwierzytelniania może być trudne debugowanie i identyfikowanie obraźliwych poświadczeń. Należy włączyć rejestrowanie, aby zobaczyć postęp z jednego poświadczenia do następnego i stan powodzenia/niepowodzenia każdego z nich. Aby uzyskać więcej informacji, zobacz Debugowanie poświadczeń łańcuchowych.
-
Obciążenie związane z wydajnością: proces sekwencyjnie próbujący uzyskać wiele poświadczeń może wprowadzić obciążenie związane z wydajnością. Na przykład w przypadku uruchamiania na lokalnym komputerze deweloperskim tożsamość zarządzana jest niedostępna.
ManagedIdentityCredential
W rezultacie zawsze kończy się niepowodzeniem w lokalnym środowisku projektowym, chyba że jawnie wyłączone za pomocą odpowiedniej właściwości z prefiksemexclude
. -
Nieprzewidywalne zachowanie:
DefaultAzureCredential
sprawdza obecność określonych zmiennych środowiskowych. Możliwe, że ktoś może dodać lub zmodyfikować te zmienne środowiskowe na poziomie systemu na maszynie hosta. Te zmiany są stosowane globalnie i w związku z tym zmieniają zachowanieDefaultAzureCredential
w trakcie działania dowolnej aplikacji na tym komputerze.
Debugowanie poświadczeń łańcuchowych
Aby zdiagnozować nieoczekiwany problem lub zrozumieć, co robi łańcuchowe poświadczenia, włącz rejestrowanie w aplikacji. Opcjonalnie przefiltruj dzienniki tylko do tych zdarzeń emitowanych z biblioteki klienta tożsamości platformy Azure. Na przykład:
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)}"
)
W celach ilustracyjnych załóżmy, że forma bez parametrów DefaultAzureCredential
jest używana do uwierzytelniania żądania do konta przechowywania danych blob. Aplikacja działa w lokalnym środowisku deweloperskim, a deweloper uwierzytelnił się w Azure za pomocą Azure CLI. Załóżmy również, że poziom rejestrowania jest ustawiony na logging.DEBUG
. Po uruchomieniu aplikacji w danych wyjściowych są wyświetlane następujące istotne wpisy:
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.
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
W poprzednich danych wyjściowych zwróć uwagę, że:
-
EnvironmentCredential
,ManagedIdentityCredential
, iSharedTokenCacheCredential
nie uzyskali tokenu dostępu Microsoft Entra, w tej kolejności. - Wywołanie
AzureCliCredential.get_token
zakończyło się pomyślnie, a dane wyjściowe wskazują również, że tokenDefaultAzureCredential
uzyskano zAzureCliCredential
. PonieważAzureCliCredential
zakończyło się pomyślnie, nie próbowano innych poświadczeń.
Uwaga
W poprzednim przykładzie poziom rejestrowania jest ustawiony na logging.DEBUG
. Należy zachować ostrożność podczas korzystania z tego poziomu rejestrowania, ponieważ może on wyświetlać poufne informacje. Na przykład w tym przypadku identyfikator klienta, identyfikator dzierżawy i identyfikator obiektu nadrzędnego użytkownika dewelopera w Azure. Wszystkie informacje o śledzeniu zwrotnym zostały usunięte z danych wyjściowych w celu uzyskania przejrzystości.