microsoft/azure-identity-dotnet

Biblioteca Azure Identity para .NET

Biblioteca de autenticação para clientes do SDK do Azure usando Microsoft Entra ID.

Instalação

dotnet add package Azure.Identity

# Para integração com ASP.NET Core
dotnet add package Microsoft.Extensions.Azure

# Para autenticação intermediada e suporte à credencial do Visual Studio Code
dotnet add package Azure.Identity.Broker

Variáveis de Ambiente

Service Principal com Segredo

AZURE_CLIENT_ID=<id-do-cliente-aplicacao>
AZURE_TENANT_ID=<id-do-diretorio-tenant>
AZURE_CLIENT_SECRET=<valor-do-segredo-cliente>

Service Principal com Certificado

AZURE_CLIENT_ID=<id-do-cliente-aplicacao>
AZURE_TENANT_ID=<id-do-diretorio-tenant>
AZURE_CLIENT_CERTIFICATE_PATH=<caminho-para-pfx-ou-pem>
AZURE_CLIENT_CERTIFICATE_PASSWORD=<senha-do-certificado>  # Opcional

Identidade Gerenciada

AZURE_CLIENT_ID=<id-do-cliente-da-identidade-gerenciada-atribuida-pelo-usuario>  # Apenas para identidade atribuída pelo usuário

DefaultAzureCredential

A credencial recomendada para a maioria dos cenários. Tenta vários métodos de autenticação em ordem. Consulte a visão geral do DefaultAzureCredential para a ordem atual da cadeia de credenciais e valores padrão.

Uso Básico

using Azure.Identity;
using Azure.Storage.Blobs;

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

ASP.NET Core com Injeção de Dependência

using Azure.Identity;
using Microsoft.Extensions.Azure;

builder.Services.AddAzureClients(clientBuilder =>
{
    clientBuilder.AddBlobServiceClient(
        new Uri("https://myaccount.blob.core.windows.net"));
    clientBuilder.AddSecretClient(
        new Uri("https://myvault.vault.azure.net"));
    
    // Usa DefaultAzureCredential por padrão
    clientBuilder.UseCredential(new DefaultAzureCredential());
});

Personalizando o DefaultAzureCredential

var credential = new DefaultAzureCredential(
    new DefaultAzureCredentialOptions
    {
        ExcludeEnvironmentCredential = true,
        ExcludeManagedIdentityCredential = false,
        ExcludeVisualStudioCredential = false,
        ExcludeAzureCliCredential = false,
        ExcludeInteractiveBrowserCredential = false, // Habilita interativo
        TenantId = "<id-do-tenant>",
        ManagedIdentityClientId = "<id-do-cliente-mi-atribuida-pelo-usuario>"
    });

Tipos de Credencial

ManagedIdentityCredential (Produção)

// Identidade gerenciada atribuída pelo sistema
var credential = new ManagedIdentityCredential(ManagedIdentityId.SystemAssigned);

// Atribuída pelo usuário por ID do cliente
var credential = new ManagedIdentityCredential(
    ManagedIdentityId.FromUserAssignedClientId("<id-do-cliente>"));

// Atribuída pelo usuário por ID do recurso
var credential = new ManagedIdentityCredential(
    ManagedIdentityId.FromUserAssignedResourceId("<id-do-recurso>"));

// Atribuída pelo usuário por ID do objeto
var credential = new ManagedIdentityCredential(
    ManagedIdentityId.FromUserAssignedObjectId("<id-do-objeto>"));

ClientSecretCredential

var credential = new ClientSecretCredential(
    tenantId: "<id-do-tenant>",
    clientId: "<id-do-cliente>",
    clientSecret: "<segredo-do-cliente>");

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

ClientCertificateCredential

var certificate = X509CertificateLoader.LoadCertificateFromFile("MyCertificate.pfx");
var credential = new ClientCertificateCredential(
    tenantId: "<id-do-tenant>",
    clientId: "<id-do-cliente>",
    certificate);

ChainedTokenCredential (Cadeia Personalizada)

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

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

Credenciais de Desenvolvedor

// Azure CLI
var credential = new AzureCliCredential();

// Azure PowerShell
var credential = new AzurePowerShellCredential();

// Azure Developer CLI (azd)
var credential = new AzureDeveloperCliCredential();

// Visual Studio
var credential = new VisualStudioCredential();

// Navegador Interativo
var credential = new InteractiveBrowserCredential();

Configuração Baseada em Ambiente

// Produção vs Desenvolvimento
TokenCredential credential = builder.Environment.IsProduction()
    ? new ManagedIdentityCredential("<id-do-cliente>")
    : new DefaultAzureCredential();

Nuvens Soberanas

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

// Autoridades disponíveis:
// AzureAuthorityHosts.AzurePublicCloud (padrão)
// AzureAuthorityHosts.AzureGovernment
// AzureAuthorityHosts.AzureChina

Referência de Tipos de Credencial

Categoria	Credencial	Propósito
Cadeias	DefaultAzureCredential	Cadeia pré-configurada do desenvolvimento à produção
	ChainedTokenCredential	Cadeia de credenciais personalizada
Hospedado no Azure	ManagedIdentityCredential	Identidade gerenciada do Azure
	WorkloadIdentityCredential	Identidade de carga de trabalho Kubernetes
	EnvironmentCredential	Variáveis de ambiente
Service Principal	ClientSecretCredential	ID do cliente + segredo
	ClientCertificateCredential	ID do cliente + certificado
	ClientAssertionCredential	Declaração de cliente assinada
Usuário	InteractiveBrowserCredential	Autenticação baseada em navegador
	DeviceCodeCredential	Fluxo de código de dispositivo
	OnBehalfOfCredential	Identidade delegada
Desenvolvedor	AzureCliCredential	Azure CLI
	AzurePowerShellCredential	Azure PowerShell
	AzureDeveloperCliCredential	Azure Developer CLI
	VisualStudioCredential	Visual Studio

Melhores Práticas

1. Use Credenciais Determinísticas em Produção

// Desenvolvimento
var devCredential = new DefaultAzureCredential();

// Produção - use credencial específica
var prodCredential = new ManagedIdentityCredential(
    ManagedIdentityId.FromUserAssignedClientId("<id-do-cliente>"));

2. Reutilize Instâncias de Credencial

// Bom: Instância de credencial única compartilhada entre clientes
var credential = new DefaultAzureCredential();
var blobClient = new BlobServiceClient(blobUri, credential);
var secretClient = new SecretClient(vaultUri, credential);

3. Configure Políticas de Repetição

var options = new ManagedIdentityCredentialOptions(
    ManagedIdentityId.FromUserAssignedClientId(clientId))
{
    Retry =
    {
        MaxRetries = 3,
        Delay = TimeSpan.FromSeconds(0.5),
    }
};
var credential = new ManagedIdentityCredential(options);

4. Habilite Log para Depuração

using Azure.Core.Diagnostics;

using AzureEventSourceListener listener = new((args, message) =>
{
    if (args is { EventSource.Name: "Azure-Identity" })
    {
        Console.WriteLine(message);
    }
}, EventLevel.LogAlways);

Tratamento de Erros

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

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($"Falha na Autenticação: {e.Message}");
}
catch (CredentialUnavailableException e)
{
    Console.WriteLine($"Credencial Indisponível: {e.Message}");
}

Exceções Principais

Exceção	Descrição
AuthenticationFailedException	Exceção base para erros de autenticação
CredentialUnavailableException	Credencial não pode autenticar no ambiente atual
AuthenticationRequiredException	Autenticação interativa é necessária

Suporte a Identidade Gerenciada

Serviços Azure suportados:

• Azure App Service e Azure Functions
• Azure Arc
• Azure Cloud Shell
• Azure Kubernetes Service (AKS)
• Azure Service Fabric
• Azure Virtual Machines
• Azure Virtual Machine Scale Sets

Segurança em Threads

Todas as implementações de credencial são thread-safe. Uma única instância de credencial pode ser compartilhada com segurança entre vários clientes e threads.

Pacotes Relacionados

Pacote	Propósito	Instalação
Azure.Identity	Autenticação (esta biblioteca)	dotnet add package Azure.Identity
Microsoft.Extensions.Azure	Integração DI	dotnet add package Microsoft.Extensions.Azure
Azure.Identity.Broker	Autenticação intermediada	dotnet add package Azure.Identity.Broker

Links de Referência

Recurso	URL
Pacote NuGet	https://www.nuget.org/packages/Azure.Identity
Referência da API	https://learn.microsoft.com/dotnet/api/azure.identity
Cadeias de Credenciais	https://aka.ms/azsdk/net/identity/credential-chains
Melhores Práticas	https://learn.microsoft.com/dotnet/azure/sdk/authentication/best-practices
Código Fonte GitHub	https://github.com/Azure/azure-sdk-for-net/tree/main/sdk/identity/Azure.Identity