Udostępnij za pośrednictwem

Łańcuchy poświadczeń w bibliotece tożsamości platformy Azure dla języka Python

  • Artykuł

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:

Diagram przedstawiający sekwencję łańcucha poświadczeń.

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:

Diagram przedstawiający przepływ uwierzytelniania DefaultAzureCredential.

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

Diagram przedstawiający przepływ uwierzytelniania dla wystąpienia DefaultAzureCredential po użyciu parametrów słów kluczowych z prefiksem wykluczania w konstruktorze w celu usunięcia poświadczeń środowiskowych i poświadczeń tożsamości obciążenia.

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:

Diagram przedstawiający przepływ uwierzytelniania dla instancji ChainedTokenCredential składającej się z poświadczeń Azure CLI i Azure Developer CLI.

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 prefiksem exclude.
  • 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ą zachowanie DefaultAzureCredential 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, i SharedTokenCacheCredential 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 token DefaultAzureCredential uzyskano z AzureCliCredential. 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.