microsoft/azure-identity-dotnet

Bibliothèque Azure Identity pour .NET

Bibliothèque d'authentification pour les clients SDK Azure utilisant Microsoft Entra ID.

Installation

dotnet add package Azure.Identity

# Pour l'intégration ASP.NET Core
dotnet add package Microsoft.Extensions.Azure

# Pour l'authentification intermédiée et la prise en charge des informations d'identification Visual Studio Code
dotnet add package Azure.Identity.Broker

Variables d'environnement

Principal de service avec secret

AZURE_CLIENT_ID=<identifiant-client-application>
AZURE_TENANT_ID=<identifiant-locataire-annuaire>
AZURE_CLIENT_SECRET=<valeur-secret-client>

Principal de service avec certificat

AZURE_CLIENT_ID=<identifiant-client-application>
AZURE_TENANT_ID=<identifiant-locataire-annuaire>
AZURE_CLIENT_CERTIFICATE_PATH=<chemin-vers-fichier-pfx-ou-pem>
AZURE_CLIENT_CERTIFICATE_PASSWORD=<mot-de-passe-certificat>  # Optionnel

Identité managée

AZURE_CLIENT_ID=<identifiant-client-identite-managee-attribuee-utilisateur>  # Uniquement pour attribuée à l'utilisateur

DefaultAzureCredential

L'information d'identification recommandée pour la plupart des scénarios. Essaie plusieurs méthodes d'authentification dans l'ordre. Voir Vue d'ensemble de DefaultAzureCredential pour l'ordre actuel de la chaîne d'informations d'identification et les valeurs par défaut.

Utilisation de base

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 avec injection de dépendances

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"));
    
    // Utilise DefaultAzureCredential par défaut
    clientBuilder.UseCredential(new DefaultAzureCredential());
});

Personnalisation de DefaultAzureCredential

var credential = new DefaultAzureCredential(
    new DefaultAzureCredentialOptions
    {
        ExcludeEnvironmentCredential = true,
        ExcludeManagedIdentityCredential = false,
        ExcludeVisualStudioCredential = false,
        ExcludeAzureCliCredential = false,
        ExcludeInteractiveBrowserCredential = false, // Activer l'interactif
        TenantId = "<identifiant-locataire>",
        ManagedIdentityClientId = "<identifiant-client-mi-attribuee-utilisateur>"
    });

Types d'informations d'identification

ManagedIdentityCredential (Production)

// Identité managée attribuée par le système
var credential = new ManagedIdentityCredential(ManagedIdentityId.SystemAssigned);

// Attribuée à l'utilisateur par identifiant client
var credential = new ManagedIdentityCredential(
    ManagedIdentityId.FromUserAssignedClientId("<identifiant-client>"));

// Attribuée à l'utilisateur par identifiant de ressource
var credential = new ManagedIdentityCredential(
    ManagedIdentityId.FromUserAssignedResourceId("<identifiant-ressource>"));

// Attribuée à l'utilisateur par identifiant d'objet
var credential = new ManagedIdentityCredential(
    ManagedIdentityId.FromUserAssignedObjectId("<identifiant-objet>"));

ClientSecretCredential

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

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

ClientCertificateCredential

var certificate = X509CertificateLoader.LoadCertificateFromFile("MonCertificat.pfx");
var credential = new ClientCertificateCredential(
    tenantId: "<identifiant-locataire>",
    clientId: "<identifiant-client>",
    certificate);

ChainedTokenCredential (Chaîne personnalisée)

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

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

Informations d'identification pour les développeurs

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

// Navigateur interactif
var credential = new InteractiveBrowserCredential();

Configuration basée sur l'environnement

// Production vs Développement
TokenCredential credential = builder.Environment.IsProduction()
    ? new ManagedIdentityCredential("<identifiant-client>")
    : new DefaultAzureCredential();

Nuages souverains

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

// Hôtes d'autorité disponibles :
// AzureAuthorityHosts.AzurePublicCloud (par défaut)
// AzureAuthorityHosts.AzureGovernment
// AzureAuthorityHosts.AzureChina

Référence des types d'informations d'identification

Catégorie	Information d'identification	Objectif
Chaînes	DefaultAzureCredential	Chaîne préconfigurée pour le développement à la production
	ChainedTokenCredential	Chaîne d'informations d'identification personnalisée
Hébergé Azure	ManagedIdentityCredential	Identité managée Azure
	WorkloadIdentityCredential	Identité de charge de travail Kubernetes
	EnvironmentCredential	Variables d'environnement
Principal de service	ClientSecretCredential	Identifiant client + secret
	ClientCertificateCredential	Identifiant client + certificat
	ClientAssertionCredential	Assertion client signée
Utilisateur	InteractiveBrowserCredential	Authentification par navigateur
	DeviceCodeCredential	Flux de code d'appareil
	OnBehalfOfCredential	Identité déléguée
Développeur	AzureCliCredential	Azure CLI
	AzurePowerShellCredential	Azure PowerShell
	AzureDeveloperCliCredential	Azure Developer CLI
	VisualStudioCredential	Visual Studio

Meilleures pratiques

1. Utiliser des informations d'identification déterministes en production

// Développement
var devCredential = new DefaultAzureCredential();

// Production - utiliser une information d'identification spécifique
var prodCredential = new ManagedIdentityCredential(
    ManagedIdentityId.FromUserAssignedClientId("<identifiant-client>"));

2. Réutiliser les instances d'informations d'identification

// Bon : Instance d'information d'identification unique partagée entre les clients
var credential = new DefaultAzureCredential();
var blobClient = new BlobServiceClient(blobUri, credential);
var secretClient = new SecretClient(vaultUri, credential);

3. Configurer les stratégies de nouvelle tentative

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

4. Activer la journalisation pour le débogage

using Azure.Core.Diagnostics;

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

Gestion des erreurs

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($"Échec d'authentification : {e.Message}");
}
catch (CredentialUnavailableException e)
{
    Console.WriteLine($"Information d'identification non disponible : {e.Message}");
}

Exceptions clés

Exception	Description
AuthenticationFailedException	Exception de base pour les erreurs d'authentification
CredentialUnavailableException	L'information d'identification ne peut pas authentifier dans l'environnement actuel
AuthenticationRequiredException	Une authentification interactive est requise

Prise en charge de l'identité managée

Services Azure pris en charge :

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

Sécurité des threads

Toutes les implémentations d'informations d'identification sont thread-safe. Une seule instance d'information d'identification peut être partagée en toute sécurité entre plusieurs clients et threads.

Packages associés

Package	Objectif	Installation
Azure.Identity	Authentification (cette bibliothèque)	dotnet add package Azure.Identity
Microsoft.Extensions.Azure	Intégration DI	dotnet add package Microsoft.Extensions.Azure
Azure.Identity.Broker	Authentification intermédiée	dotnet add package Azure.Identity.Broker

Liens de référence

Ressource	URL
Package NuGet	https://www.nuget.org/packages/Azure.Identity
Référence API	https://learn.microsoft.com/dotnet/api/azure.identity
Chaînes d'informations d'identification	https://aka.ms/azsdk/net/identity/credential-chains
Meilleures pratiques	https://learn.microsoft.com/dotnet/azure/sdk/authentication/best-practices
Source GitHub	https://github.com/Azure/azure-sdk-for-net/tree/main/sdk/identity/Azure.Identity