Cadeias de credenciais na biblioteca de identidades do Azure para .NET

A biblioteca de Identidades do Azure fornece credenciais, classes públicas derivadas da classe 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

No tempo de execução, uma cadeia de credenciais tenta autenticar usando 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:

• Reconhecimento de ambiente: seleciona automaticamente a credencial mais apropriada com base no ambiente em que o aplicativo está sendo executado. Sem ele, você teria que escrever um código como este:

  TokenCredential credential;
  
  if (app.Environment.IsProduction() || app.Environment.IsStaging())
  {
      credential = new ManagedIdentityCredential(
          ManagedIdentityId.FromUserAssignedClientId(userAssignedClientId));
  }
  else
  {
      // local development environment
      credential = new VisualStudioCredential();
  }
  

• Transições perfeitas: seu aplicativo pode passar do desenvolvimento local para o ambiente de preparo 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 a anterior não consegue adquirir um token de acesso.

Como escolher uma credencial encadeada

Existem duas filosofias diferentes para o encadeamento de credenciais:

• "Destruir" uma cadeia: comece com uma cadeia pré-configurada e exclua o que você não precisa. Para essa abordagem, consulte a seção Visão geral do DefaultAzureCredential.
• "Construa" uma corrente: comece com uma corrente vazia e inclua apenas o que você precisa. Para essa abordagem, consulte a seção Visão geral do ChainedTokenCredential.

Visão geral do DefaultAzureCredential

DefaultAzureCredential é uma cadeia de credenciais opinativa e pré-configurada. Ele foi projetado para dar suporte a muitos ambientes, juntamente com os fluxos de autenticação e ferramentas de desenvolvedor mais comuns. Em forma gráfica, a cadeia subjacente se parece com isso:

A ordem na qual as credenciais de tentativas DefaultAzureCredential seguem.

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

builder.Services.AddAzureClients(clientBuilder =>
{
    clientBuilder.AddSecretClient(
        new Uri($"https://{keyVaultName}.vault.azure.net"));
    clientBuilder.AddBlobServiceClient(
        new Uri($"https://{storageAccountName}.blob.core.windows.net"));

    DefaultAzureCredential credential = new();
    clientBuilder.UseCredential(credential);
});

Como personalizar DefaultAzureCredential

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

Excluir uma credencial individual

Para excluir uma credencial individual do DefaultAzureCredential, use a propriedade correspondente com o prefixo Exclude em DefaultAzureCredentialOptions. Por exemplo:

builder.Services.AddAzureClients(clientBuilder =>
{
    clientBuilder.AddSecretClient(
        new Uri($"https://{keyVaultName}.vault.azure.net"));
    clientBuilder.AddBlobServiceClient(
        new Uri($"https://{storageAccountName}.blob.core.windows.net"));

    clientBuilder.UseCredential(new DefaultAzureCredential(
        new DefaultAzureCredentialOptions
        {
            ExcludeEnvironmentCredential = true,
            ExcludeManagedIdentityCredential = true,
            ExcludeWorkloadIdentityCredential = true,
        }));
});

No exemplo de código anterior, EnvironmentCredentiale ManagedIdentityCredentialWorkloadIdentityCredential são removidos da cadeia de credenciais. Como resultado, a primeira credencial a ser tentada é VisualStudioCredential. A cadeia modificada contém apenas credenciais de fase de desenvolvimento e se parece com isto:

À medida que mais Excludepropriedades prefixadas são definidas como true (exclusões de credenciais são configuradas), as vantagens de usar DefaultAzureCredential diminuem. Nesses casos, ChainedTokenCredential é uma escolha melhor e requer menos código. Para ilustrar, esses dois exemplos de código se comportam da mesma maneira:

credential = new DefaultAzureCredential(
    new DefaultAzureCredentialOptions
    {
        ExcludeEnvironmentCredential = true,
        ExcludeWorkloadIdentityCredential = true,
        ExcludeManagedIdentityCredential = true,
        ExcludeVisualStudioCodeCredential = true,
        ExcludeAzurePowerShellCredential = true,
        ExcludeAzureDeveloperCliCredential = true,
        ExcludeBrokerCredential = true,
    });

credential = new ChainedTokenCredential(
    new VisualStudioCredential(),
    new AzureCliCredential());

Excluir uma categoria de tipo de credencial

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

Quando um valor é dev usado, a cadeia tem a seguinte aparência:

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 VisualStudioCredential ao definir AZURE_TOKEN_CREDENTIALS como VisualStudioCredential. A comparação de cadeia de caracteres é executada 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
• AzureDeveloperCliCredential
• AzurePowerShellCredential
• BrokerCredential
• EnvironmentCredential
• InteractiveBrowserCredential
• ManagedIdentityCredential
• VisualStudioCredential
• VisualStudioCodeCredential
• WorkloadIdentityCredential

Visão geral do ChainedTokenCredential

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

builder.Services.AddAzureClients(clientBuilder =>
{
    clientBuilder.AddSecretClient(
        new Uri($"https://{keyVaultName}.vault.azure.net"));
    clientBuilder.AddBlobServiceClient(
        new Uri($"https://{storageAccountName}.blob.core.windows.net"));

    clientBuilder.UseCredential(new ChainedTokenCredential(
        new AzurePowerShellCredential(),
        new VisualStudioCredential()));
});

O exemplo de código anterior cria uma cadeia de credenciais personalizada composta de duas credenciais de tempo de desenvolvimento. AzurePowerShellCredential é tentado primeiro, seguido por VisualStudioCredential, se necessário. Em forma gráfica, a cadeia se parece com isso:

Diretrizes de uso para DefaultAzureCredential

DefaultAzureCredential é, sem dúvida, a maneira mais fácil de começar a usar a biblioteca de Identidades do Azure, mas com essa conveniência vêm 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. Confira a lista derivada para opções.

Eis o motivo:

• Desafios de depuração: quando a autenticação falha, pode ser um desafio depurar e identificar a credencial ofensiva. Você deve habilitar o registro em log 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, ao executar em um computador de desenvolvimento local, a identidade gerenciada não está disponível. Consequentemente, ManagedIdentityCredential sempre falha no ambiente de desenvolvimento local, a menos que explicitamente desabilitado por meio de sua propriedade prefixada Exclude correspondente.
• 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 se aplicam globalmente e, portanto, alteram o comportamento de DefaultAzureCredential em tempo de execução em qualquer aplicativo em execução nesse computador. Para obter mais informações sobre a imprevisibilidade, consulte Usar credenciais determinísticas em ambientes de produção.

Depurar uma credencial encadeada

Para diagnosticar um problema inesperado ou entender o que uma credencial encadeada está fazendo, habilite o registro em log em seu aplicativo. Opcionalmente, filtre os logs apenas para os eventos emitidos da biblioteca de Identidades do Azure. Por exemplo:

using AzureEventSourceListener listener = new((args, message) =>
{
    if (args is { EventSource.Name: "Azure-Identity" })
    {
        Console.WriteLine(message);
    }
}, EventLevel.LogAlways);

Para fins de ilustração, suponha que a forma sem parâmetros de DefaultAzureCredential foi usada para autenticar uma solicitação em um workspace do Log Analytics. O aplicativo foi executado no ambiente de desenvolvimento local e o Visual Studio foi autenticado em uma conta do Azure. Na próxima vez que o aplicativo for executado, as seguintes entradas pertinentes aparecerão na saída:

DefaultAzureCredential.GetToken invoked. Scopes: [ https://api.loganalytics.io//.default ] ParentRequestId: d7ef15d1-50f8-451d-afeb-6b06297a3342
EnvironmentCredential.GetToken invoked. Scopes: [ https://api.loganalytics.io//.default ] ParentRequestId: d7ef15d1-50f8-451d-afeb-6b06297a3342
EnvironmentCredential.GetToken was unable to retrieve an access token. Scopes: [ https://api.loganalytics.io//.default ] ParentRequestId: d7ef15d1-50f8-451d-afeb-6b06297a3342 Exception: Azure.Identity.CredentialUnavailableException (0x80131500): EnvironmentCredential authentication unavailable. Environment variables are not fully configured. See the troubleshooting guide for more information. https://aka.ms/azsdk/net/identity/environmentcredential/troubleshoot
WorkloadIdentityCredential.GetToken invoked. Scopes: [ https://api.loganalytics.io//.default ] ParentRequestId: d7ef15d1-50f8-451d-afeb-6b06297a3342
WorkloadIdentityCredential.GetToken was unable to retrieve an access token. Scopes: [ https://api.loganalytics.io//.default ] ParentRequestId: d7ef15d1-50f8-451d-afeb-6b06297a3342 Exception: Azure.Identity.CredentialUnavailableException (0x80131500): WorkloadIdentityCredential authentication unavailable. The workload options are not fully configured. See the troubleshooting guide for more information. https://aka.ms/azsdk/net/identity/workloadidentitycredential/troubleshoot
ManagedIdentityCredential.GetToken invoked. Scopes: [ https://api.loganalytics.io//.default ] ParentRequestId: d7ef15d1-50f8-451d-afeb-6b06297a3342
ManagedIdentityCredential.GetToken was unable to retrieve an access token. Scopes: [ https://api.loganalytics.io//.default ] ParentRequestId: d7ef15d1-50f8-451d-afeb-6b06297a3342 Exception: Azure.Identity.CredentialUnavailableException (0x80131500): ManagedIdentityCredential authentication unavailable. No response received from the managed identity endpoint.
VisualStudioCredential.GetToken invoked. Scopes: [ https://api.loganalytics.io//.default ] ParentRequestId: d7ef15d1-50f8-451d-afeb-6b06297a3342
VisualStudioCredential.GetToken succeeded. Scopes: [ https://api.loganalytics.io//.default ] ParentRequestId: d7ef15d1-50f8-451d-afeb-6b06297a3342 ExpiresOn: 2024-08-13T17:16:50.8023621+00:00
DefaultAzureCredential credential selected: Azure.Identity.VisualStudioCredential
DefaultAzureCredential.GetToken succeeded. Scopes: [ https://api.loganalytics.io//.default ] ParentRequestId: d7ef15d1-50f8-451d-afeb-6b06297a3342 ExpiresOn: 2024-08-13T17:16:50.8023621+00:00

Na saída anterior, observe que:

• EnvironmentCredential, WorkloadIdentityCredential e ManagedIdentityCredential cada um falhou ao adquirir um token de acesso do Microsoft Entra, nessa ordem.
• A entrada prefixada DefaultAzureCredential credential selected: indica a credencial que foi selecionada —VisualStudioCredential nesse caso. Desde que VisualStudioCredential foi bem-sucedido, nenhuma credencial além dele foi usada.