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

• Reconhecimento do ambiente: seleciona automaticamente a credencial mais apropriada com base no ambiente no qual 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 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

Existem duas filosofias diferentes para o encadeamento de credenciais:

• Use uma cadeia pré-configurada: comece com uma cadeia opinativa e pré-construída que acomoda os cenários de autenticação mais comuns. Para essa abordagem, consulte a secção Visão geral do DefaultAzureCredential.
• "Construa" uma cadeia: comece com uma cadeia vazia e inclua apenas o que você precisa. Para essa abordagem, consulte a seção Visão geral de ChainedTokenCredential.

Visão geral de DefaultAzureCredential

DefaultAzureCredential é uma cadeia de credenciais opinativa e pré-configurada. Ele foi projetado para suportar 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.

Ordenar	Credencial	Descrição
1	Ambiente	Lê uma coleção de variáveis de ambiente para determinar se uma entidade de aplicação (usuário da aplicação) está configurada para o aplicativo. 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 Gerida	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 se autenticou por meio do Kit de Ferramentas do Azure para IntelliJ, autentique essa conta.
5	Código do Visual Studio	Se o desenvolvedor autenticado por meio da extensão Recursos do Azure do Visual Studio Code e o pacote azure-identity-broker estiver instalado, autentique essa conta.
6	CLI do Azure	Se o desenvolvedor se autenticou no Azure usando o comando da CLI do az login Azure, autentique o aplicativo no Azure usando essa mesma conta.
7	Azure PowerShell	Se o desenvolvedor se autenticou no Azure usando o cmdlet do Connect-AzAccount Azure PowerShell, autentique o aplicativo no Azure usando essa mesma conta.
8	CLI do desenvolvedor do Azure	Se o desenvolvedor se autenticou no Azure usando o comando da CLI do azd auth login Azure Developer, autentique-se com essa conta.
9	Broker	Autentica usando a conta padrão conectada ao sistema operacional por meio de um broker. Requer que o pacote azure-identity-broker esteja instalado, uma vez que uma instância habilitada para broker de InteractiveBrowserCredential é usada.

Em sua forma mais simples, você pode usar a versão sem parâmetros da DefaultAzureCredential 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 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 tem a seguinte aparência:

Importante

A AZURE_TOKEN_CREDENTIALS variável de ambiente é suportada 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 suportada, 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 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
• AzureDeveloperCliCredential
• AzurePowerShellCredential
• EnvironmentCredential
• IntelliJCredential
• ManagedIdentityCredential
• VisualStudioCodeCredential
• WorkloadIdentityCredential

Importante

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

Para garantir que a variável de ambiente esteja definida e configurada como uma string suportada, chame o método requireEnvVars da seguinte forma:

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

Visão geral de 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 por duas credenciais de desenvolvimento. AzureCliCredential é tentado primeiro, seguido de IntelliJCredential, se necessário. Em forma gráfica, a cadeia tem esta aparência:

Gorjeta

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 Identidade do Azure, mas essa conveniência traz consigo alguns compromissos. 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 difícil 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 em cadeia.
• 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:

[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, , IntelliJCredentiale VisualStudioCodeCredential cada um não conseguiu adquirir um token de acesso do Microsoft Entra, nessa ordem.
• A chamada AzureCliCredential.getToken é bem-sucedida, conforme indicado pela entrada com sufixo -returns a token. Desde que AzureCliCredential teve sucesso, nenhuma outra credencial foi tentada.