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

Biblioteka klienta tożsamości Azure udostępnia poświadczenia — typy publiczne, które pochodzą z abstrakcyjnej klasy bazowej 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 należy zastosować.

Jak działa poświadczenie łańcuchowe

Podczas działania łańcuch poświadczeń próbuje uwierzytelnić się przy użyciu pierwszego poświadczenia z 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)
std::shared_ptr<Azure::Core::Credentials::TokenCredential> credential;
if (std::getenv("WEBSITE_HOSTNAME"))
{
    credential = std::make_shared<Azure::Identity::ManagedIdentityCredential>();
}
else
{
    credential = std::make_shared<Azure::Identity::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

W języku C++istnieją dwie opcje tworzenia łańcuchów poświadczeń:

Użyj wstępnie skonfigurowanego łańcucha: użyj wstępnie skonfigurowanego łańcucha zaimplementowanego przez typ DefaultAzureCredential. W przypadku tego podejścia zobacz sekcję Omówienie DefaultAzureCredential.
Utwórz niestandardowy łańcuch poświadczeń: 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 opiniotwórczym, wstępnie skonfigurowanym łańcuchem poświadczeń. Jego projekt obsługuje wiele środowisk oraz najczęściej używane przepływy uwierzytelniania i narzędzia programistyczne. W postaci graficznej podstawowy łańcuch wygląda następująco:

Diagram przedstawiający przepływ uwierzytelniania DefaultAzureCredential.

Kolejność, w której DefaultAzureCredential próbuje użyć danych uwierzytelniających, jest następująca.

Zamówienie	Uprawnienia	Opis
1	Środowisko	Odczytuje kolekcję zmiennych środowiskowych w celu określenia, czy dla aplikacji skonfigurowano głównego użytkownika usługi (użytkownika aplikacji). Jeśli tak, `DefaultAzureCredential` używa 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.
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.
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.
4	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.

W najprostszym ujęciu można użyć wersji DefaultAzureCredential bez parametrów w następujący sposób:

#include <azure/identity/default_azure_credential.hpp>
#include <azure/storage/blobs/blob_client.hpp>

int main()
{
    // create a credential
    auto credential = std::make_shared<Azure::Identity::DefaultAzureCredential>();

    // create a Blob service client
    auto blobUrl = "https://<my_account_name>.blob.core.windows.net/mycontainer/myblob";
    Azure::Storage::Blobs::BlobClient blobClient{blobUrl, credential};
}

Jak dostosować DefaultAzureCredential

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

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 zawiera tylko AzureCliCredential.

Aby upewnić się, że zmienna środowiskowa jest zdefiniowana i ustawiona na obsługiwany ciąg, przekaż true do konstruktora DefaultAzureCredential :

auto credential = std::make_shared<Azure::Identity::DefaultAzureCredential>(true);

Ważne

Wyżej wymienione przeciążenie konstruktora jest obsługiwane w pakietach azure-identity-cpp wersji 1.13.1 lub nowszej.

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
EnvironmentCredential
ManagedIdentityCredential
WorkloadIdentityCredential

Aby upewnić się, że zmienna środowiskowa jest zdefiniowana i ustawiona na obsługiwany ciąg, przekaż true do konstruktora DefaultAzureCredential :

auto credential = std::make_shared<Azure::Identity::DefaultAzureCredential>(true);

Ważne

Wyżej wymienione przeciążenie konstruktora jest obsługiwane w pakietach azure-identity-cpp wersji 1.13.1 lub nowszej.

ChainedTokenCredential — omówienie

ChainedTokenCredential to pusty łańcuch, do którego dodasz poświadczenia zgodnie z potrzebami aplikacji. Przykład:

#include <azure/identity/azure_cli_credential.hpp>
#include <azure/identity/chained_token_credential.hpp>
#include <azure/identity/managed_identity_credential.hpp>
#include <azure/storage/blobs/blob_client.hpp>

int main()
{
    // create a credential
    auto credential = std::make_shared<Azure::Identity::ChainedTokenCredential>(
        Azure::Identity::ChainedTokenCredential::Sources{
            std::make_shared<Azure::Identity::ManagedIdentityCredential>(),
            std::make_shared<Azure::Identity::AzureCliCredential>()});

    // create a Blob service client
    auto blobUrl = "https://<my_account_name>.blob.core.windows.net/mycontainer/myblob";
    Azure::Storage::Blobs::BlobClient blobClient{blobUrl, credential};
}

Powyższy przykładowy kod tworzy dostosowany łańcuch poświadczeń składający się z dwóch poświadczeń. Najpierw podejmowana jest próba z ManagedIdentityCredential, a w razie potrzeby z AzureCliCredential. W formie graficznej łańcuch wygląda następująco:

Diagram przedstawiający przepływ uwierzytelniania dla instancji ChainedTokenCredential złożonej z ManagedIdentityCredential i AzureCliCredential.

Wskazówka

Aby uzyskać lepszą wydajność, zoptymalizuj kolejność poświadczeń w ChainedTokenCredential z większości do najmniej używanych poświadczeń.

Instrukcja użytkowania DefaultAzureCredential

DefaultAzureCredential jest niewątpliwie najprostszym sposobem rozpoczęcia pracy z biblioteką klienta tożsamości platformy Azure, ale z tą wygodą wiążą się pewne kompromisy. 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.

Oto dlaczego:

Problemy z debugowaniem: w przypadku niepowodzenia uwierzytelniania, debugowanie oraz identyfikacja wadliwych poświadczeń mogą być trudne. 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 tożsamość zarządzana jest niedostępna podczas uruchamiania na lokalnym komputerze deweloperskim. W związku z tym ManagedIdentityCredential zawsze kończy się niepowodzeniem w lokalnym środowisku projektowym.
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 uruchomionej na tym komputerze.

Debugowanie poświadczeń łańcuchowych

Aby zdiagnozować nieoczekiwany problem lub zrozumieć, co robi poświadczenie łańcuchowe, włączyć rejestrowanie w aplikacji. W celach ilustracyjnych załóżmy, że forma bez parametrów DefaultAzureCredential jest używana do uwierzytelniania żądania na koncie usługi Blob Storage. Aplikacja działa w lokalnym środowisku deweloperskim, a deweloper uwierzytelnił się w Azure za pomocą Azure CLI. Po uruchomieniu aplikacji w danych wyjściowych są wyświetlane następujące istotne wpisy:

DEBUG : Identity: Creating DefaultAzureCredential which combines multiple parameterless credentials into a single one.
DefaultAzureCredential is only recommended for the early stages of development, and not for usage in production environment.
Once the developer focuses on the Credentials and Authentication aspects of their application, DefaultAzureCredential needs to be replaced with the credential that is the better fit for the application.
INFO  : Identity: EnvironmentCredential gets created with ClientSecretCredential.
DEBUG : Identity: EnvironmentCredential: 'AZURE_TENANT_ID', 'AZURE_CLIENT_ID', and 'AZURE_CLIENT_SECRET' environment variables are set, so ClientSecretCredential with corresponding tenantId, clientId, and clientSecret gets created.
WARN  : Identity: Azure Kubernetes environment is not set up for the WorkloadIdentityCredential credential to work.
DEBUG : Identity: ManagedIdentityCredential: Environment is not set up for the credential to be created with App Service 2019 source.
DEBUG : Identity: ManagedIdentityCredential: Environment is not set up for the credential to be created with App Service 2017 source.
DEBUG : Identity: ManagedIdentityCredential: Environment is not set up for the credential to be created with Cloud Shell source.
DEBUG : Identity: ManagedIdentityCredential: Environment is not set up for the credential to be created with Azure Arc source.
INFO  : Identity: ManagedIdentityCredential will be created with Azure Instance Metadata Service source.
Successful creation does not guarantee further successful token retrieval.
INFO  : Identity: AzureCliCredential created.
Successful creation does not guarantee further successful token retrieval.
INFO  : Identity: DefaultAzureCredential: Created with the following credentials: EnvironmentCredential, WorkloadIdentityCredential, ManagedIdentityCredential, AzureCliCredential.
DEBUG : Identity: DefaultAzureCredential: Failed to get token from EnvironmentCredential: GetToken(): error response: 400 Bad Request

{"error":"invalid_grant","error_description":"AADSTS53003: Access has been blocked by Conditional Access policies. The access policy does not allow token issuance. Trace ID: 0000aaaa-11bb-cccc-dd22-eeeeee333333 Correlation ID: aaaa0000-bb11-2222-33cc-444444dddddd Timestamp: 2025-03-07 21:25:44Z","error_codes":[53003],"timestamp":"2025-03-07 21:25:44Z","trace_id":"0000aaaa-11bb-cccc-dd22-eeeeee333333","correlation_id":"aaaa0000-bb11-2222-33cc-444444dddddd","error_uri":"https://login.microsoftonline.com/error?code=53003","suberror":"message_only","claims":"{\"access_token\":{\"capolids\":{\"essential\":true,\"values\":[\"cccc2222-dd33-4444-55ee-666666ffffff\"]}}}"}
WARN  : Identity: WorkloadIdentityCredential authentication unavailable. See earlier WorkloadIdentityCredential log messages for details.
DEBUG : Identity: DefaultAzureCredential: Failed to get token from WorkloadIdentityCredential: WorkloadIdentityCredential authentication unavailable. Azure Kubernetes environment is not set up correctly.
INFO  : Identity: DefaultAzureCredential: Successfully got token from ManagedIdentityCredential. This credential will be reused for subsequent calls.
DEBUG : Identity: DefaultAzureCredential: Saved this credential at index 2 for subsequent calls.

W poprzednich danych wyjściowych zwróć uwagę, że:

EnvironmentCredential, WorkloadIdentityCredential, i ManagedIdentityCredential nie uzyskali tokenu dostępu Microsoft Entra, w tej kolejności.
ManagedIdentityCredential odnosi sukces, co wskazuje wpis rozpoczynający się od "Successfully got token from ManagedIdentityCredential".

Sprzężenie zwrotne

Czy ta strona była pomocna?

Last updated on 2025-11-24