Cadeias de credenciais na biblioteca Azure Identity para Java

A biblioteca Azure Identity fornece classes públicas credentials — 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 de 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

Há duas abordagens diferentes para 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.

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:

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

Para usar um nome de variável de ambiente personalizado em vez do padrão AZURE_TOKEN_CREDENTIALS, use AzureIdentityEnvVars.fromString() para criar uma referência à variável personalizada:

DefaultAzureCredential credential = new DefaultAzureCredentialBuilder()
    .requireEnvVars(AzureIdentityEnvVars.fromString("MY_CUSTOM_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 ao definir AZURE_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

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

Diretrizes de uso para DefaultAzureCredential

DefaultAzureCredential é, sem dúvida, a maneira mais fácil de começar a usar a biblioteca Azure Identity, mas com essa conveniência vem as compensações. Depois de implantar seu aplicativo em Azure, você deve entender os requisitos de autenticação do aplicativo e considerar se DefaultAzureCredential é apropriado para seu cenário.

DefaultAzureCredential oferece um benefício fundamental: ele separa o código do aplicativo de mecanismos de autenticação específicos, permitindo que você altere sua configuração de autenticação sem modificar o código. Para desenvolvedores experientes que configuram conscientemente sua autenticação de produção, essa flexibilidade pode ser valiosa. No entanto, essa flexibilidade vem com possíveis desvantagens:

• 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.
• Unpredictable behavior: 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.
• Desajustes de permissão: DefaultAzureCredential interrompe-se na primeira credencial que obtém um token com sucesso, independentemente de essa credencial ter as permissões corretas. Por exemplo, uma credencial de desenvolvimento local pode ter permissões mais amplas do que a identidade gerenciada de produção, fazendo com que o aplicativo funcione localmente, mas falha nas verificações de autorização após a implantação.

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 ilustrativos, suponha que a forma sem parâmetros de DefaultAzureCredential seja usada para autenticar uma solicitação em uma conta Blob Storage. O aplicativo é executado no ambiente de desenvolvimento local e o desenvolvedor autenticado para Azure usando o Azure CLI. 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 não conseguiu adquirir um token de acesso 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.