Biblioteca de clientes da Identidade do Azure para .NET – versão 1.10.3

A biblioteca de identidade do Azure fornece suporte à autenticação de token de ID de Microsoft Entra (anteriormente Azure Active Directory) no SDK do Azure. Ele fornece um conjunto de TokenCredential implementações que podem ser usadas para construir clientes do SDK do Azure que dão suporte à autenticação de token Microsoft Entra.

Código-fonte | Pacote (NuGet) | Documentação | de referência da APIdocumentação da ID do Microsoft Entra

Introdução

Instalar o pacote

Instale a biblioteca de clientes do Azure Identity para .NET com o NuGet:

dotnet add package Azure.Identity

Pré-requisitos

• Uma assinatura do Azure.
• A CLI do Azure também pode ser útil para autenticar em um ambiente de desenvolvimento, criar contas e gerenciar funções de conta.

Autenticar o cliente

Ao depurar e executar o código localmente, é comum que um desenvolvedor use sua própria conta para autenticar chamadas aos serviços do Azure. Há várias ferramentas de desenvolvedor que podem ser usadas para executar essa autenticação no ambiente de desenvolvimento.

Autenticar por meio do Visual Studio

Os desenvolvedores que usam o Visual Studio 2017 ou posterior podem autenticar uma conta Microsoft Entra por meio do IDE. Os aplicativos que usam DefaultAzureCredential ou VisualStudioCredential podem usar essa conta para autenticar chamadas no aplicativo ao serem executados localmente.

Para autenticar no Visual Studio, selecione o menuOpções de Ferramentas> para iniciar a caixa de diálogo Opções. Em seguida, navegue até as Azure Service Authentication opções para entrar com sua conta Microsoft Entra.

Autenticar por meio de Visual Studio Code

Os desenvolvedores que usam Visual Studio Code podem usar a extensão conta do Azure para autenticar por meio do editor. Os aplicativos que usam DefaultAzureCredential ou VisualStudioCodeCredential podem usar essa conta para autenticar chamadas no aplicativo ao serem executados localmente.

É um problema conhecido que VisualStudioCodeCredential não funciona com versões de extensão da Conta do Azure mais recentes do que 0.9.11. Uma correção de longo prazo para esse problema está em andamento. Enquanto isso, considere a autenticação por meio da CLI do Azure.

Autenticar por meio da CLI do Azure

Os desenvolvedores que codificam fora de um IDE também podem usar a CLI do Azure para autenticar. Os aplicativos que usam DefaultAzureCredential ou AzureCliCredential podem usar essa conta para autenticar chamadas no aplicativo ao serem executados localmente.

Para autenticar com a CLI do Azure, os usuários podem executar o comando az login. Para usuários em execução em um sistema com um navegador da Web padrão, a CLI do Azure iniciará o navegador para autenticar o usuário.

Para sistemas sem um navegador da Web padrão, o comando az login usará o fluxo de autenticação de código do dispositivo. O usuário também pode forçar a CLI do Azure a usar o fluxo de código do dispositivo em vez de iniciar um navegador especificando o argumento --use-device-code.

Autenticar por meio do Azure Developer CLI

Os desenvolvedores que codificam fora de um IDE também podem usar o Azure Developer CLI para autenticar. Os aplicativos que usam DefaultAzureCredential ou AzureDeveloperCliCredential podem usar essa conta para autenticar chamadas no aplicativo ao serem executados localmente.

Para autenticar com o Azure Developer CLI, os usuários podem executar o comando azd auth login. Para usuários em execução em um sistema com um navegador da Web padrão, o Azure Developer CLI iniciará o navegador para autenticar o usuário.

Para sistemas sem um navegador da Web padrão, o comando azd auth login --use-device-code usará o fluxo de autenticação de código do dispositivo.

Autenticar por meio de Azure PowerShell

Os desenvolvedores que codificam fora de um IDE também podem usar Azure PowerShell para autenticar. Os aplicativos que usam DefaultAzureCredential ou AzurePowerShellCredential podem usar essa conta para autenticar chamadas no aplicativo ao serem executados localmente.

Para autenticar com Azure PowerShell, os usuários podem executar o comando Connect-AzAccount. Para usuários em execução em um sistema com um navegador da Web padrão e versão 5.0.0 ou posterior do Azure PowerShell, ele iniciará o navegador para autenticar o usuário.

Para sistemas sem um navegador da Web padrão, o comando Connect-AzAccount usará o fluxo de autenticação de código do dispositivo. O usuário também pode forçar Azure PowerShell a usar o fluxo de código do dispositivo em vez de iniciar um navegador especificando o UseDeviceAuthentication argumento .

Principais conceitos

Credenciais

Uma credencial é uma classe que contém ou pode obter os dados necessários para um cliente de serviço autenticar solicitações. Os clientes de serviço no SDK do Azure aceitam credenciais quando são construídos. Os clientes de serviço usam essas credenciais para autenticar solicitações para o serviço.

A biblioteca de Identidade do Azure se concentra na autenticação OAuth com Microsoft Entra ID e oferece uma variedade de classes de credencial capazes de adquirir um token Microsoft Entra para autenticar solicitações de serviço. Todas as classes de credencial nessa biblioteca são implementações da TokenCredential classe abstrata no Azure.Core e qualquer uma delas pode ser usada para construir clientes de serviço capazes de autenticar com um TokenCredential.

Consulte Classes de credencial para obter uma listagem completa dos tipos de credenciais disponíveis.

DefaultAzureCredential

O DefaultAzureCredential é apropriado para a maioria dos cenários em que o aplicativo se destina a ser executado no Azure. Isso ocorre porque o DefaultAzureCredential combina as credenciais normalmente usadas para autenticação quando implantada com as credenciais usadas para realizar a autenticação em um ambiente de desenvolvimento.

Observação: DefaultAzureCredential destina-se a simplificar a introdução ao SDK manipulando cenários comuns com comportamentos padrão razoáveis. Os desenvolvedores que desejam mais controle ou cujo cenário não é abordado nas configurações padrão devem usar outros tipos de credencial.

A DefaultAzureCredential tenta realizar a autenticação por meio dos seguintes mecanismos, nesta ordem, e para quando um é bem-sucedido:

1. Ambiente – o DefaultAzureCredential lerá as informações da conta especificadas por meio de variáveis de ambiente e as usará para autenticar.
2. Identidade da carga de trabalho – se o aplicativo for implantado em um host do Azure com a Identidade de Carga de Trabalho habilitada, o DefaultAzureCredential será autenticado com essa conta.
3. Identidade Gerenciada – se o aplicativo for implantado em um host do Azure com a Identidade Gerenciada habilitada, o DefaultAzureCredential será autenticado com essa conta.
4. Visual Studio – se o desenvolvedor tiver se autenticado por meio do Visual Studio, o DefaultAzureCredential será autenticado com essa conta.
5. Visual Studio Code – atualmente excluído por padrão, pois a autenticação do SDK por meio de Visual Studio Code está interrompida devido ao problema nº 27263. O VisualStudioCodeCredential será habilitado novamente no DefaultAzureCredential fluxo quando uma correção estiver em vigor. O problema nº 30525 acompanha isso. Enquanto isso, Visual Studio Code usuários podem autenticar seu ambiente de desenvolvimento usando a CLI do Azure.
6. CLI do Azure – se o desenvolvedor tiver autenticado uma conta por meio do comando da CLI az login do Azure, o DefaultAzureCredential será autenticado com essa conta.
7. Azure PowerShell – se o desenvolvedor tiver autenticado uma conta por meio do comando Azure PowerShellConnect-AzAccount, o DefaultAzureCredential será autenticado com essa conta.
8. Azure Developer CLI – se o desenvolvedor tiver se autenticado por meio do comando Azure Developer CLIazd auth login, o DefaultAzureCredential será autenticado com essa conta.
9. Navegador interativo – se habilitado, a DefaultAzureCredential autenticará interativamente o desenvolvedor por meio do navegador padrão do sistema atual. Por padrão, esse tipo de credencial está desabilitado.

Política de continuação

A partir da versão 1.10.1, DefaultAzureCredential tentará autenticar com todas as credenciais de desenvolvedor até que uma seja bem-sucedida, independentemente de quaisquer erros que as credenciais anteriores do desenvolvedor tenham sofrido. Por exemplo, uma credencial de desenvolvedor pode tentar obter um token e falhar, portanto DefaultAzureCredential , continuará para a próxima credencial no fluxo. As credenciais de serviço implantadas interromperão o fluxo com uma exceção gerada se puderem tentar a recuperação de token, mas não receberão uma. Antes da versão 1.10.1, as credenciais do desenvolvedor paravam o fluxo de autenticação da mesma forma se a recuperação de token falhasse.

Esse comportamento permite experimentar todas as credenciais do desenvolvedor em seu computador enquanto tem um comportamento previsível implantado.

Exemplos

Autenticar com DefaultAzureCredential

Este exemplo demonstra a autenticação do SecretClient da biblioteca de clientes Azure.Security.KeyVault.Secrets usando a DefaultAzureCredential.

// Create a secret client using the DefaultAzureCredential
var client = new SecretClient(new Uri("https://myvault.vault.azure.net/"), new DefaultAzureCredential());

Habilitar a autenticação interativa com DefaultAzureCredential

A autenticação interativa está desabilitada no DefaultAzureCredential por padrão. Este exemplo demonstra duas maneiras de habilitar a parte de autenticação interativa do DefaultAzureCredential. Quando habilitado, o DefaultAzureCredential retornará para autenticar interativamente o desenvolvedor por meio do navegador padrão do sistema se nenhuma outra credencial estiver disponível. Em seguida, este exemplo autentica um EventHubProducerClient da biblioteca de clientes Azure.Messaging.EventHubs usando o DefaultAzureCredential com a autenticação interativa habilitada.

// the includeInteractiveCredentials constructor parameter can be used to enable interactive authentication
var credential = new DefaultAzureCredential(includeInteractiveCredentials: true);

var eventHubClient = new EventHubProducerClient("myeventhub.eventhubs.windows.net", "myhubpath", credential);

Especifique uma identidade gerenciada atribuída pelo usuário com DefaultAzureCredential

Muitos hosts do Azure permitem a atribuição de uma identidade gerenciada atribuída pelo usuário. Este exemplo demonstra a configuração do DefaultAzureCredential para autenticar uma identidade atribuída pelo usuário quando implantada em um host do Azure. Em seguida, ele autentica um BlobClient na biblioteca de clientes Azure.Storage.Blobs com credencial.

// When deployed to an azure host, the default azure credential will authenticate the specified user assigned managed identity.

string userAssignedClientId = "<your managed identity client Id>";
var credential = new DefaultAzureCredential(new DefaultAzureCredentialOptions { ManagedIdentityClientId = userAssignedClientId });

var blobClient = new BlobClient(new Uri("https://myaccount.blob.core.windows.net/mycontainer/myblob"), credential);

Além de configurar o por meio do ManagedIdentityClientId código, ele também pode ser definido usando a AZURE_CLIENT_ID variável de ambiente . Essas duas abordagens são equivalentes ao usar o DefaultAzureCredential.

Definir um fluxo de autenticação personalizado com ChainedTokenCredential

Embora DefaultAzureCredential seja geralmente a maneira mais rápida de começar a desenvolver aplicativos para o Azure, os usuários mais avançados podem personalizar as credenciais consideradas durante a autenticação. ChainedTokenCredential permite que os usuários combinem várias instâncias de credencial para definir uma cadeia personalizada de credenciais. Este exemplo demonstra a criação de um ChainedTokenCredential que tentará autenticar usando a identidade gerenciada e retornará à autenticação por meio da CLI do Azure se a identidade gerenciada não estiver disponível no ambiente atual. Em seguida, a credencial é usada para autenticar um EventHubProducerClient na biblioteca de clientes Azure.Messaging.EventHubs.

// Authenticate using managed identity if it is available; otherwise use the Azure CLI to authenticate.

var credential = new ChainedTokenCredential(new ManagedIdentityCredential(), new AzureCliCredential());

var eventHubProducerClient = new EventHubProducerClient("myeventhub.eventhubs.windows.net", "myhubpath", credential);

Suporte de identidade gerenciada

A autenticação de identidade gerenciada tem suporte por meio do DefaultAzureCredential ou diretamente ManagedIdentityCredential para os seguintes serviços do Azure:

• Serviço de Aplicativo do Azure e Azure Functions
• Azure Arc
• Azure Cloud Shell
• Serviço de Kubernetes do Azure
• Azure Service Fabric
• Máquinas Virtuais do Azure
• Conjuntos de dimensionamento de Máquinas Virtuais do Azure

Exemplos

Estes exemplos demonstram a autenticação do SecretClient da biblioteca de clientes Azure.Security.KeyVault.Secrets usando o ManagedIdentityCredential.

Autenticar com uma identidade gerenciada atribuída pelo usuário

var credential = new ManagedIdentityCredential(clientId: userAssignedClientId);
var client = new SecretClient(new Uri("https://myvault.vault.azure.net/"), credential);

Autenticar com uma identidade gerenciada atribuída pelo sistema

var credential = new ManagedIdentityCredential();
var client = new SecretClient(new Uri("https://myvault.vault.azure.net/"), credential);

Configuração de nuvem

As credenciais são padrão para autenticação no ponto de extremidade Microsoft Entra para a nuvem pública do Azure. Para acessar recursos em outras nuvens, como Azure Governamental ou uma nuvem privada, configure as credenciais com o AuthorityHost argumento . O AzureAuthorityHosts define autoridades para nuvens conhecidas:

var credential = new DefaultAzureCredential(new DefaultAzureCredentialOptions { AuthorityHost = AzureAuthorityHosts.AzureGovernment });

Nem todas as credenciais exigem essa configuração. As credenciais que se autenticam por meio de uma ferramenta de desenvolvimento, como AzureCliCredential, usam a configuração dessa ferramenta.

Classes de credencial

Autenticar aplicativos hospedados no Azure

Autenticar entidades de serviço

Autenticar usuários

Autenticar por meio de ferramentas de desenvolvimento

Nota: Todas as implementações de credenciais na biblioteca de Identidade do Azure são threadsafe e uma única instância de credencial pode ser usada por vários clientes de serviço.

Variáveis de ambiente

DefaultAzureCredential e EnvironmentCredential podem ser configurados com variáveis de ambiente. Cada tipo de autenticação requer valores para variáveis específicas:

Entidade de serviço com segredo

Entidade de serviço com certificado

Nome de usuário e senha

A configuração é tentada na ordem acima. Por exemplo, se os valores para um segredo do cliente e um certificado estiverem presentes, o segredo do cliente será usado.

Avaliação contínua de acesso

A partir da versão 1.10.0, o acesso a recursos protegidos pela CAE (Avaliação Contínua de Acesso) é possível por solicitação. Esse comportamento pode ser habilitado definindo a IsCaeEnabled propriedade de por meio de TokenRequestContext seu construtor. Não há suporte para CAE para credenciais de identidade gerenciada e de desenvolvedor.

Armazenamento de token em cache

O cache de token é um recurso fornecido pela biblioteca de identidade do Azure que permite que os aplicativos:

• Cache de tokens na memória (padrão) ou em disco (aceitação).
• Melhorar a resiliência e o desempenho.
• Reduza o número de solicitações feitas para Microsoft Entra ID para obter tokens de acesso.

A biblioteca de Identidade do Azure oferece cache de disco persistente e na memória. Para obter mais detalhes, consulte a documentação de cache de token

Solução de problemas

Consulte o guia de solução de problemas para obter detalhes sobre como diagnosticar vários cenários de falha.

Tratamento de erros

Erros decorrentes da autenticação podem ser gerados em qualquer método de cliente de serviço que faça uma solicitação para o serviço. Isso ocorre porque a primeira vez que o token é solicitado da credencial é na primeira chamada para o serviço, e qualquer chamada subsequente pode precisar atualizar o token. Para distinguir essas falhas de falhas nas classes de identidade do Azure cliente de serviço, gere o AuthenticationFailedException com detalhes para a origem do erro na mensagem de exceção, bem como possivelmente a mensagem de erro. Dependendo do aplicativo, esses erros podem ou não ser recuperáveis.

using Azure.Identity;
using Azure.Security.KeyVault.Secrets;

// Create a secret client using the DefaultAzureCredential
var client = new SecretClient(new Uri("https://myvault.vault.azure.net/"), new DefaultAzureCredential());

try
{
    KeyVaultSecret secret = await client.GetSecretAsync("secret1");
}
catch (AuthenticationFailedException e)
{
    Console.WriteLine($"Authentication Failed. {e.Message}");
}

Para obter mais informações sobre como lidar com erros decorrentes de solicitações com falha para Microsoft Entra ID ou pontos de extremidade de identidade gerenciada, consulte a documentação da ID do Microsoft Entra sobre códigos de erro de autorização.

Registro em log

A biblioteca de Identidade do Azure fornece os mesmos recursos de registro em log que o restante do SDK do Azure.

A maneira mais simples de ver os logs para ajudar a depurar problemas de autenticação é habilitar o log do console.

// Setup a listener to monitor logged events.
using AzureEventSourceListener listener = AzureEventSourceListener.CreateConsoleLogger();

Todas as credenciais podem ser configuradas com opções de diagnóstico da mesma forma que outros clientes no SDK.

CUIDADO: Solicitações e respostas na biblioteca de identidades do Azure contêm informações confidenciais. A precaução deve ser tomada para proteger os logs, ao personalizar a saída, para evitar comprometer a segurança da conta.

DefaultAzureCredentialOptions options = new DefaultAzureCredentialOptions
{
    Diagnostics =
    {
        LoggedHeaderNames = { "x-ms-request-id" },
        LoggedQueryParameters = { "api-version" },
        IsLoggingContentEnabled = true
    }
};

Ao solucionar problemas de autenticação, talvez você também queira habilitar o registro em log de informações confidenciais. Para habilitar esse tipo de registro em log, defina a IsLoggingContentEnabled propriedade como true. Para registrar apenas detalhes sobre a conta que foi usada para tentar autenticação e autorização, defina IsAccountIdentifierLoggingEnabled como true.

DefaultAzureCredentialOptions options = new DefaultAzureCredentialOptions
{
    Diagnostics =
    {
        LoggedHeaderNames = { "x-ms-request-id" },
        LoggedQueryParameters = { "api-version" },
        IsAccountIdentifierLoggingEnabled = true
    }
};

Acesso thread-safe

Garantimos que todos os métodos de instância de credencial sejam thread-safe e independentes uns dos outros (diretriz). Isso garante que a recomendação de reutilize instâncias de credencial seja sempre segura, mesmo entre threads.

Conceitos adicionais

Opções | do clienteAcessando a resposta | Diagnostics | Zombando | Tempo de vida do cliente

Próximas etapas

Bibliotecas de clientes que dão suporte à autenticação com a Identidade do Azure

Muitas das bibliotecas de clientes listadas aqui dão suporte à autenticação com TokenCredential e à biblioteca de identidade do Azure. Lá, você também encontrará links nos quais poderá saber mais sobre o uso deles, incluindo documentação e exemplos adicionais.

Problemas conhecidos

No momento, essa biblioteca não dá suporte a cenários relacionados ao serviço Azure AD B2C.

Problemas abertos para a Azure.Identity biblioteca podem ser encontrados aqui.

Contribuição

Este projeto aceita contribuições e sugestões. A maioria das contribuições exige que você concorde com um CLA (Contrato de Licença do Colaborador) declarando que você tem o direito de nos conceder, e de fato concede, os direitos de usar sua contribuição. Para obter detalhes, visite https://cla.microsoft.com.

Quando você envia uma solicitação de pull, um bot do CLA determina automaticamente se você precisa fornecer um CLA e preencher a PR corretamente (por exemplo, rótulo, comentário). Basta seguir as instruções fornecidas pelo bot. Você só precisará fazer isso uma vez em todos os repositórios que usam nosso CLA.

Este projeto adotou o Código de Conduta de Software Livre da Microsoft. Para obter mais informações, confira as Perguntas frequentes sobre o Código de Conduta ou contate opencode@microsoft.com para enviar outras perguntas ou comentários.