microsoft/azure-identity-dotnet

Librería Azure Identity para .NET

Biblioteca de autenticación para clientes de Azure SDK que usa Microsoft Entra ID.

Instalación

dotnet add package Azure.Identity

# Para integración con ASP.NET Core
dotnet add package Microsoft.Extensions.Azure

# Para autenticación intermediada y soporte de credenciales de Visual Studio Code
dotnet add package Azure.Identity.Broker

Variables de Entorno

Principal de Servicio con Secreto

AZURE_CLIENT_ID=<id-de-cliente-de-aplicación>
AZURE_TENANT_ID=<id-de-inquilino-de-directorio>
AZURE_CLIENT_SECRET=<valor-del-secreto-de-cliente>

Principal de Servicio con Certificado

AZURE_CLIENT_ID=<id-de-cliente-de-aplicación>
AZURE_TENANT_ID=<id-de-inquilino-de-directorio>
AZURE_CLIENT_CERTIFICATE_PATH=<ruta-al-pfx-o-pem>
AZURE_CLIENT_CERTIFICATE_PASSWORD=<contraseña-del-certificado>  # Opcional

Identidad Administrada

AZURE_CLIENT_ID=<id-de-cliente-de-identidad-administrada-asignada-por-usuario>  # Solo para asignada por usuario

DefaultAzureCredential

La credencial recomendada para la mayoría de los escenarios. Intenta varios métodos de autenticación en orden. Consulte Descripción general de DefaultAzureCredential para conocer el orden actual de la cadena de credenciales y los valores predeterminados.

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 con Inyección de Dependencias

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 defecto
    clientBuilder.UseCredential(new DefaultAzureCredential());
});

Personalizando DefaultAzureCredential

var credential = new DefaultAzureCredential(
    new DefaultAzureCredentialOptions
    {
        ExcludeEnvironmentCredential = true,
        ExcludeManagedIdentityCredential = false,
        ExcludeVisualStudioCredential = false,
        ExcludeAzureCliCredential = false,
        ExcludeInteractiveBrowserCredential = false, // Habilitar interactivo
        TenantId = "<id-del-inquilino>",
        ManagedIdentityClientId = "<id-de-cliente-mi-asignada-por-usuario>"
    });

Tipos de Credenciales

ManagedIdentityCredential (Producción)

// Identidad administrada asignada por el sistema
var credential = new ManagedIdentityCredential(ManagedIdentityId.SystemAssigned);

// Asignada por usuario mediante ID de cliente
var credential = new ManagedIdentityCredential(
    ManagedIdentityId.FromUserAssignedClientId("<id-de-cliente>"));

// Asignada por usuario mediante ID de recurso
var credential = new ManagedIdentityCredential(
    ManagedIdentityId.FromUserAssignedResourceId("<id-de-recurso>"));

// Asignada por usuario mediante ID de objeto
var credential = new ManagedIdentityCredential(
    ManagedIdentityId.FromUserAssignedObjectId("<id-de-objeto>"));

ClientSecretCredential

var credential = new ClientSecretCredential(
    tenantId: "<id-del-inquilino>",
    clientId: "<id-de-cliente>",
    clientSecret: "<secreto-de-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-del-inquilino>",
    clientId: "<id-de-cliente>",
    certificate);

ChainedTokenCredential (Cadena Personalizada)

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

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

Credenciales de Desarrollador

// 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 Interactivo
var credential = new InteractiveBrowserCredential();

Configuración Basada en Entorno

// Producción vs Desarrollo
TokenCredential credential = builder.Environment.IsProduction()
    ? new ManagedIdentityCredential("<id-de-cliente>")
    : new DefaultAzureCredential();

Nubes Soberanas

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

// Hosts de autoridad disponibles:
// AzureAuthorityHosts.AzurePublicCloud (predeterminado)
// AzureAuthorityHosts.AzureGovernment
// AzureAuthorityHosts.AzureChina

Referencia de Tipos de Credenciales

Categoría	Credencial	Propósito
Cadenas	DefaultAzureCredential	Cadena preconfigurada para desarrollo a producción
	ChainedTokenCredential	Cadena de credenciales personalizada
Alojadas en Azure	ManagedIdentityCredential	Identidad administrada de Azure
	WorkloadIdentityCredential	Identidad de carga de trabajo de Kubernetes
	EnvironmentCredential	Variables de entorno
Principal de Servicio	ClientSecretCredential	ID de cliente + secreto
	ClientCertificateCredential	ID de cliente + certificado
	ClientAssertionCredential	Aserción de cliente firmada
Usuario	InteractiveBrowserCredential	Autenticación basada en navegador
	DeviceCodeCredential	Flujo de código de dispositivo
	OnBehalfOfCredential	Identidad delegada
Desarrollador	AzureCliCredential	Azure CLI
	AzurePowerShellCredential	Azure PowerShell
	AzureDeveloperCliCredential	Azure Developer CLI
	VisualStudioCredential	Visual Studio

Mejores Prácticas

1. Usar Credenciales Determinísticas en Producción

// Desarrollo
var devCredential = new DefaultAzureCredential();

// Producción - usar credencial específica
var prodCredential = new ManagedIdentityCredential(
    ManagedIdentityId.FromUserAssignedClientId("<id-de-cliente>"));

2. Reutilizar Instancias de Credenciales

// Bueno: Instancia única de credencial compartida entre clientes
var credential = new DefaultAzureCredential();
var blobClient = new BlobServiceClient(blobUri, credential);
var secretClient = new SecretClient(vaultUri, credential);

3. Configurar Políticas de Reintento

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

4. Habilitar Registro para Depuración

using Azure.Core.Diagnostics;

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

Manejo de Errores

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($"Autenticación Fallida: {e.Message}");
}
catch (CredentialUnavailableException e)
{
    Console.WriteLine($"Credencial No Disponible: {e.Message}");
}

Excepciones Clave

Excepción	Descripción
AuthenticationFailedException	Excepción base para errores de autenticación
CredentialUnavailableException	La credencial no puede autenticar en el entorno actual
AuthenticationRequiredException	Se requiere autenticación interactiva

Soporte de Identidad Administrada

Servicios de Azure compatibles:

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

Seguridad para Hilos

Todas las implementaciones de credenciales son seguras para hilos. Una sola instancia de credencial puede compartirse de forma segura entre múltiples clientes y hilos.

Paquetes Relacionados

Paquete	Propósito	Instalación
Azure.Identity	Autenticación (esta librería)	dotnet add package Azure.Identity
Microsoft.Extensions.Azure	Integración DI	dotnet add package Microsoft.Extensions.Azure
Azure.Identity.Broker	Autenticación intermediada	dotnet add package Azure.Identity.Broker

Enlaces de Referencia

Recurso	URL
Paquete NuGet	https://www.nuget.org/packages/Azure.Identity
Referencia de API	https://learn.microsoft.com/dotnet/api/azure.identity
Cadenas de Credenciales	https://aka.ms/azsdk/net/identity/credential-chains
Mejores Prácticas	https://learn.microsoft.com/dotnet/azure/sdk/authentication/best-practices
Código Fuente en GitHub	https://github.com/Azure/azure-sdk-for-net/tree/main/sdk/identity/Azure.Identity