Cadeias de credenciais na biblioteca de cliente do Azure Identity para C++

A biblioteca de cliente do Azure Identity fornece credenciais — tipos públicos que derivam da classe base abstrata TokenCredential da biblioteca do Azure Core. Uma credencial representa um fluxo de autenticação distinto para adquirir um token de acesso do Microsoft Entra ID. Essas credenciais podem ser encadeadas para formar uma sequência ordenada de mecanismos de autenticação a serem tentados.

Como funciona uma credencial encadeada

Durante o tempo de execução, uma cadeia de credenciais tenta autenticar utilizando a primeira credencial da sequência. Se essa credencial não conseguir adquirir um token de acesso, a próxima credencial na sequência será tentada, e assim por diante, até que um token de acesso seja obtido com êxito. O diagrama de sequência a seguir ilustra esse comportamento:

Por que usar cadeias de credenciais?

Uma credencial encadeada pode oferecer os seguintes benefícios:

• Perceção do ambiente: seleciona automaticamente a credencial mais apropriada com base no ambiente em que a aplicação está a ser executada. Sem ele, você teria que escrever um código como este:

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

• Transições perfeitas: seu aplicativo pode passar do desenvolvimento local para o ambiente de preparação ou produção sem alterar o código de autenticação.

• Resiliência aprimorada: inclui um mecanismo de fallback que se move para a próxima credencial quando o anterior não consegue adquirir um token de acesso.

Como escolher uma credencial encadeada

Com o C++, há duas opções para o encadeamento de credenciais:

• Utilize uma cadeia preconfigurada: Utilize a cadeia preconfigurada implementada pelo tipo DefaultAzureCredential. Para essa abordagem, consulte a secção Visão geral do DefaultAzureCredential.
• Crie uma cadeia de credenciais personalizada: comece com uma cadeia vazia e inclua apenas o que você precisa. Para esta abordagem, consulte a seção Visão geral de ChainedTokenCredential.

Visão geral de DefaultAzureCredential

DefaultAzureCredential é uma cadeia de credenciais opinativa e pré-configurada. Seu design suporta muitos ambientes, juntamente com os fluxos de autenticação mais comuns e ferramentas de desenvolvedor. Na forma gráfica, a cadeia subjacente tem esta aparência:

A ordem pela qual DefaultAzureCredential tenta as credenciais é a seguinte.

Encomenda	Credencial	Descrição
1	Ambiente	Lê uma coleção de variáveis de ambiente para determinar se um principal de serviço da aplicação (usuário da aplicação) está configurado para a aplicação. Em caso afirmativo, DefaultAzureCredential usa esses valores para autenticar o aplicativo no Azure. Este método é mais frequentemente usado em ambientes de servidor, mas também pode ser usado ao desenvolver localmente.
2	Identidade da carga de trabalho	Se o aplicativo for implantado em um host do Azure com a Identidade da Carga de Trabalho habilitada, autentique essa conta.
3	Identidade Gerenciada	Se o aplicativo for implantado em um host do Azure com a Identidade Gerenciada habilitada, autentique o aplicativo no Azure usando essa Identidade Gerenciada.
4	CLI do Azure	Se o desenvolvedor se autenticou no Azure usando o comando az login da CLI do Azure, autentique o aplicativo no Azure usando essa mesma conta.

Em sua forma mais simples, você pode usar a versão sem parâmetros do DefaultAzureCredential da seguinte maneira:

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

Como personalizar DefaultAzureCredential

As seções a seguir descrevem estratégias para controlar quais credenciais estão incluídas na cadeia.

Excluir uma categoria de tipo de credencial

Para excluir todas as Developer tool ou Deployed service credenciais, defina a variável de ambiente AZURE_TOKEN_CREDENTIALS como prod ou dev, respectivamente. Quando um valor de prod é utilizado, a cadeia de credenciais subjacente tem a seguinte aparência:

Quando um valor de dev é usado, a cadeia inclui AzureCliCredentialapenas .

Para garantir que a variável de ambiente seja definida e definida como uma cadeia de caracteres suportada, passe true para o DefaultAzureCredential construtor:

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

Importante

A sobrecarga do construtor acima mencionada é suportada nas azure-identity-cpp versões de pacote 1.13.1 e posteriores.

Usar uma credencial específica

Para excluir todas as credenciais, exceto uma, defina a variável AZURE_TOKEN_CREDENTIALS de ambiente como o nome da credencial. Por exemplo, você pode reduzir a DefaultAzureCredential cadeia para AzureCliCredential definindo AZURE_TOKEN_CREDENTIALS como AzureCliCredential. A comparação de cadeia de caracteres é realizada de maneira que não diferencia maiúsculas de minúsculas. Os valores de cadeia de caracteres válidos para a variável de ambiente incluem:

• AzureCliCredential
• EnvironmentCredential
• ManagedIdentityCredential
• WorkloadIdentityCredential

Para garantir que a variável de ambiente seja definida e definida como uma cadeia de caracteres suportada, passe true para o DefaultAzureCredential construtor:

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

Importante

A sobrecarga do construtor acima mencionada é suportada nas azure-identity-cpp versões de pacote 1.13.1 e posteriores.

Visão geral de ChainedTokenCredential

ChainedTokenCredential é uma cadeia vazia à qual você adiciona credenciais para atender às necessidades do seu aplicativo. Por exemplo:

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

O exemplo de código anterior cria uma cadeia de credenciais personalizada composta por duas credenciais. ManagedIdentityCredential é tentado primeiro, seguido de AzureCliCredential, se necessário. Em forma gráfica, a cadeia tem esta aparência:

Sugestão

Para melhorar o desempenho, otimize a ordenação de credenciais em ChainedTokenCredential da credencial mais para a menos usada.

Diretrizes de uso para DefaultAzureCredential

DefaultAzureCredential é, sem dúvida, a maneira mais fácil de começar a usar a biblioteca de cliente do Azure Identity, mas com essa conveniência surgem compensações. Depois de implantar seu aplicativo no Azure, você deve entender os requisitos de autenticação do aplicativo. Por esse motivo, substitua DefaultAzureCredential por uma implementação TokenCredential específica, como ManagedIdentityCredential.

Aqui está o porquê:

• Desafios de depuração: Quando a autenticação falha, pode ser um desafio depurar e identificar a credencial infratora. Você deve habilitar o registro para ver a progressão de uma credencial para a próxima e o status de sucesso/falha de cada uma. Para obter mais informações, consulte Depurar uma credencial encadeada.
• Sobrecarga de desempenho: o processo de tentar sequencialmente várias credenciais pode introduzir sobrecarga de desempenho. Por exemplo, quando executado em uma máquina de desenvolvimento local, a identidade gerenciada não está disponível. Consequentemente, ManagedIdentityCredential falha sempre no ambiente de desenvolvimento local.
• Comportamento imprevisível: DefaultAzureCredential verifica a presença de determinadas variáveis de ambiente. É possível que alguém possa adicionar ou modificar essas variáveis de ambiente no nível do sistema na máquina host. Essas alterações aplicam-se globalmente e, portanto, alteram o comportamento de DefaultAzureCredential em tempo de execução em qualquer aplicação em execução nessa máquina.

Depurar uma credencial encadeada

Para diagnosticar um problema inesperado ou entender o que uma credencial encadeada está a fazer, habilite o registo de atividade na sua aplicação. Para fins de ilustração, suponha que a forma sem parâmetros de DefaultAzureCredential seja usada para autenticar um pedido a uma conta de Blob Storage. O aplicativo é executado no ambiente de desenvolvimento local e o desenvolvedor autenticado no Azure usando a CLI do Azure. Quando o aplicativo é executado, as seguintes entradas pertinentes aparecem na saída:

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.

Na saída anterior, observe que:

• EnvironmentCredential, WorkloadIdentityCredentiale ManagedIdentityCredential cada um não conseguiu adquirir um token de acesso do Microsoft Entra, nessa ordem.
• ManagedIdentityCredential é bem-sucedida, conforme indicado por uma entrada que começa com "Successfully got token from ManagedIdentityCredential".