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

A biblioteca de cliente do Azure Identity fornece as credenciais : tipos públicos 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

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:

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

  // Set up credential based on environment (Azure or local development)
  if os.Getenv("WEBSITE_HOSTNAME") != "" {
      clientID := azidentity.ClientID("abcd1234-...")
      opts := azidentity.ManagedIdentityCredentialOptions{ID: clientID}
      cred, err := azidentity.NewManagedIdentityCredential(&opts)
  
      if err != nil {
        // TODO: handle error
      }
  }
  else {
      // Use Azure CLI Credential
      credential, err = azidentity.NewAzureCLICredential(nil)
  
      if err != nil {
        // TODO: handle error
      }
  }
  

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

Com o Go, há duas opções para o encadeamento de credenciais:

• Utilize uma cadeia preconfigurada: Utilize a cadeia preconfigurada implementada pelo tipo DefaultAzureCredential. Para esta abordagem, consulte a seção de visão geral de DefaultAzureCredential .
• Crie uma cadeia de credenciais personalizada: comece com uma cadeia vazia e inclua apenas o que você precisa. Para esta abordagem, consulte a seção de visão geral do 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 tenta as credenciais é a seguinte.

Encomenda	Credencial	Descrição
1	Ambiente	Lê uma coleção de variáveis de ambiente para determinar se um principal de serviço de aplicação está configurado para a aplicação. 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 de 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	Azure CLI	Se o desenvolvedor se autenticou no Azure usando o comando az login da CLI do Azure, autentique o aplicativo no Azure usando essa mesma conta.
5	CLI do Desenvolvedor do Azure	Se o desenvolvedor se autenticou no Azure usando o comando azd auth login da CLI do Azure Developer, autentique-se com essa conta.

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

import (
    "github.com/Azure/azure-sdk-for-go/sdk/azidentity"
    "github.com/Azure/azure-sdk-for-go/sdk/storage/azblob"
    )

// create a credential
credential, err := azidentity.NewDefaultAzureCredential(nil)
if err != nil {
    // TODO: handle error
}

// create a Blob service client 
accountURL := "https://<my_account_name>.blob.core.windows.net"
client, err := azblob.NewClient(accountURL, credential, nil)
if err != nil {
    // TODO: handle error
}

Visão geral de ChainedTokenCredential

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

managed, err := azidentity.NewManagedIdentityCredential(nil)
if err != nil {
  // handle error
}

azCLI, err := azidentity.NewAzureCLICredential(nil)
if err != nil {
  // handle error
}

chain, err := azidentity.NewChainedTokenCredential([]azcore.TokenCredential{managed, azCLI}, nil)
if err != nil {
  // handle error
}

O exemplo de código anterior cria uma cadeia de credenciais personalizada composta por duas credenciais. ManagedIdentityCredential é tentado primeiro, seguido de AzureCliCredential, se necessário. Em forma gráfica, a cadeia tem esta aparência:

Dica

Para um desempenho melhorado, otimize a ordenação de credenciais em ChainedTokenCredential para o seu ambiente de produção. As credenciais destinadas ao uso no ambiente de desenvolvimento local devem ser adicionadas por último.

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 de DefaultAzureCredential para uma das seguintes soluções:

• Uma implementação de credencial específica, como ManagedIdentityCredential.
• Uma implementação de ChainedTokenCredential reduzida 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 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 Debug de 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 sempre falha no ambiente de desenvolvimento local, a menos que seja explicitamente desativado através da propriedade com o prefixo excludecorrespondente.
• 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 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 na sua aplicação. Opcionalmente, filtre os logs somente para os eventos emitidos pela biblioteca de cliente do Azure Identity. Por exemplo:

import azlog "github.com/Azure/azure-sdk-for-go/sdk/azcore/log"
// print log output to stdout
azlog.SetListener(func(event azlog.Event, s string) {
    fmt.Println(s)
})
// include only azidentity credential logs
azlog.SetEvents(azidentity.EventAuthentication)

Para obter orientação sobre como resolver erros de tipos de credenciais específicos, consulte o guia de solução de problemas de .