Cadeias de credenciais na biblioteca Azure Identity para Java

A biblioteca Azure Identity fornece credentials — 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

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:

• Perceção do ambiente: seleciona automaticamente a credencial mais apropriada com base no ambiente em que a aplicação está a ser executada. 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

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

Em sua forma mais simples, você pode usar a versão sem parâmetros do 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 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:

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

Para usar um nome de variável de ambiente personalizado em vez do predefinido AZURE_TOKEN_CREDENTIALS, use AzureIdentityEnvVars.fromString() para criar uma referência à sua 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 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

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

Diretrizes de uso para DefaultAzureCredential

DefaultAzureCredential é, sem dúvida, a forma mais fácil de começar com a biblioteca Azure Identity, mas com essa conveniência vêm os compromissos. Depois de implementar a sua aplicação para Azure, deve compreender os requisitos de autenticação da aplicação e considerar se DefaultAzureCredential é apropriado para o seu cenário.

DefaultAzureCredential Oferece um benefício fundamental: desacopla o código da sua aplicação de mecanismos específicos de autenticação, permitindo-lhe alterar a configuração de autenticação sem modificar o código. Para programadores experientes que configuram conscientemente a sua autenticação em produção, esta flexibilidade pode ser valiosa. No entanto, esta flexibilidade traz potenciais desvantagens:

• Desafios de depuração: Quando a autenticação falha, pode ser um desafio 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 certas variáveis 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.
• Incompatibilidades de permissões: DefaultAzureCredential termina na primeira credencial que adquire com sucesso um token, 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 gerida em produção, fazendo com que a aplicação funcione localmente mas falhe nas verificações de autorização após a implementação.

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 ilustrativos, assuma que a forma sem parâmetros de DefaultAzureCredential é usada para autenticar um pedido a uma conta Blob Storage. A aplicação corre no ambiente de desenvolvimento local e o programador autenticou-se no Azure usando a 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 falharam em adquirir um token de acesso Microsoft Entra, por esta ordem.
• A chamada AzureCliCredential.getToken é bem-sucedida, conforme indicado pela entrada com sufixo -returns a token. Desde que AzureCliCredential teve sucesso, não foram testadas mais credenciais além disso.