Udostępnij za pośrednictwem

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

  • Artykuł

Biblioteka klienta tożsamości platformy Azure udostępnia poświadczenia — klasy publiczne, które implementują protokół TokenCredential 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 mają być podejmowane.

Jak działa poświadczenie łańcuchowe

W czasie wykonywania łańcuch poświadczeń próbuje uwierzytelnić się przy użyciu pierwszego poświadczenia 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 różne filozofie tworzenia łańcuchów 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 domyślneAzureCredential.
  • "Utwórz" łańcuch: zacznij od pustego łańcucha i uwzględnij tylko potrzebne elementy. Aby uzyskać to podejście, zobacz sekcję ChainedTokenCredential overview (Omówienie elementu ChainedTokenCredential).

Omówienie domyślneAzureCredential

DefaultAzureCredential jest 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 której DefaultAzureCredential następuje próba wykonania poświadczeń.

Zamówienie Referencje opis Włączone domyślnie?
1 Środowisko Odczytuje kolekcję zmiennych środowiskowych, aby określić, czy dla aplikacji skonfigurowano jednostkę usługi aplikacji (użytkownika aplikacji). 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ść obciążenia 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
100 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 Interfejs wiersza polecenia platformy Azure Jeśli deweloper uwierzytelniony na platformie Azure przy użyciu polecenia interfejsu az login wiersza polecenia platformy Azure, uwierzytelnij aplikację na platformie Azure przy użyciu 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 uwierzytelniony na platformie Azure przy użyciu polecenia interfejsu azd auth login wiersza polecenia dla deweloperów platformy Azure, uwierzytelnij się przy użyciu tego konta. Tak
8 Przeglądarka interaktywna Jeśli to ustawienie jest włączone, interakcyjne uwierzytelnianie dewelopera za pośrednictwem domyślnej przeglądarki bieżącego systemu. Nie.

W najprostszej formie można użyć bez parametrów DefaultAzureCredential wersji 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ć wartość domyślnąAzureCredential

Aby usunąć poświadczenie z DefaultAzureCredentialprogramu , użyj odpowiedniego excludeparametru -prefiksed 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 kodu i WorkloadIdentityCredential są usuwane z łańcucha poświadczeń. W związku z tym pierwsze poświadczenie do podjęcia próby to ManagedIdentityCredential. Zmodyfikowany łańcuch wygląda następująco:

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

Uwaga

InteractiveBrowserCredential jest domyślnie wykluczony i dlatego nie jest wyświetlany na powyższym diagramie. Aby uwzględnić InteractiveBrowserCredentialparametr , ustaw parametr słowa kluczowego exclude_interactive_browser_credential na False wartość podczas wywoływania konstruktora DefaultAzureCredential .

W miarę ustawiania większej excludeliczby parametrów słowa kluczowego prefiksu na True wartość (wykluczenia poświadczeń są konfigurowane), korzyści wynikające z używania 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(
    ManagedIdentityCredential(client_id=user_assigned_client_id),
    AzureCliCredential()
)

Powyższy przykładowy kod tworzy dostosowany łańcuch poświadczeń składający się z dwóch poświadczeń. Wariant tożsamości zarządzanej przypisanej ManagedIdentityCredential przez użytkownika jest najpierw podejmowany, a następnie AzureCliCredential, w razie potrzeby. W formie graficznej łańcuch wygląda następująco:

Diagram przedstawiający przepływ uwierzytelniania dla wystąpienia ChainedTokenCredential składającego się z poświadczeń tożsamości zarządzanej i poświadczeń interfejsu wiersza polecenia platformy Azure.

Napiwek

Aby uzyskać lepszą wydajność, zoptymalizuj kolejność poświadczeń w ChainedTokenCredential środowisku produkcyjnym. Poświadczenia przeznaczone do użytku w lokalnym środowisku programistycznym powinny zostać dodane ostatnio.

Wskazówki dotyczące użycia elementu DefaultAzureCredential

DefaultAzureCredential jest niewątpliwie najprostszym sposobem rozpoczęcia pracy z biblioteką klienta tożsamości platformy Azure, ale z tym wygodą są kompromisy. Po wdrożeniu aplikacji na platformie Azure należy zrozumieć wymagania dotyczące uwierzytelniania aplikacji. Z tego powodu zdecydowanie rozważ przejście z jednego z DefaultAzureCredential następujących rozwiązań:

  • Konkretna implementacja poświadczeń, taka jak ManagedIdentityCredential.
  • Implementacja pared-down ChainedTokenCredential zoptymalizowana pod kątem środowiska platformy Azure, w którym działa aplikacja.

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 związku z tym zawsze kończy się niepowodzeniem w lokalnym środowisku projektowym, chyba że jawnie wyłączone za pośrednictwem odpowiedniej excludewłaściwości -prefiksed.
  • 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 środowiska uruchomieniowego w dowolnej aplikacji uruchomionej 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 na koncie magazynu obiektów blob. Aplikacja działa w lokalnym środowisku projektowym, a deweloper uwierzytelniony na platformie Azure przy użyciu interfejsu wiersza polecenia platformy Azure. Załóżmy również, że poziom rejestrowania jest ustawiony na logging.DEBUGwartość . 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, ManagedIdentityCredentiali SharedTokenCacheCredential każdy z nich nie może uzyskać tokenu dostępu firmy Microsoft Entra w tej kolejności.
  • Wywołanie AzureCliCredential.get_token zakończy się pomyślnie, a dane wyjściowe wskazują również, że DefaultAzureCredential uzyskano token z .AzureCliCredential Ponieważ AzureCliCredential zakończyło się pomyślnie, nie próbowano poświadczeń poza nią.

Uwaga

W poprzednim przykładzie poziom rejestrowania jest ustawiony na logging.DEBUGwartość . 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 podmiotu zabezpieczeń użytkownika dewelopera na platformie Azure. Wszystkie informacje o śledzeniu zwrotnym zostały usunięte z danych wyjściowych w celu uzyskania przejrzystości.