Řetězy přihlašovacích údajů v klientské knihovně Azure Identity pro C++

Klientská knihovna Azure Identity poskytuje přihlašovací údaje – veřejné typy odvozené z abstraktní základní třídy TokenCredential knihovny Azure Core. Přihlašovací údaje představují jedinečný tok ověřování pro získání přístupového tokenu z ID Microsoft Entra. Tyto přihlašovací údaje lze spojit dohromady a vytvořit seřazenou posloupnost ověřovacích mechanismů, které mají být vyzkoušeny.

Jak fungují řetězené přihlašovací údaje

Během spuštění se řetěz přihlašovacích údajů pokusí ověřit pomocí prvních přihlašovacích údajů v pořadí. Pokud se tento přihlašovací údaj nepodaří získat přístupový token, pokusí se další přihlašovací údaje v této sekvenci atd., dokud se přístupový token úspěšně nezíská. Toto chování znázorňuje následující sekvenční diagram:

Proč používat řetězy přihlašovacích údajů?

Zřetězené přihlašovací údaje mohou nabídnout následující výhody:

• Rozpoznávání prostředí: Automaticky vybere nejvhodnější přihlašovací údaje na základě prostředí, ve kterém je aplikace spuštěná. Bez něj byste museli psát kód takto:

  // 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>();
  }
  

• Bezproblémové přechody: Aplikace se může přesunout z místního vývoje do přípravného nebo produkčního prostředí beze změny ověřovacího kódu.

• Vylepšená odolnost: Zahrnuje náhradní mechanismus, který se přesune na další přihlašovací údaje, když se předchozí pokus o získání přístupového tokenu nezdaří.

Jak vybrat zřetězené přihlašovací údaje

V jazyce C++ existují dvě možnosti řetězení přihlašovacích údajů:

• Použít předkonfigurovaný řetěz: Použijte předkonfigurovaný řetězec implementovaný typem DefaultAzureCredential. Tento přístup najdete v části Přehled DefaultAzureCredential.
• Vytvoření vlastního řetězu přihlašovacích údajů: Začněte prázdným řetězem a zahrňte jenom to, co potřebujete. Tento přístup naleznete v části Přehled ChainedTokenCredential.

Přehled DefaultAzureCredential

DefaultAzureCredential je názorově vyhraněný a předkonfigurovaný řetězec přihlašovacích údajů. Jeho návrh podporuje mnoho prostředí spolu s nejběžnějšími toky ověřování a vývojářskými nástroji. Základní řetězec v grafické podobě vypadá takto:

Pořadí, ve kterém DefaultAzureCredential zkouší přihlašovací údaje, je následující.

Objednávka	Pověření	Popis
1	Prostředí	Načte kolekci proměnných prostředí , aby zjistil, zda je pro aplikaci nakonfigurovaný služební hlavní objekt aplikace (uživatel aplikace). Pokud ano, DefaultAzureCredential tyto hodnoty použije k ověření aplikace v Azure. Tato metoda se nejčastěji používá v serverových prostředích, ale dá se použít také při místním vývoji.
2	Identita úloh	Pokud je aplikace nasazená na hostitele Azure s povolenou identitou úloh, ověřte tento účet.
3	Spravovaná identita	Pokud je aplikace nasazená na hostitele Azure s povolenou spravovanou identitou, ověřte ji v Azure pomocí této spravované identity.
4	Azure CLI	Pokud se vývojář ověřil v Azure pomocí příkazu Azure CLI az login , ověřte aplikaci v Azure pomocí stejného účtu.

V nejjednodušší podobě můžete použít bezparametrovou verzi DefaultAzureCredential následujícím způsobem:

#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 přizpůsobit DefaultAzureCredential

Následující části popisují strategie pro řízení, které přihlašovací údaje jsou zahrnuty v řetězci.

Vyloučení kategorie typu přihlašovacích údajů

Chcete-li vyloučit všechny přihlašovací údaje Developer tool nebo Deployed service, nastavte proměnnou prostředí AZURE_TOKEN_CREDENTIALS na prod nebo dev. Pokud se použije hodnota prod, základní řetězec přihlašovacích údajů vypadá takto:

Pokud se použije hodnota dev, řetězec obsahuje pouze AzureCliCredential.

Pokud chcete zajistit, aby byla proměnná prostředí definovaná a nastavená na podporovaný řetězec, předejte true konstruktoru DefaultAzureCredential :

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

Důležité

Výše uvedené přetížení konstruktoru je podporováno ve azure-identity-cpp verzích balíčku 1.13.1 a novějších.

Použití konkrétních přihlašovacích údajů

Pokud chcete vyloučit všechny přihlašovací údaje kromě jednoho, nastavte proměnnou AZURE_TOKEN_CREDENTIALS prostředí na název přihlašovacích údajů. Můžete například zmenšit řetěz DefaultAzureCredential na AzureCliCredential tím, že nastavíte AZURE_TOKEN_CREDENTIALS na AzureCliCredential. Porovnání řetězců se provádí bez rozlišování velkých a malých písmen. Platné řetězcové hodnoty pro proměnnou prostředí zahrnují:

• AzureCliCredential
• EnvironmentCredential
• ManagedIdentityCredential
• WorkloadIdentityCredential

Pokud chcete zajistit, aby byla proměnná prostředí definovaná a nastavená na podporovaný řetězec, předejte true konstruktoru DefaultAzureCredential :

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

Důležité

Výše uvedené přetížení konstruktoru je podporováno ve azure-identity-cpp verzích balíčku 1.13.1 a novějších.

Přehled ChainedTokenCredential

ChainedTokenCredential je prázdný řetězec, ke kterému přidáváte přihlašovací údaje, které vyhovují potřebám vaší aplikace. Například:

#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};
}

Předchozí ukázka kódu vytvoří přizpůsobený řetěz přihlašovacích údajů složený ze dvou přihlašovacích údajů. Nejprve se provede ManagedIdentityCredential, a pokud je to nutné, následuje AzureCliCredential. V grafické podobě řetězec vypadá takto:

Návod

Pokud chcete dosáhnout vyššího výkonu, optimalizujte řazení přihlašovacích údajů v ChainedTokenCredential od většiny po nejméně používané přihlašovací údaje.

Pokyny k použití pro DefaultAzureCredential

DefaultAzureCredential je nepochybně nejjednodušším způsobem, jak začít s klientskou knihovnou Azure Identity, ale s tím, že pohodlí přináší kompromisy. Po nasazení aplikace do Azure byste měli porozumět požadavkům na ověřování aplikace. Z tohoto důvodu nahraďte DefaultAzureCredential konkrétní implementací TokenCredential, například ManagedIdentityCredential.

Tady je důvod:

• Výzvy při ladění: Při selhání ověřování může být náročné ladit a identifikovat chybné přihlašovací údaje. Abyste viděli průběh z jednoho pověření na další a stav úspěchu/selhání každého z nich, musíte povolit protokolování. Další informace naleznete v tématu Ladění zřetězených přihlašovacích údajů.
• Výkonová režie: Proces postupného zkoušení více přihlašovacích údajů může představovat výkonovou režii. Například při spuštění na místním vývojovém počítači není spravovaná identita k dispozici. V důsledku toho ManagedIdentityCredential vždy selže v místním vývojovém prostředí.
• Nepředvídatelné chování: DefaultAzureCredential kontroluje přítomnost určitých proměnných prostředí. Je možné, že někdo může přidat nebo upravit tyto proměnné prostředí na úrovni systému na hostitelském počítači. Tyto změny platí globálně a proto mění chování DefaultAzureCredential za běhu v libovolné aplikaci spuštěné na tomto počítači.

Odladění zřetězených přihlašovacích údajů

Pokud chcete diagnostikovat neočekávaný problém nebo zjistit, co dělá zřetězený přihlašovací údaj, povolte protokolování v aplikaci. Pro ilustraci předpokládejme, že je použita forma DefaultAzureCredential bez parametrů k ověření požadavku na účet Blob Storage. Aplikace běží v místním vývojovém prostředí a vývojář se ověřil v Azure pomocí Azure CLI. Při spuštění aplikace se ve výstupu zobrazí následující relevantní položky:

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.

V předchozím výstupu si všimněte, že:

• EnvironmentCredential, WorkloadIdentityCredential a ManagedIdentityCredential se nepodařilo každému z nich získat přístupový token Microsoft Entra v daném pořadí.
• ManagedIdentityCredential uspěje, jak je uvedeno v položce, která začíná "Successfully got token from ManagedIdentityCredential".