Referentieketens in de Azure Identity-clientbibliotheek voor C++

De Azure Identity-clientbibliotheek biedt referentiemiddelen—openbare typen die zijn afgeleid van de TokenCredential abstracte basisklasse van de Azure Core-bibliotheek. Een inloggegeven vertegenwoordigt een afzonderlijk verificatieproces voor het verkrijgen van een toegangstoken van Microsoft Entra ID. Deze referenties kunnen worden gekoppeld om een geordende reeks verificatiemechanismen te vormen die moeten worden geprobeerd.

Hoe een gekoppelde inloggegevens werkt

Tijdens runtime probeert een referentieketen te verifiëren met behulp van de eerste referentie van de reeks. Als deze referentie geen toegangstoken kan verkrijgen, wordt de volgende referentie in de reeks geprobeerd, enzovoort, totdat een toegangstoken is verkregen. In het volgende sequentiediagram ziet u dit gedrag:

Waarom referentieketens gebruiken?

Een gekoppelde geloofsbrief kan de volgende voordelen bieden:

• Omgevingsbewustzijn: selecteert automatisch de meest geschikte referentie op basis van de omgeving waarin de app wordt uitgevoerd. Zonder deze code moet u als volgt code schrijven:

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

• Naadloze overgangen: uw app kan overstappen van lokale ontwikkeling naar uw faserings- of productieomgeving zonder verificatiecode te wijzigen.

• Verbeterde tolerantie: bevat een terugvalmechanisme dat overgaat naar de volgende inloggegevens wanneer de vorige geen toegangstoken verkrijgt.

Hoe een gekoppelde referentie te kiezen

Met C++zijn er twee opties voor het koppelen van referenties:

• Een vooraf geconfigureerde keten gebruiken: gebruik de vooraf geconfigureerde keten die door het DefaultAzureCredential type is geïmplementeerd. Raadpleeg de sectie DefaultAzureCredential-overzicht voor deze aanpak.
• Een aangepaste referentieketen bouwen: Begin met een lege keten en neem alleen op wat u nodig hebt. Zie de sectie ChainedTokenCredential-overzicht voor deze benadering.

Overzicht van DefaultAzureCredential

DefaultAzureCredential is een weloverwogen, vooraf geconfigureerde keten van referenties. Het ontwerp ondersteunt veel omgevingen, samen met de meest voorkomende verificatiestromen en ontwikkelhulpprogramma's. In grafische vorm ziet de onderliggende keten er als volgt uit:

De volgorde waarin DefaultAzureCredential inloggegevens worden geprobeerd, is als volgt.

In de eenvoudigste vorm kunt u de parameterloze versie van DefaultAzureCredential als volgt gebruiken:

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

Hoe pas je DefaultAzureCredential aan

In de volgende secties worden strategieën beschreven voor het beheren van welke referenties in de keten zijn opgenomen.

Een categorie referentietype uitsluiten

Als u alle Developer tool of Deployed service referenties wilt uitsluiten, stelt u de omgevingsvariabele AZURE_TOKEN_CREDENTIALSprod in op respectievelijk dev. Wanneer een waarde van prod wordt gebruikt, ziet de onderliggende referentieketen er als volgt uit:

Wanneer een waarde van dev wordt gebruikt, omvat de keten alleen AzureCliCredential.

Om ervoor te zorgen dat de omgevingsvariabele is gedefinieerd en ingesteld op een ondersteunde tekenreeks, geeft true u deze door aan de DefaultAzureCredential constructor:

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

Een specifieke referentie gebruiken

Als u alle referenties behalve één wilt uitsluiten, stelt u de omgevingsvariabele AZURE_TOKEN_CREDENTIALS in op de naam van de referentie. U kunt bijvoorbeeld de keten beperken door deze DefaultAzureCredential in te stellen AzureCliCredential op AZURE_TOKEN_CREDENTIALS.AzureCliCredential De tekenreeksvergelijking wordt op een niet-hoofdlettergevoelige manier uitgevoerd. Geldige tekenreekswaarden voor de omgevingsvariabele zijn:

• AzureCliCredential
• EnvironmentCredential
• ManagedIdentityCredential
• WorkloadIdentityCredential

Om ervoor te zorgen dat de omgevingsvariabele is gedefinieerd en ingesteld op een ondersteunde tekenreeks, geeft true u deze door aan de DefaultAzureCredential constructor:

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

Overzicht ChainedTokenCredential

ChainedTokenCredential is een lege keten waaraan u referentiegegevens toevoegt om aan de behoeften van uw app te voldoen. Voorbeeld:

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

In het voorgaande codevoorbeeld wordt een aangepaste referentieketen gemaakt die bestaat uit twee referenties. ManagedIdentityCredential wordt eerst geprobeerd, gevolgd door AzureCliCredential, indien nodig. In grafische vorm ziet de keten er als volgt uit:

Gebruiksrichtlijnen voor DefaultAzureCredential

DefaultAzureCredential is ongetwijfeld de eenvoudigste manier om aan de slag te gaan met de Azure Identity-clientbibliotheek, maar met dat gemak komen ook compromissen. Zodra u uw app in Azure hebt geïmplementeerd, moet u de verificatievereisten van de app begrijpen. Vervang daarom DefaultAzureCredential door een specifieke TokenCredential-implementatie, zoals ManagedIdentityCredential.

Dit is de reden waarom:

• Problemen met foutopsporing: wanneer de verificatie mislukt, kan het lastig zijn om fouten op te sporen en de foutopsporingsreferentie te identificeren. U moet logboekregistratie inschakelen om de voortgang te zien van de ene referentie naar de volgende en de succes-/foutstatus van elke referentie. Zie Fouten opsporen in een gekoppelde referentievoor meer informatie.
• Prestatieoverhead: het proces waarbij meerdere referenties opeenvolgend worden geprobeerd, kan leiden tot prestatieoverhead. Wanneer bijvoorbeeld een lokale ontwikkelcomputer wordt gebruikt, is een beheerde identiteit niet beschikbaar. ManagedIdentityCredential mislukt daarom altijd in de lokale ontwikkelomgeving.
• Onvoorspelbaar gedrag: DefaultAzureCredential controleert op de aanwezigheid van bepaalde omgevingsvariabelen. Het is mogelijk dat iemand deze omgevingsvariabelen kan toevoegen of wijzigen op systeemniveau op de hostcomputer. Deze wijzigingen zijn globaal van toepassing en wijzigen daarom het gedrag van DefaultAzureCredential tijdens runtime in elke app die op die computer wordt uitgevoerd.

Fouten opsporen in een gekoppeld toegangsbewijs

Als u een onverwacht probleem wilt vaststellen of wilt weten wat een gekoppelde referentie doet, schakelt u logboekregistratie in uw app in. Voor illustratiedoeleinden wordt ervan uitgegaan dat de parameterloze vorm van wordt gebruikt voor het verifiëren van DefaultAzureCredential een aanvraag voor een Blob Storage-account. De app draait in de lokale ontwikkelomgeving en de ontwikkelaar heeft zich geverifieerd bij Azure met de Azure CLI. Wanneer de app wordt uitgevoerd, worden de volgende relevante vermeldingen weergegeven in de uitvoer:

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.

In de voorgaande uitvoer ziet u dat:

• EnvironmentCredential, WorkloadIdentityCredentialen ManagedIdentityCredential elk kan in die volgorde geen Microsoft Entra-toegangstoken verkrijgen.
• ManagedIdentityCredential is succesvol, zoals blijkt uit een vermelding die begint met 'Successfully got token from ManagedIdentityCredential'.