Udostępnij za pomocą

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

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 Visual Studio Code Jeśli deweloper uwierzytelniony za pośrednictwem rozszerzenia zasobów platformy Azure programu Visual Studio Code i zostanie zainstalowany pakiet azure-identity-broker , uwierzytelnij to konto. Tak
6 Interfejs wiersza polecenia platformy Azure 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
7 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
8 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
9 Przeglądarka interaktywna Jeśli to ustawienie jest włączone, uwierzytelniaj dewelopera interaktywnie za pomocą domyślnej przeglądarki systemowej. Nie.
10 Brokera Uwierzytelnia się przy użyciu konta domyślnego zalogowanego do systemu operacyjnego za pośrednictwem brokera. Wymaga zainstalowania pakietu azure-identity-broker , ponieważ jest używane wystąpienie InteractiveBrowserBrokerCredential programu . Tak

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

W poniższych sekcjach opisano strategie kontrolowania poświadczeń zawartych w łańcuchu.

Wykluczanie pojedynczego poświadczenia

Aby wykluczyć pojedyncze poświadczenie z DefaultAzureCredential, użyj odpowiedniego parametru exclude z prefiksem 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 exclude (konfigurowane są wykluczenia poświadczeń), korzyści z użycia True 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_visual_studio_code_credential=True,
    exclude_azure_powershell_credential=True,
    exclude_azure_developer_cli_credential=True,
    exclude_broker_credential=True,
    managed_identity_client_id=user_assigned_client_id
)

Wyklucz kategorię typu poświadczeń

Aby wykluczyć wszystkie Developer tool lub Deployed service poświadczenia, ustaw odpowiednio zmienną środowiskową AZURE_TOKEN_CREDENTIALS na prod lub dev. Gdy jest używana wartość prod , podstawowy łańcuch poświadczeń wygląda następująco:

Diagram pokazujący DefaultAzureCredential z AZURE_TOKEN_CREDENTIALS ustawionym na 'prod'.

W przypadku użycia wartości dev łańcuch wygląda następująco:

Diagram przedstawiający DefaultAzureCredential z AZURE_TOKEN_CREDENTIALS ustawionym na 'dev'.

Ważne

Zmienna środowiskowa AZURE_TOKEN_CREDENTIALS jest obsługiwana w pakietach azure-identity w wersji 1.23.0 lub nowszej.

Aby upewnić się, że zmienna środowiskowa jest zdefiniowana i ustawiona na obsługiwany ciąg, ustaw parametr require_envvar na True w konstruktorze:

credential = DefaultAzureCredential(require_envvar=True)

Używanie określonego poświadczenia

Aby wykluczyć wszystkie poświadczenia z wyjątkiem jednego, ustaw zmienną środowiskową AZURE_TOKEN_CREDENTIALS na nazwę poświadczenia. Możesz, na przykład, zmniejszyć DefaultAzureCredential do AzureCliCredential, ustawiając AZURE_TOKEN_CREDENTIALS na AzureCliCredential. Porównanie ciągów jest wykonywane w sposób niewrażliwy na wielkość liter. Prawidłowe wartości ciągów dla zmiennej środowiskowej obejmują:

  • AzureCliCredential
  • AzureDeveloperCliCredential
  • AzurePowerShellCredential
  • EnvironmentCredential
  • InteractiveBrowserCredential
  • ManagedIdentityCredential
  • VisualStudioCodeCredential
  • WorkloadIdentityCredential

Ważne

Zmienna AZURE_TOKEN_CREDENTIALS środowiskowa obsługuje poszczególne nazwy poświadczeń w pakiecie w azure-identity wersji 1.24.0 lub nowszej.

Aby upewnić się, że zmienna środowiskowa jest zdefiniowana i ustawiona na obsługiwany ciąg, ustaw parametr require_envvar na True w konstruktorze:

credential = DefaultAzureCredential(require_envvar=True)

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.
VisualStudioCodeCredential.get_token failed: VisualStudioCodeCredential authentication unavailable. No Azure account information found in Visual Studio Code.
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, SharedTokenCacheCredential i VisualStudioCodeCredential nie udało się uzyskać 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.

  • Last updated on