Autentiseringskedjor i Azure Identity-klientbiblioteket för C++

Azure Identity-klientbiblioteket innehåller autentiseringsuppgifter – offentliga typer som härleds från Azure Core-bibliotekets abstrakta basklass TokenCredential . En autentiseringsuppgift representerar ett distinkt autentiseringsflöde för att hämta en åtkomsttoken från Microsoft Entra-ID. Dessa autentiseringsuppgifter kan kopplas samman för att bilda en ordnad sekvens med autentiseringsmekanismer som ska försökas.

Så här fungerar en länkad autentiseringsuppgift

Vid körning försöker en autentiseringskedja autentisera med sekvensens första autentiseringsuppgifter. Om det misslyckas att erhålla en åtkomsttoken prövas nästa referens i sekvensen och så vidare, tills en åtkomsttoken framgångsrikt har erhållits. Följande sekvensdiagram illustrerar det här beteendet:

Varför ska du använda autentiseringskedjor?

En länkad autentiseringsuppgift kan erbjuda följande fördelar:

• Miljömedvetenhet: Väljer automatiskt de lämpligaste autentiseringsuppgifterna baserat på miljön där appen körs. Utan den skulle du behöva skriva kod så här:

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

• Sömlösa övergångar: Din app kan gå från lokal utveckling till mellanlagrings- eller produktionsmiljön utan att ändra autentiseringskoden.

• Förbättrad återhämtning: Innehåller en återställningsmekanism som flyttas till nästa autentiseringsuppgift när den föregående misslyckas med att hämta en åtkomsttoken.

Så här väljer du en länkad autentiseringsuppgift

Med C++finns det två alternativ för autentiseringslänkning:

• Använd en förkonfigurerad kedja: Använd den förkonfigurerade kedjan som implementeras av DefaultAzureCredential typ. För denna metod, se avsnittet DefaultAzureCredential-översikt.
• Skapa en anpassad autentiseringskedja: Börja med en tom kedja och inkludera bara det du behöver. Den här metoden finns i översiktsavsnittet ChainedTokenCredential.

Översikt över DefaultAzureCredential

DefaultAzureCredential är en åsiktsbaserad, förkonfigurerad kedja med autentiseringsuppgifter. Dess design stöder många miljöer, tillsammans med de vanligaste autentiseringsflödena och utvecklarverktygen. I grafisk form ser den underliggande kedjan ut så här:

Den ordning i vilken DefaultAzureCredential försöker att använda autentiseringsuppgifterna följer.

I sin enklaste form kan du använda den parameterlösa versionen av DefaultAzureCredential på följande sätt:

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

Så här anpassar du DefaultAzureCredential

I följande avsnitt beskrivs strategier för att kontrollera vilka autentiseringsuppgifter som ingår i kedjan.

Exkludera en kategori för autentiseringsuppgifter

Om du vill exkludera alla Developer tool eller Deployed service autentiseringsuppgifter anger du miljövariabeln AZURE_TOKEN_CREDENTIALS till prod respektive dev. När ett värde prod för används ser den underliggande autentiseringskedjan ut så här:

När ett värde på dev används, innehåller kedjan endast AzureCliCredential.

För att säkerställa att miljövariabeln har definierats och angetts till en sträng som stöds skickar du trueDefaultAzureCredential till konstruktorn:

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

Använda en specifik autentiseringsuppgift

Om du vill exkludera alla autentiseringsuppgifter förutom en anger du miljövariabeln AZURE_TOKEN_CREDENTIALS till namnet på autentiseringsuppgifterna. Du kan till exempel minska DefaultAzureCredential kedjan till genom att AzureCliCredential ange AZURE_TOKEN_CREDENTIALS till AzureCliCredential. Strängjämförelsen utförs på ett skiftlägesokänsligt sätt. Giltiga strängvärden för miljövariabeln är:

• AzureCliCredential
• EnvironmentCredential
• ManagedIdentityCredential
• WorkloadIdentityCredential

För att säkerställa att miljövariabeln har definierats och angetts till en sträng som stöds skickar du trueDefaultAzureCredential till konstruktorn:

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

Översikt över ChainedTokenCredential

ChainedTokenCredential är en tom kedja som du lägger till autentiseringsuppgifter till för att passa appens behov. Till exempel:

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

Föregående kodexempel skapar en anpassad autentiseringskedja som består av två autentiseringsuppgifter. ManagedIdentityCredential försöks först, följt av AzureCliCredential, om det behövs. I grafisk form ser kedjan ut så här:

Användningsvägledning för DefaultAzureCredential

DefaultAzureCredential är utan tvekan det enklaste sättet att komma igång med Azure Identity-klientbiblioteket, men med den bekvämligheten kommer kompromisser. När du har distribuerat din app till Azure bör du förstå appens autentiseringskrav. Därför ersätter du DefaultAzureCredential med en specifik TokenCredential implementering, till exempel ManagedIdentityCredential.

Här är varför:

• Felsökningsutmaningar: När autentiseringen misslyckas kan det vara svårt att felsöka och identifiera de felaktiga autentiseringsuppgifterna. Du måste aktivera loggning för att se övergången från ett autentiseringsuppgifter till nästa och se statusen för var och en, om det lyckas eller misslyckas. Mer information finns i Felsöka en länkad autentiseringsuppgift.
• Prestandakostnader: Processen med att sekventiellt prova flera autentiseringsuppgifter kan medföra prestandakostnader. När den till exempel körs på en lokal utvecklingsdator är den hanterade identiteten inte tillgänglig. Därför ManagedIdentityCredential misslyckas alltid i den lokala utvecklingsmiljön.
• Oförutsägbart beteende: DefaultAzureCredential söker efter förekomsten av vissa miljövariabler. Det är möjligt att någon kan lägga till eller ändra dessa miljövariabler på systemnivå på värddatorn. Dessa ändringar gäller globalt och ändrar därför beteendet för DefaultAzureCredential vid körning i alla appar som körs på den datorn.

Felsöka en länkad autentiseringsuppgift

Om du vill diagnostisera ett oväntat problem eller förstå vad en länkad autentiseringsuppgift gör aktiverar du loggning i din app. I illustrationssyfte förutsätter vi att den parameterlösa formen av DefaultAzureCredential används för att autentisera en begäran till ett Blob Storage-konto. Appen körs i den lokala utvecklingsmiljön och utvecklaren autentiseras till Azure med hjälp av Azure CLI. När appen körs visas följande relevanta poster i utdata:

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.

Observera följande i föregående utdata:

• EnvironmentCredential, WorkloadIdentityCredentialoch ManagedIdentityCredential kunde inte hämta en Microsoft Entra-åtkomsttoken i den ordningen.
• ManagedIdentityCredential lyckas, vilket anges av en post som börjar med "Successfully got token from ManagedIdentityCredential".