microsoft/azure-identity-dotnet

Azure Identity-Bibliothek für .NET

Authentifizierungsbibliothek für Azure SDK-Clients mit Microsoft Entra ID.

Installation

dotnet add package Azure.Identity

# Für ASP.NET Core Integration
dotnet add package Microsoft.Extensions.Azure

# Für vermittelte Authentifizierung und Visual Studio Code-Anmeldeinformationsunterstützung
dotnet add package Azure.Identity.Broker

Umgebungsvariablen

Service Principal mit Secret

AZURE_CLIENT_ID=<anwendungs-client-id>
AZURE_TENANT_ID=<verzeichnis-mandanten-id>
AZURE_CLIENT_SECRET=<client-secret-wert>

Service Principal mit Zertifikat

AZURE_CLIENT_ID=<anwendungs-client-id>
AZURE_TENANT_ID=<verzeichnis-mandanten-id>
AZURE_CLIENT_CERTIFICATE_PATH=<pfad-zu-pfx-oder-pem>
AZURE_CLIENT_CERTIFICATE_PASSWORD=<zertifikat-passwort>  # Optional

Verwaltete Identität

AZURE_CLIENT_ID=<client-id-der-benutzerzugewiesenen-verwalteten-identität>  # Nur für benutzerzugewiesene

DefaultAzureCredential

Die empfohlene Anmeldeinformation für die meisten Szenarien. Versucht mehrere Authentifizierungsmethoden in einer bestimmten Reihenfolge. Siehe DefaultAzureCredential Übersicht für die aktuelle Reihenfolge der Anmeldeinformationskette und die Standardeinstellungen.

Grundlegende Verwendung

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 mit Dependency Injection

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"));
    
    // Verwendet standardmäßig DefaultAzureCredential
    clientBuilder.UseCredential(new DefaultAzureCredential());
});

Anpassen von DefaultAzureCredential

var credential = new DefaultAzureCredential(
    new DefaultAzureCredentialOptions
    {
        ExcludeEnvironmentCredential = true,
        ExcludeManagedIdentityCredential = false,
        ExcludeVisualStudioCredential = false,
        ExcludeAzureCliCredential = false,
        ExcludeInteractiveBrowserCredential = false, // Interaktiv aktivieren
        TenantId = "<mandanten-id>",
        ManagedIdentityClientId = "<benutzerzugewiesene-mi-client-id>"
    });

Anmeldeinformationstypen

ManagedIdentityCredential (Produktion)

// Systemzugewiesene verwaltete Identität
var credential = new ManagedIdentityCredential(ManagedIdentityId.SystemAssigned);

// Benutzerzugewiesen nach Client-ID
var credential = new ManagedIdentityCredential(
    ManagedIdentityId.FromUserAssignedClientId("<client-id>"));

// Benutzerzugewiesen nach Ressourcen-ID
var credential = new ManagedIdentityCredential(
    ManagedIdentityId.FromUserAssignedResourceId("<ressourcen-id>"));

// Benutzerzugewiesen nach Objekt-ID
var credential = new ManagedIdentityCredential(
    ManagedIdentityId.FromUserAssignedObjectId("<objekt-id>"));

ClientSecretCredential

var credential = new ClientSecretCredential(
    tenantId: "<mandanten-id>",
    clientId: "<client-id>",
    clientSecret: "<client-secret>");

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

ClientCertificateCredential

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

ChainedTokenCredential (Benutzerdefinierte Kette)

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

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

Entwicklungsanmeldeinformationen

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

// Interaktiver Browser
var credential = new InteractiveBrowserCredential();

Umgebungsbasierte Konfiguration

// Produktion vs. Entwicklung
TokenCredential credential = builder.Environment.IsProduction()
    ? new ManagedIdentityCredential("<client-id>")
    : new DefaultAzureCredential();

Sovereign Clouds

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

// Verfügbare Authority Hosts:
// AzureAuthorityHosts.AzurePublicCloud (Standard)
// AzureAuthorityHosts.AzureGovernment
// AzureAuthorityHosts.AzureChina

Referenz der Anmeldeinformationstypen

Kategorie	Anmeldeinformation	Zweck
Ketten	DefaultAzureCredential	Vorkonfigurierte Kette für Entwicklung bis Produktion
	ChainedTokenCredential	Benutzerdefinierte Anmeldeinformationskette
Azure-gehostet	ManagedIdentityCredential	Verwaltete Azure-Identität
	WorkloadIdentityCredential	Kubernetes-Workload-Identität
	EnvironmentCredential	Umgebungsvariablen
Service Principal	ClientSecretCredential	Client-ID + Secret
	ClientCertificateCredential	Client-ID + Zertifikat
	ClientAssertionCredential	Signierte Client-Assertion
Benutzer	InteractiveBrowserCredential	Browserbasierte Authentifizierung
	DeviceCodeCredential	Gerätecode-Flow
	OnBehalfOfCredential	Delegierte Identität
Entwickler	AzureCliCredential	Azure CLI
	AzurePowerShellCredential	Azure PowerShell
	AzureDeveloperCliCredential	Azure Developer CLI
	VisualStudioCredential	Visual Studio

Best Practices

1. Deterministische Anmeldeinformationen in der Produktion verwenden

// Entwicklung
var devCredential = new DefaultAzureCredential();

// Produktion - spezifische Anmeldeinformationen verwenden
var prodCredential = new ManagedIdentityCredential(
    ManagedIdentityId.FromUserAssignedClientId("<client-id>"));

2. Instanzen von Anmeldeinformationen wiederverwenden

// Gut: Einzelne Instanz von Anmeldeinformationen wird für mehrere Clients gemeinsam genutzt
var credential = new DefaultAzureCredential();
var blobClient = new BlobServiceClient(blobUri, credential);
var secretClient = new SecretClient(vaultUri, credential);

3. Wiederholungsrichtlinien konfigurieren

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

4. Protokollierung für die Fehlersuche aktivieren

using Azure.Core.Diagnostics;

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

Fehlerbehandlung

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($"Authentifizierung fehlgeschlagen: {e.Message}");
}
catch (CredentialUnavailableException e)
{
    Console.WriteLine($"Anmeldeinformation nicht verfügbar: {e.Message}");
}

Wichtige Ausnahmen

Ausnahme	Beschreibung
AuthenticationFailedException	Basisausnahme für Authentifizierungsfehler
CredentialUnavailableException	Anmeldeinformation kann in der aktuellen Umgebung nicht authentifizieren
AuthenticationRequiredException	Interaktive Authentifizierung erforderlich

Unterstützung für verwaltete Identität

Unterstützte Azure-Dienste:

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

Thread-Sicherheit

Alle Implementierungen von Anmeldeinformationen sind threadsicher. Eine einzelne Instanz von Anmeldeinformationen kann sicher für mehrere Clients und Threads gemeinsam genutzt werden.

Verwandte Pakete

Paket	Zweck	Installation
Azure.Identity	Authentifizierung (diese Bibliothek)	dotnet add package Azure.Identity
Microsoft.Extensions.Azure	DI-Integration	dotnet add package Microsoft.Extensions.Azure
Azure.Identity.Broker	Vermittelte Authentifizierung	dotnet add package Azure.Identity.Broker

Referenzlinks

Ressource	URL
NuGet-Paket	https://www.nuget.org/packages/Azure.Identity
API-Referenz	https://learn.microsoft.com/dotnet/api/azure.identity
Anmeldeinformationsketten	https://aka.ms/azsdk/net/identity/credential-chains
Best Practices	https://learn.microsoft.com/dotnet/azure/sdk/authentication/best-practices
GitHub-Quelle	https://github.com/Azure/azure-sdk-for-net/tree/main/sdk/identity/Azure.Identity