Cadeias de credenciais na biblioteca de Identidade do Azure para Java

A biblioteca de identidade do Azure fornece credenciais—classes públicas que implementam a interface 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 a execução, uma cadeia de credenciais tenta se 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:

• 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:

  import com.azure.core.credential.TokenCredential;
  import com.azure.identity.AzureCliCredentialBuilder;
  import com.azure.identity.ManagedIdentityCredentialBuilder;
  
  // Code omitted for brevity
  
  TokenCredential credential = null;
  
  // Set up credential based on environment (Azure or local development)
  String environment = System.getenv("ENV");
  
  if (environment != null && environment.equals("production")) {
      credential = new ManagedIdentityCredentialBuilder()
          .clientId(userAssignedClientId)
          .build();
  } else {
      credential = new AzureCliCredentialBuilder()
          .build();
  }
  

• 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:

• Use uma cadeia pré-configurada: comece com uma cadeia opinativa e pré-construída que acomode os cenários de autenticação mais comuns. Para essa abordagem, consulte a seção Visão geral do DefaultAzureCredential.
• "Monte" uma cadeia: comece com uma cadeia 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 em que DefaultAzureCredential tenta credenciais é a seguinte.

Pedido	Credencial	Descrição
1	Ambiente	Lê uma coleção de variáveis de ambiente para determinar se uma entidade de serviço de aplicativo (usuário do aplicativo) está configurada para o aplicativo. Nesse caso, DefaultAzureCredential usa esses valores para autenticar o aplicativo no Azure. Esse método geralmente é 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 de 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	IntelliJ	Se o desenvolvedor tiver sido autenticado por meio do Azure Toolkit for IntelliJ, autentique essa conta.
5	Código do Visual Studio	Se o desenvolvedor for autenticado por meio da extensão de Recursos do Azure do Visual Studio Code e o pacote do agente de identidade do Azure estiver instalado, autentique essa conta.
6	CLI do Azure	Se o desenvolvedor tiver se autenticado no Azure usando o comando da CLI do Azure az login, autentique o aplicativo no Azure usando essa mesma conta.
7	Azure PowerShell	Se o desenvolvedor tiver sido autenticado no Azure usando o cmdlet do Azure PowerShell Connect-AzAccount, autentique o aplicativo no Azure usando essa mesma conta.
oito	CLI do Azure para Desenvolvedores	Se o desenvolvedor tiver se autenticado no Azure usando o comando da CLI do Desenvolvedor do Azure azd auth login, autentique-se com essa conta.
9	Broker	Autentica usando a conta padrão logada no sistema operacional por meio de um intermediário. Requer que o pacote azure-identity-broker esteja instalado, uma vez que uma instância habilitada para broker do InteractiveBrowserCredential é utilizada.

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

import com.azure.identity.DefaultAzureCredential;
import com.azure.identity.DefaultAzureCredentialBuilder;

// Code omitted for brevity

DefaultAzureCredential credential = new DefaultAzureCredentialBuilder()
    .build();

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 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:

Importante

A AZURE_TOKEN_CREDENTIALS variável de ambiente tem suporte nas azure-identity versões de pacote 1.16.1 e posteriores.

Para garantir que a variável de ambiente seja definida e definida como uma cadeia de caracteres com suporte, chame o método requireEnvVars da seguinte maneira:

DefaultAzureCredential credential = new DefaultAzureCredentialBuilder()
    .requireEnvVars(AzureIdentityEnvVars.AZURE_TOKEN_CREDENTIALS)
    .build();

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 definindo AzureCliCredentialAZURE_TOKEN_CREDENTIALS como AzureCliCredential. 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
• EnvironmentCredential
• IntelliJCredential
• ManagedIdentityCredential
• VisualStudioCodeCredential
• WorkloadIdentityCredential

Importante

A AZURE_TOKEN_CREDENTIALS variável de ambiente dá suporte a nomes de credenciais individuais nas azure-identity versões de pacote 1.17.0 e posteriores.

Para garantir que a variável de ambiente seja definida e atribuída a uma string compatível, chame o método requireEnvVars da seguinte maneira:

DefaultAzureCredential credential = new DefaultAzureCredentialBuilder()
    .requireEnvVars(AzureIdentityEnvVars.AZURE_TOKEN_CREDENTIALS)
    .build();

Visão geral do ChainedTokenCredential

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

import com.azure.identity.AzureCliCredential;
import com.azure.identity.AzureCliCredentialBuilder;
import com.azure.identity.ChainedTokenCredential;
import com.azure.identity.ChainedTokenCredentialBuilder;
import com.azure.identity.IntelliJCredential;
import com.azure.identity.IntelliJCredentialBuilder;

// Code omitted for brevity

AzureCliCredential cliCredential = new AzureCliCredentialBuilder()
    .build();
IntelliJCredential ijCredential = new IntelliJCredentialBuilder()
    .build();

ChainedTokenCredential credential = new ChainedTokenCredentialBuilder()
    .addLast(cliCredential)
    .addLast(ijCredential)
    .build();

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

Dica

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

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 desvantagens. 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.

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.
• 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.

Depurar uma credencial encadeada

Para diagnosticar um problema inesperado ou entender o que uma credencial encadeada está fazendo, habilite o logging no seu aplicativo.

Para fins de ilustração, suponha que a forma sem parâmetros de DefaultAzureCredential seja utilizada para autenticar um pedido a uma conta de armazenamento de blobs. 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:

[main] INFO com.azure.identity.ChainedTokenCredential - Azure Identity => Attempted credential EnvironmentCredential is unavailable.
[main] INFO com.azure.identity.ChainedTokenCredential - Azure Identity => Attempted credential WorkloadIdentityCredential is unavailable.
[ForkJoinPool.commonPool-worker-1] WARN com.microsoft.aad.msal4j.ConfidentialClientApplication - [Correlation ID: aaaa0000-bb11-2222-33cc-444444dddddd] Execution of class com.microsoft.aad.msal4j.AcquireTokenByClientCredentialSupplier failed: java.util.concurrent.ExecutionException: com.azure.identity.CredentialUnavailableException: ManagedIdentityCredential authentication unavailable. Connection to IMDS endpoint cannot be established.
[main] INFO com.azure.identity.ChainedTokenCredential - Azure Identity => Attempted credential ManagedIdentityCredential is unavailable.
[main] INFO com.azure.identity.ChainedTokenCredential - Azure Identity => Attempted credential IntelliJCredential is unavailable.
[main] INFO com.azure.identity.ChainedTokenCredential - Azure Identity => Attempted credential VisualStudioCodeCredential is unavailable.
[main] INFO com.azure.identity.ChainedTokenCredential - Azure Identity => Attempted credential AzureCliCredential returns a token

Na saída anterior, observe que:

• EnvironmentCredential, WorkloadIdentityCredential, ManagedIdentityCredential, IntelliJCredential e VisualStudioCodeCredential cada um falhou ao adquirir um token de acesso do Microsoft Entra, nessa ordem.
• A chamada AzureCliCredential.getToken é bem-sucedida, conforme indicado pela entrada com o sufixo returns a token. Desde que AzureCliCredential foi bem-sucedido, não foram tentadas outras credenciais para além desta.