Cadeias de credenciais na biblioteca de cliente do Azure Identity para Java

A biblioteca de cliente do Azure Identity fornece credenciais — classes públicas que implementam a interface TokenCredential da biblioteca 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 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 seção Visão geral de 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 em que DefaultAzureCredential as credenciais de tentativa seguem.

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

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.ManagedIdentityCredential;
import com.azure.identity.ManagedIdentityCredentialBuilder;

// Code omitted for brevity

ManagedIdentityCredential miCredential = new ManagedIdentityCredentialBuilder()
    .clientId(userAssignedClientId)
    .build();
AzureCliCredential cliCredential = new AzureCliCredentialBuilder()
    .build();

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

O exemplo de código anterior cria uma cadeia de credenciais personalizada composta por duas credenciais. A variante de identidade gerenciada atribuída pelo usuário é tentada ManagedIdentityCredential primeiro, seguida por AzureCliCredential, se necessário. Em forma gráfica, a cadeia tem esta aparência:

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, considere fortemente passar DefaultAzureCredential de uma das seguintes soluções:

• Uma implementação de credencial específica, como ManagedIdentityCredential.
• Uma implementação reduzida ChainedTokenCredential otimizada para o ambiente do Azure no qual seu aplicativo é executado.

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 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 se aplicam globalmente e, portanto, alteram o comportamento do tempo de DefaultAzureCredential execução em qualquer aplicativo em execução nessa máquina.

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.

Para fins de ilustração, suponha que a forma sem parâmetros do é usada para autenticar uma solicitação para uma conta de Armazenamento de DefaultAzureCredential Blob. 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 SharedTokenCacheCredential 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 AzureCliCredential returns a token

Na saída anterior, observe que:

• EnvironmentCredential, WorkloadIdentityCredential, ManagedIdentityCredential, , SharedTokenCacheCredentiale IntelliJCredential cada um não conseguiu adquirir um token de acesso do Microsoft Entra, nessa ordem.
• A AzureCliCredential.getToken chamada é bem-sucedida, conforme indicado pela entrada -sufixo returns a token. Desde que AzureCliCredential conseguiu, nenhuma credencial além dela foi tentada.