Fournisseur de configuration Azure Key Vault dans ASP.NET Core

Article
10/29/2024

Cet article explique comment utiliser le fournisseur de configuration Azure Key Vault pour charger des valeurs de configuration d’application à partir de secrets d’Azure Key Vault. Azure Key Vault est un service cloud qui protège les clés de chiffrement et les secrets utilisés par les applications et services cloud. Les scénarios courants d’utilisation d’Azure Key Vault avec les applications ASP.NET Core sont les suivants :

Contrôle de l’accès aux données de configuration sensibles.
Respect de la condition requise pour les modules de sécurité matérielle (HSM) FIPS 140-2 validés de niveau 2 lors du stockage des données de configuration.

Paquets

Ajoutez des références de package pour les packages suivants :

Exemple d'application

L’exemple d’application s’exécute dans l’un des deux modes déterminés par la #define directive de préprocesseur en haut de Program.cs :

Certificate : illustre l’utilisation d’un ID client Azure Key Vault et d’un certificat X.509 pour accéder aux secrets stockés dans Azure Key Vault. Cet exemple peut être exécuté à partir de n’importe quel emplacement, qu’il soit déployé sur Azure App Service ou tout hôte pouvant servir une application ASP.NET Core.
Managed : montre comment utiliser des identités managées pour les ressources Azure. L’identity managée authentifie l’application auprès d’Azure Key Vault avec les identités managées pour les ressources Azure sans stocker les informations d’identification dans le code ou la configuration de l’application. La version de l’exemple Managed doit être déployée sur Azure. Suivez les instructions de la section Utiliser les identités managées pour les ressources Azure.

Pour plus d’informations sur la configuration d’un exemple d’application à l’aide de directives de préprocesseur (#define), consultez Vue d’ensemble de ASP.NET Core.

Affichez ou téléchargez l’exemple de code (procédure de téléchargement)

Stockage secret dans l’environnement de développement

Définissez des secrets localement à l’aide du Gestionnaire de secrets. Lorsque l’exemple d’application s’exécute sur l’ordinateur local dans l’environnement de développement, les secrets sont chargés à partir du magasin de secrets utilisateur local.

Secret Manager nécessite une propriété <UserSecretsId> dans le fichier projet de l’application. Définissez la valeur de la propriété ({GUID}) sur n’importe quel GUID unique :

<PropertyGroup>
  <UserSecretsId>{GUID}</UserSecretsId>
</PropertyGroup>

Les secrets sont créés sous forme de paires nom-valeur. Les valeurs hiérarchiques (sections de configuration) utilisent un : (deux-points) comme séparateur dans les noms de clésConfiguration ASP.NET Core.

Le Secret Manager est utilisé à partir d’un interpréteur de commandes ouvert à la racine de contenu du projet, où {SECRET NAME} est le nom et {SECRET VALUE} la valeur :

dotnet user-secrets set "{SECRET NAME}" "{SECRET VALUE}"

Exécutez les commandes suivantes dans un interpréteur de commandes à partir de la racine de contenu du projet pour définir les secrets de l’exemple d’application :

dotnet user-secrets set "SecretName" "secret_value_1_dev"
dotnet user-secrets set "Section:SecretName" "secret_value_2_dev"

Lorsque ces secrets sont stockés dans Azure Key Vault dans la section Stockage secret dans l’environnement de production avec Azure Key Vault, le suffixe _dev est remplacé par _prod. Le suffixe fournit un repère visuel dans la sortie de l’application indiquant la source des valeurs de configuration.

Stockage secret dans l’environnement de production avec Azure Key Vault

Effectuez les étapes suivantes pour créer un Azure Key Vault et y stocker les secrets de l’exemple d’application. Pour plus d’informations, consultez Démarrage rapide : Définir et récupérer un secret depuis Azure Key Vault à l’aide d’Azure CLI.

Ouvrez Azure Cloud Shell à l’aide de l’une des méthodes suivantes dans le Portail Azure :
- Sélectionnez Essayer dans le coin supérieur droit d’un bloc de code. Utilisez la chaîne de recherche « Azure CLI » dans la zone de texte.
- Ouvrez Cloud Shell dans votre navigateur avec le bouton Lancer Cloud Shell.
- Sélectionnez le bouton Cloud Shell dans le menu en haut à droite du Portail Azure.
Pour plus d'informations, voir Azure CLI et Aperçu d'Azure Cloud Shell.
Si vous n’êtes pas encore authentifié, connectez-vous avec la commande az login.
Créez un groupe de ressources avec la commande suivante, où {RESOURCE GROUP NAME} correspond au nom du nouveau groupe de ressources et {LOCATION} à la région Azure :
```
az group create --name "{RESOURCE GROUP NAME}" --location {LOCATION}
```
Créez un coffre de clés dans le groupe de ressources avec la commande suivante, dans lequel {KEY VAULT NAME} est le nom du nouveau coffre et {LOCATION} la région Azure :
```
az keyvault create --name {KEY VAULT NAME} --resource-group "{RESOURCE GROUP NAME}" --location {LOCATION}
```
Créer des secrets dans le coffre sous forme de paires nom-valeur.

Les noms de secrets Azure Key Vault sont limités aux caractères alphanumériques et aux tirets. Les valeurs hiérarchiques (sections de configuration) utilisent -- (deux tirets) comme séparateur, car les deux points ne sont pas autorisés dans les noms de secrets du coffre de clés. Les deux-points délimitent une section d’une sous-clé dans ASP.NET Core configuration. La séquence à deux tirets est remplacée par un signe deux-points lorsque les secrets sont chargés dans la configuration de l’application.

Les secrets suivants sont à utiliser avec l’exemple d’application. Les valeurs incluent un _prod suffixe pour les distinguer des valeurs de suffixe _dev chargées dans l’environnement de développement à partir de Secret Manager. Remplacez {KEY VAULT NAME} par le nom du coffre de clés que vous avez créé à l'étape précédente :
```
az keyvault secret set --vault-name {KEY VAULT NAME} --name "SecretName" --value "secret_value_1_prod"
az keyvault secret set --vault-name {KEY VAULT NAME} --name "Section--SecretName" --value "secret_value_2_prod"
```

Utiliser l’ID d’application et le certificat X.509 pour les applications non hébergées sur Azure

Configurez Azure Key Vault et l’application pour utiliser un ID d’application Microsoft Entra ID et un certificat X.509 pour une authentification auprès d’un coffre lorsque l’application est hébergée en dehors d’Azure. Pour plus d’informations, consultez À propos des clés, des secrets et des certificats.

Notes

Bien que l’utilisation d’un ID d’application et d’un certificat X.509 soit prise en charge pour les applications hébergées dans Azure, elle n’est pas recommandée. Utilisez plutôt des identités managées pour les ressources Azure lors de l’hébergement d’une application dans Azure. Les identités managées ne nécessitent pas le stockage d’un certificat dans l’application ou dans l’environnement de développement.

L’exemple d’application utilise un ID d’application et un certificat X.509 lorsque la #define directive de préprocesseur en haut de Program.cs est définie sur Certificate.

Créez un certificat d’archive PKCS#12 (.pfx). Les options de création de certificats incluent New-SelfSignedCertificate sur Windows et OpenSSL.
Installez le certificat dans le magasin de certificats personnel de l’utilisateur actuel. Le marquage de la clé comme exportable est facultatif. Notez l’empreinte numérique du certificat, qui sera utilisée plus loin dans ce processus.
Exportez le certificat d’archive PKCS#12 (.pfx) sous la forme d’un certificat codé en DER (.cer).
Inscrire l’application auprès de Microsoft Entra ID (inscriptions d’applications).
Chargez le certificat encodé en DER (.cer) dans Microsoft Entra ID :
1. Sélectionnez l’application dans Microsoft Entra ID.
2. Accédez à Certificats et secrets.
3. Sélectionnez Charger le certificat pour charger le certificat, qui contient la clé publique. Un certificat .cer, .pem ou .crt est acceptable.
Stockez le nom du coffre de clés, l'identifiant d'application et l'empreinte du certificat dans le fichier appsettings.json de l'application.
Accédez à Coffre de clés dans le portail Azure.
Sélectionnez le coffre de clés que vous avez créé dans la section Stockage de secrets dans l'environnement de production avec Azure Key Vault.
Sélectionnez Stratégies d’accès.
Sélectionnez Ajouter une stratégie d’accès.
Ouvrez les autorisations de secret et fournissez à l’application les autorisations Get et List .
Sélectionnez Sélectionner un principal, puis sélectionnez l’application inscrite par nom. Sélectionnez le bouton Sélectionner.
Sélectionnez OK.
Sélectionnez Enregistrer.
Déployez l’application.

L’exemple d’application Certificate obtient ses valeurs de configuration avec IConfigurationRoot le même nom que le nom du secret :

Valeurs non hiérarchiques : la valeur pour SecretName est obtenue avec config["SecretName"].
Valeurs hiérarchiques (sections) : utilisez la notation (deux-points) : ou la méthode GetSection. Utilisez l’une de ces approches pour obtenir la valeur de configuration :
- config["Section:SecretName"]
- config.GetSection("Section")["SecretName"]

Le certificat X.509 est géré par le système d’exploitation. L’application appelle AddAzureKeyVault avec les valeurs fournies par le fichier appsettings.json :


using System.Security.Cryptography.X509Certificates;
using Azure.Identity;

var builder = WebApplication.CreateBuilder(args);

if (builder.Environment.IsProduction())
{
    using var x509Store = new X509Store(StoreLocation.CurrentUser);

    x509Store.Open(OpenFlags.ReadOnly);

    var x509Certificate = x509Store.Certificates
        .Find(
            X509FindType.FindByThumbprint,
            builder.Configuration["AzureADCertThumbprint"],
            validOnly: false)
        .OfType<X509Certificate2>()
        .Single();

    builder.Configuration.AddAzureKeyVault(
        new Uri($"https://{builder.Configuration["KeyVaultName"]}.vault.azure.net/"),
        new ClientCertificateCredential(
            builder.Configuration["AzureADDirectoryId"],
            builder.Configuration["AzureADApplicationId"],
            x509Certificate));
}

var app = builder.Build();

Exemples de valeurs

Nom du coffre de clés :contosovault
ID de l'application :00001111-aaaa-2222-bbbb-3333cccc4444
Empreinte de certificat :fe14593dd66b2406c5269d742d04b6e1ab03adb1

appsettings.json:

{
  "KeyVaultName": "Key Vault Name",
  "AzureADApplicationId": "Azure AD Application ID",
  "AzureADCertThumbprint": "Azure AD Certificate Thumbprint",
  "AzureADDirectoryId": "Azure AD Directory ID"
}

Lorsque vous exécutez l’application, une page web affiche les valeurs de secret chargées. Dans l’environnement de développement, les valeurs secrètes se chargent avec le suffixe _dev. Dans l’environnement production, les valeurs se chargent avec le suffixe _prod.

Utiliser des identités managées pour des ressources Azure

Une application déployée sur Azure peut tirer parti des identités managées pour les ressources Azure. Une identity managée permet à l’application de s’authentifier auprès d’Azure Key Vault à l’aide de l’authentification Microsoft Entra ID sans stocker d’informations d’identification dans le code ou la configuration de l’application.

L’exemple d’application utilise une identity managée affectée par le système lorsque la directive de préprocesseur #define en haut du Program.cs est définie sur Managed. Pour créer une identity managée pour une application Azure App Service, consultez la section Comment utiliser des identités managées pour App Service et Azure Functions. Une fois l’identity managée créée, notez l’ID d’objet de l’application affiché dans le Portail Azure dans le panneau Identity de l’App Service.

Entrez le nom du coffre dans le l’application appsettings.json. L’exemple d’application ne nécessite pas d’ID d’application et de mot de passe (clé secrète client) lorsqu’il est défini sur la version Managed. Vous pouvez donc ignorer ces entrées de configuration. L’application est déployée sur Azure et Azure l’authentifie pour accéder à Azure Key Vault uniquement en utilisant le nom du coffre stocké dans le fichier appsettings.json.

Déployer l’exemple dans Azure App Service.

À l'aide d'Azure CLI et de l'identifiant d'objet de l'application, fournissez à l'application les autorisations list et get pour accéder au coffre :

az keyvault set-policy --name {KEY VAULT NAME} --object-id {OBJECT ID} --secret-permissions get list

Redémarrez l’application à l’aide d’Azure CLI, de PowerShell ou du Portail Azure.

L’application exemple crée une instance de la classe DefaultAzureCredential. Les informations d’identification tentent d’obtenir un jeton d’accès à partir de l’environnement pour les ressources Azure :

using Azure.Identity;

var builder = WebApplication.CreateBuilder(args);

if (builder.Environment.IsProduction())
{
    builder.Configuration.AddAzureKeyVault(
        new Uri($"https://{builder.Configuration["KeyVaultName"]}.vault.azure.net/"),
        new DefaultAzureCredential());
}

Valeur d'exemple de nom de coffre de clés : contosovault

appsettings.json:

{
  "KeyVaultName": "Key Vault Name"
}

Pour les applications qui utilisent une identity managée affectée par l’utilisateur, configurez l’ID client de l’identity managée en utilisant l’une des approches suivantes :

Définissez la variable d’environnement AZURE_CLIENT_ID.

Définissez la propriété DefaultAzureCredentialOptions.ManagedIdentityClientId lors de l’appel de AddAzureKeyVault :

builder.Configuration.AddAzureKeyVault(
    new Uri($"https://{builder.Configuration["KeyVaultName"]}.vault.azure.net/"),
    new DefaultAzureCredential(new DefaultAzureCredentialOptions
    {
        ManagedIdentityClientId = builder.Configuration["AzureADManagedIdentityClientId"]
    }));

Lorsque vous exécutez l’application, une page web affiche les valeurs de secret chargées. Dans l’environnement de développement, les valeurs secrètes ont le suffixe _dev, car elles sont fournies par Secret Manager. Dans l’environnement de production, les valeurs se chargent avec le suffixe _prod, car elles sont fournies par Azure Key Vault.

Si vous recevez une erreur Access denied, vérifiez que l’application est inscrite auprès de Microsoft Entra ID et qu’elle a accès au coffre. Vérifiez que vous avez redémarré le service dans Azure.

Pour plus d’informations sur l’utilisation du fournisseur avec une identity managée et d’Azure Pipelines, consultez la section Créer une connexion de service Azure Resource Manager à une machine virtuelle avec une identity de service managée.

Options de configuration

AddAzureKeyVault peut accepter un objet AzureKeyVaultConfigurationOptions :

// using Azure.Extensions.AspNetCore.Configuration.Secrets;

builder.Configuration.AddAzureKeyVault(
    new Uri($"https://{builder.Configuration["KeyVaultName"]}.vault.azure.net/"),
    new DefaultAzureCredential(),
    new AzureKeyVaultConfigurationOptions
    {
        // ...
    });

L’objet AzureKeyVaultConfigurationOptions contient les propriétés suivantes :

Propriété	Description
Manager	Instance KeyVaultSecretManager utilisée pour contrôler le chargement du secret.
ReloadInterval	`TimeSpan` pour patienter entre les tentatives d'interrogation du coffre pour les modifications. La valeur par défaut est `null` (la configuration n’est pas rechargée).

Utiliser un préfixe de nom de clé

AddAzureKeyVault fournit une surcharge qui accepte une implémentation de KeyVaultSecretManager, ce qui vous permet de contrôler la façon dont les secrets du coffre de clés sont convertis en clés de configuration. Par exemple, vous pouvez implémenter l’interface pour charger des valeurs secrètes basées sur une valeur de préfixe que vous fournissez au démarrage de l’application. Cette technique vous permet, par exemple, de charger des secrets en fonction de la version de l’application.

Avertissement

N'utilisez pas de préfixes sur les secrets du coffre de clés pour :

Placez les secrets de plusieurs applications dans le même coffre.
Placez les secrets environnementaux (par exemple, les secrets de développement et de production ) dans le même coffre.

Différentes applications et les environnements de développement/production doivent utiliser des coffres de clés distincts pour isoler les environnements d'applications afin d'obtenir le niveau de sécurité le plus élevé.

Dans l'exemple suivant, un secret est établi dans le coffre de clés (et à l'aide de Secret Manager pour l'environnement de développement) pour 5000-AppSecret (les périodes ne sont pas autorisées dans les noms de secrets de coffre de clés). Ce secret représente un secret d’application pour la version 5.0.0.0 de l’application. Pour une autre version de l'application, 5.1.0.0, un secret est ajouté au coffre (et à l'aide de Secret Manager) pour 5100-AppSecret. Chaque version de l’application charge sa valeur de secret avec version dans sa configuration en tant que AppSecret, en supprimant la version au fur et à mesure qu’elle charge le secret.

AddAzureKeyVault est appelé avec une implémentation personnalisée KeyVaultSecretManager :

// using Azure.Extensions.AspNetCore.Configuration.Secrets;

builder.Configuration.AddAzureKeyVault(
    new Uri($"https://{builder.Configuration["KeyVaultName"]}.vault.azure.net/"),
    new DefaultAzureCredential(),
    new SamplePrefixKeyVaultSecretManager("5000"));

L’implémentation réagit aux préfixes de version des secrets pour charger le secret approprié dans la configuration :

Load charge un secret lorsque son nom commence par le préfixe. Les autres secrets ne sont pas chargés.
GetKey:
- Supprime le préfixe du nom du secret.
- Remplace deux tirets dans n’importe quel nom par le KeyDelimiter, qui est le délimiteur utilisé dans la configuration (généralement un signe deux-points). Azure Key Vault n’autorise pas de signe deux-points dans les noms de secrets.

public class SamplePrefixKeyVaultSecretManager : KeyVaultSecretManager
{
    private readonly string _prefix;

    public SamplePrefixKeyVaultSecretManager(string prefix)
        => _prefix = $"{prefix}-";

    public override bool Load(SecretProperties properties)
        => properties.Name.StartsWith(_prefix);

    public override string GetKey(KeyVaultSecret secret)
        => secret.Name[_prefix.Length..].Replace("--", ConfigurationPath.KeyDelimiter);
}

La méthode Load est appelée par un algorithme de fournisseur qui effectue une itération dans les secrets du coffre pour rechercher les secrets préfixés par la version. Lorsqu’un préfixe de version est trouvé avec Load, l’algorithme utilise la méthode GetKey pour retourner le nom de configuration du nom de secret. Il supprime le préfixe de version du nom du secret. Le rest du nom de secret est retourné pour le chargement dans les paires nom-valeur de configuration de l’application.

Lorsque cette approche est implémentée :

Version de l’application spécifiée dans le fichier projet de l’application. Dans l’exemple suivant, la version de l’application est définie sur 5.0.0.0 :
```
<PropertyGroup>
  <Version>5.0.0.0</Version>
</PropertyGroup>
```
Vérifiez qu’une propriété <UserSecretsId> est présente dans le fichier projet de l’application, où {GUID} est un GUID fourni par l’utilisateur :
```
<PropertyGroup>
  <UserSecretsId>{GUID}</UserSecretsId>
</PropertyGroup>
```
Enregistrez les secrets suivants localement avec Secret Manager :
```
dotnet user-secrets set "5000-AppSecret" "5.0.0.0_secret_value_dev"
dotnet user-secrets set "5100-AppSecret" "5.1.0.0_secret_value_dev"
```

Les secrets sont enregistrés dans Azure Key Vault à l’aide des commandes Azure CLI suivantes :

az keyvault secret set --vault-name {KEY VAULT NAME} --name "5000-AppSecret" --value "5.0.0.0_secret_value_prod"
az keyvault secret set --vault-name {KEY VAULT NAME} --name "5100-AppSecret" --value "5.1.0.0_secret_value_prod"

Lorsque l'application est exécutée, les secrets du coffre de clés sont chargés. Le secret de chaîne pour 5000-AppSecret est mis en correspondance avec la version de l’application spécifiée dans le fichier projet de l’application (5.0.0.0).
La version ( 5000 avec le tiret) est supprimée du nom de la clé. Dans l’application, la lecture de la configuration avec la clé AppSecret charge la valeur de secret.
Si la version de l’application est modifiée dans le fichier projet 5.1.0.0 et que l’application est réexécutée, la valeur secrète retournée est 5.1.0.0_secret_value_dev dans l’environnement de développement et 5.1.0.0_secret_value_prod en production.

Notes

Vous pouvez également fournir votre propre SecretClient implémentation à AddAzureKeyVault. Un client personnalisé permet de partager une seule instance du client dans l’application.

Lier un tableau à une classe

Le fournisseur peut lire les valeurs de configuration dans un tableau pour la liaison à un tableau POCO.

Lors de la lecture à partir d’une source de configuration qui permet aux clés de contenir des séparateurs deux-points (:), un segment de clé numérique est utilisé pour distinguer les clés qui composent un tableau (:0:, , :1:... :{n}:). Pour plus d’informations, consultez Configuration : Lier un tableau à une classe.

Les clés Azure Key Vault ne peuvent pas utiliser un signe deux-points comme séparateur. L’approche décrite dans cet article utilise des tirets doubles (--) comme séparateur pour les valeurs hiérarchiques (sections). Les clés de tableau sont stockées dans Azure Key Vault avec des tirets doubles et des segments de clé numériques (--0--, --1--, ... --{n}--).

Examinez la configuration suivante du fournisseur de journalisation Serilog fournie par un fichier JSON. Il existe deux littéraux d’objet définis dans le tableau WriteTo qui reflètent deux récepteurs Serilog, qui décrivent les destinations pour la sortie de journalisation :

"Serilog": {
  "WriteTo": [
    {
      "Name": "AzureTableStorage",
      "Args": {
        "storageTableName": "logs",
        "connectionString": "DefaultEnd...ountKey=Eby8...GMGw=="
      }
    },
    {
      "Name": "AzureDocumentDB",
      "Args": {
        "endpointUrl": "https://contoso.documents.azure.com:443",
        "authorizationKey": "Eby8...GMGw=="
      }
    }
  ]
}

La configuration indiquée dans le fichier JSON précédent est stockée dans Azure Key Vault à l’aide de la notation à double tiret (--) et des segments numériques :

Clé	Valeur
`Serilog--WriteTo--0--Name`	`AzureTableStorage`
`Serilog--WriteTo--0--Args--storageTableName`	`logs`
`Serilog--WriteTo--0--Args--connectionString`	`DefaultEnd...ountKey=Eby8...GMGw==`
`Serilog--WriteTo--1--Name`	`AzureDocumentDB`
`Serilog--WriteTo--1--Args--endpointUrl`	`https://contoso.documents.azure.com:443`
`Serilog--WriteTo--1--Args--authorizationKey`	`Eby8...GMGw==`

Recharger les secrets

Par défaut, les secrets sont mis en cache par le fournisseur de configuration pendant la durée de vie de l’application. Les secrets qui ont été désactivés ou mis à jour ultérieurement dans le coffre sont ignorés par l'application.

Pour recharger les secrets, appelez IConfigurationRoot.Reload :

config.Reload();

Pour recharger régulièrement les secrets, à un intervalle spécifié, définissez la propriété AzureKeyVaultConfigurationOptions.ReloadInterval. Pour plus d’informations, consultez Options de configuration.

Secrets désactivés et expirés

Les secrets expirés sont inclus par défaut dans le fournisseur de configuration. Pour exclure les valeurs de ces secrets dans la configuration de l'application, mettez à jour le secret expiré ou fournissez la configuration à l'aide d'un fournisseur de configuration personnalisé :

class SampleKeyVaultSecretManager : KeyVaultSecretManager
{
  public override bool Load(SecretProperties properties) =>
    properties.ExpiresOn.HasValue &&
    properties.ExpiresOn.Value > DateTimeOffset.Now;
}

Passez ce personnalisé KeyVaultSecretManager à AddAzureKeyVault :

// using Azure.Extensions.AspNetCore.Configuration.Secrets;

builder.Configuration.AddAzureKeyVault(
    new Uri($"https://{builder.Configuration["KeyVaultName"]}.vault.azure.net/"),
    new DefaultAzureCredential(),
    new SampleKeyVaultSecretManager());

Les secrets désactivés ne peuvent pas être récupérés à partir du coffre de clés et ne sont jamais inclus.

Résoudre les problèmes

Lorsque l’application ne parvient pas à charger la configuration à l’aide du fournisseur, un message d’erreur est écrit dans l’infrastructure de journalisation ASP.NET Core. Les conditions suivantes empêchent le chargement de la configuration :

L’application ou le certificat n’est pas configuré correctement dans Microsoft Entra ID.
Le coffre n'existe pas dans Azure Key Vault.
L'application n'est pas autorisée à accéder au coffre.
La stratégie d’accès n’inclut pas les autorisations Get et List .
Dans le coffre, les données de configuration (paire nom-valeur) sont incorrectement nommées, manquantes, ou désactivées.
L’application n’a pas le nom du coffre de clés (KeyVaultName), l’ID d’application Microsoft Entra ID (AzureADApplicationId), l’empreinte du certificat Microsoft Entra ID (AzureADCertThumbprint) ou l’ID d’annuaire Microsoft Entra ID (AzureADDirectoryId) approprié.
Lors de l'ajout de la stratégie d'accès au coffre de clés pour l'application, la stratégie a été créée, mais le bouton Enregistrer n'a pas été sélectionné dans l'interface utilisateur Stratégies d'accès.

Ressources supplémentaires

Contrôle de l’accès aux données de configuration sensibles.
Respect de la condition requise pour les modules de sécurité matérielle (HSM) FIPS 140-2 validés de niveau 2 lors du stockage des données de configuration.

Paquets

Ajoutez des références de package pour les packages suivants :

Exemple d'application

L’exemple d’application s’exécute dans l’un des deux modes déterminés par la #define directive de préprocesseur en haut de Program.cs :

Certificate : illustre l’utilisation d’un ID client Azure Key Vault et d’un certificat X.509 pour accéder aux secrets stockés dans Azure Key Vault. Cet exemple peut être exécuté à partir de n’importe quel emplacement, qu’il soit déployé sur Azure App Service ou tout hôte pouvant servir une application ASP.NET Core.
Managed : montre comment utiliser des identités managées pour les ressources Azure. L’identity managée authentifie l’application auprès d’Azure Key Vault avec les identités managées pour les ressources Azure sans les informations d’identification stockées dans le code ou la configuration de l’application. Lorsque vous utilisez des identités managées pour l’authentification, des identités managées pour l’ID d’application et le mot de passe (secret client) des ressources Azure ne sont pas nécessaires. La version de l’exemple Managed doit être déployée sur Azure. Suivez les instructions de la section Utiliser les identités managées pour les ressources Azure.

Pour plus d’informations sur la configuration d’un exemple d’application à l’aide de directives de préprocesseur (#define), consultez Vue d’ensemble de ASP.NET Core.

Affichez ou téléchargez l’exemple de code (procédure de téléchargement)

Stockage secret dans l’environnement de développement

Secret Manager nécessite une propriété <UserSecretsId> dans le fichier projet de l’application. Définissez la valeur de la propriété ({GUID}) sur n’importe quel GUID unique :

<PropertyGroup>
  <UserSecretsId>{GUID}</UserSecretsId>
</PropertyGroup>

Le Secret Manager est utilisé à partir d’un interpréteur de commandes ouvert à la racine de contenu du projet, où {SECRET NAME} est le nom et {SECRET VALUE} la valeur :

dotnet user-secrets set "{SECRET NAME}" "{SECRET VALUE}"

Exécutez les commandes suivantes dans un interpréteur de commandes à partir de la racine de contenu du projet pour définir les secrets de l’exemple d’application :

dotnet user-secrets set "SecretName" "secret_value_1_dev"
dotnet user-secrets set "Section:SecretName" "secret_value_2_dev"

Stockage secret dans l’environnement de production avec Azure Key Vault

Ouvrez Azure Cloud Shell à l’aide de l’une des méthodes suivantes dans le Portail Azure :
- Sélectionnez Essayer dans le coin supérieur droit d’un bloc de code. Utilisez la chaîne de recherche « Azure CLI » dans la zone de texte.
- Ouvrez Cloud Shell dans votre navigateur avec le bouton Lancer Cloud Shell.
- Sélectionnez le bouton Cloud Shell dans le menu en haut à droite du Portail Azure.
Pour plus d'informations, voir Azure CLI et Aperçu d'Azure Cloud Shell.
Si vous n’êtes pas encore authentifié, connectez-vous avec la commande az login.
Créez un groupe de ressources avec la commande suivante, où {RESOURCE GROUP NAME} correspond au nom du nouveau groupe de ressources et {LOCATION} à la région Azure :
```
az group create --name "{RESOURCE GROUP NAME}" --location {LOCATION}
```
Créez un coffre de clés dans le groupe de ressources avec la commande suivante, dans lequel {KEY VAULT NAME} est le nom du nouveau coffre et {LOCATION} la région Azure :
```
az keyvault create --name {KEY VAULT NAME} --resource-group "{RESOURCE GROUP NAME}" --location {LOCATION}
```
Créer des secrets dans le coffre sous forme de paires nom-valeur.

Les noms de secrets Azure Key Vault sont limités aux caractères alphanumériques et aux tirets. Les valeurs hiérarchiques (sections de configuration) utilisent -- (deux tirets) comme séparateur, car les deux points ne sont pas autorisés dans les noms de secrets du coffre de clés. Les deux-points délimitent une section d’une sous-clé dans ASP.NET Core configuration. La séquence à deux tirets est remplacée par un signe deux-points lorsque les secrets sont chargés dans la configuration de l’application.

Les secrets suivants sont à utiliser avec l’exemple d’application. Les valeurs incluent un _prod suffixe pour les distinguer des valeurs de suffixe _dev chargées dans l’environnement de développement à partir de Secret Manager. Remplacez {KEY VAULT NAME} par le nom du coffre de clés que vous avez créé à l'étape précédente :
```
az keyvault secret set --vault-name {KEY VAULT NAME} --name "SecretName" --value "secret_value_1_prod"
az keyvault secret set --vault-name {KEY VAULT NAME} --name "Section--SecretName" --value "secret_value_2_prod"
```

Utiliser l’ID d’application et le certificat X.509 pour les applications non hébergées sur Azure

Notes

L’exemple d’application utilise un ID d’application et un certificat X.509 lorsque la #define directive de préprocesseur en haut de Program.cs est définie sur Certificate.

Créez un certificat d’archive PKCS#12 (.pfx). Les options de création de certificats incluent New-SelfSignedCertificate sur Windows et OpenSSL.
Installez le certificat dans le magasin de certificats personnel de l’utilisateur actuel. Le marquage de la clé comme exportable est facultatif. Notez l’empreinte numérique du certificat, qui sera utilisée plus loin dans ce processus.
Exportez le certificat d’archive PKCS#12 (.pfx) sous la forme d’un certificat codé en DER (.cer).
Inscrire l’application auprès de Microsoft Entra ID (inscriptions d’applications).
Chargez le certificat encodé en DER (.cer) dans Microsoft Entra ID :
1. Sélectionnez l’application dans Microsoft Entra ID.
2. Accédez à Certificats et secrets.
3. Sélectionnez Charger le certificat pour charger le certificat, qui contient la clé publique. Un certificat .cer, .pem ou .crt est acceptable.
Stockez le nom du coffre de clés, l'identifiant d'application et l'empreinte du certificat dans le fichier appsettings.json de l'application.
Accédez à Coffre de clés dans le portail Azure.
Sélectionnez le coffre de clés que vous avez créé dans la section Stockage de secrets dans l'environnement de production avec Azure Key Vault.
Sélectionnez Stratégies d’accès.
Sélectionnez Ajouter une stratégie d’accès.
Ouvrez les autorisations de secret et fournissez à l’application les autorisations Get et List .
Sélectionnez Sélectionner un principal, puis sélectionnez l’application inscrite par nom. Sélectionnez le bouton Sélectionner.
Sélectionnez OK.
Sélectionnez Enregistrer.
Déployez l’application.

L’exemple d’application Certificate obtient ses valeurs de configuration avec IConfigurationRoot le même nom que le nom du secret :

Valeurs non hiérarchiques : la valeur pour SecretName est obtenue avec config["SecretName"].
Valeurs hiérarchiques (sections) : utilisez la notation (deux-points) : ou la méthode GetSection. Utilisez l’une de ces approches pour obtenir la valeur de configuration :
- config["Section:SecretName"]
- config.GetSection("Section")["SecretName"]

Le certificat X.509 est géré par le système d’exploitation. L’application appelle AddAzureKeyVault avec les valeurs fournies par le fichier appsettings.json :

// using System.Linq;
// using System.Security.Cryptography.X509Certificates;
// using Azure.Extensions.AspNetCore.Configuration.Secrets;
// using Azure.Identity;

public static IHostBuilder CreateHostBuilder(string[] args) =>
    Host.CreateDefaultBuilder(args)
        .ConfigureAppConfiguration((context, config) =>
        {
            if (context.HostingEnvironment.IsProduction())
            {
                var builtConfig = config.Build();

                using var store = new X509Store(StoreLocation.CurrentUser);
                store.Open(OpenFlags.ReadOnly);
                var certs = store.Certificates.Find(
                    X509FindType.FindByThumbprint,
                    builtConfig["AzureADCertThumbprint"], false);

                config.AddAzureKeyVault(new Uri($"https://{builtConfig["KeyVaultName"]}.vault.azure.net/"),
                                        new ClientCertificateCredential(builtConfig["AzureADDirectoryId"], builtConfig["AzureADApplicationId"], certs.OfType<X509Certificate2>().Single()),
                                        new KeyVaultSecretManager());

                store.Close();
            }
        })
        .ConfigureWebHostDefaults(webBuilder => webBuilder.UseStartup<Startup>());

Exemples de valeurs

Nom du coffre de clés :contosovault
ID de l'application :00001111-aaaa-2222-bbbb-3333cccc4444
Empreinte de certificat :fe14593dd66b2406c5269d742d04b6e1ab03adb1

appsettings.json:

{
  "KeyVaultName": "Key Vault Name",
  "AzureADApplicationId": "Azure AD Application ID",
  "AzureADCertThumbprint": "Azure AD Certificate Thumbprint",
  "AzureADDirectoryId": "Azure AD Directory ID"
}

Utiliser des identités managées pour des ressources Azure

Une application déployée sur Azure peut tirer parti des identités managées pour les ressources Azure. Une identity managée permet à l’application de s’authentifier auprès d’Azure Key Vault à l’aide de l’authentification Microsoft Entra ID sans informations d’identification (ID d’application et mot de passe/secret client) stockées dans l’application.

L’exemple d’application utilise des identités managées pour les ressources Azure lorsque la #define directive de préprocesseur en haut de Program.cs est définie sur Managed.

Déployer l’exemple dans Azure App Service.

Une application déployée sur Azure App Service est automatiquement inscrite auprès de Microsoft Entra ID lors de la création du service. Obtenez l’ID d’objet du déploiement à utiliser dans la commande suivante. L’ID d’objet s’affiche dans le Portail Azure du Identity panneau du App Service.

À l'aide d'Azure CLI et de l'identifiant d'objet de l'application, fournissez à l'application les autorisations list et get pour accéder au coffre :

az keyvault set-policy --name {KEY VAULT NAME} --object-id {OBJECT ID} --secret-permissions get list

Redémarrez l’application à l’aide d’Azure CLI, de PowerShell ou du Portail Azure.

Exemple d’application :

Crée une instance de la classe DefaultAzureCredential. Les informations d’identification tentent d’obtenir un jeton d’accès à partir de l’environnement pour les ressources Azure.
Un nouveau SecretClient est créé avec l’instance DefaultAzureCredential.
L’instance SecretClient est utilisé avec une instance KeyVaultSecretManager, qui charge des valeurs secrètes et remplace les tirets doubles (--) par les deux-points (:) dans les noms de clé.

// using Azure.Security.KeyVault.Secrets;
// using Azure.Identity;
// using Azure.Extensions.AspNetCore.Configuration.Secrets;

public static IHostBuilder CreateHostBuilder(string[] args) =>
    Host.CreateDefaultBuilder(args)
        .ConfigureAppConfiguration((context, config) =>
        {
            if (context.HostingEnvironment.IsProduction())
            {
                var builtConfig = config.Build();
                var secretClient = new SecretClient(
                    new Uri($"https://{builtConfig["KeyVaultName"]}.vault.azure.net/"),
                    new DefaultAzureCredential());
                config.AddAzureKeyVault(secretClient, new KeyVaultSecretManager());
            }
        })
        .ConfigureWebHostDefaults(webBuilder => webBuilder.UseStartup<Startup>());

Valeur d'exemple de nom de coffre de clés : contosovault

appsettings.json:

{
  "KeyVaultName": "Key Vault Name"
}

Options de configuration

AddAzureKeyVault peut accepter un objet AzureKeyVaultConfigurationOptions :

config.AddAzureKeyVault(
    new SecretClient(
        new Uri("Your Key Vault Endpoint"),
        new DefaultAzureCredential(),
        new AzureKeyVaultConfigurationOptions())
    {
        ...
    });

L’objet AzureKeyVaultConfigurationOptions contient les propriétés suivantes.

Propriété	Description
Manager	Instance KeyVaultSecretManager utilisée pour contrôler le chargement du secret.
ReloadInterval	`TimeSpan` pour patienter entre les tentatives d'interrogation du coffre pour les modifications. La valeur par défaut est `null` (la configuration n’est pas rechargée).

Utiliser un préfixe de nom de clé

Avertissement

N'utilisez pas de préfixes sur les secrets du coffre de clés pour :

Placez les secrets de plusieurs applications dans le même coffre.
Placez les secrets environnementaux (par exemple, les secrets de développement et de production ) dans le même coffre.

AddAzureKeyVault est appelé avec une implémentation personnalisée KeyVaultSecretManager :

config.AddAzureKeyVault(
    $"https://{builtConfig["KeyVaultName"]}.vault.azure.net/",
    builtConfig["AzureADApplicationId"],
    certs.OfType<X509Certificate2>().Single(),
    new PrefixKeyVaultSecretManager(versionPrefix));

L’implémentation réagit aux préfixes de version des secrets pour charger le secret approprié dans la configuration :

Load charge un secret lorsque son nom commence par le préfixe. Les autres secrets ne sont pas chargés.
GetKey:
- Supprime le préfixe du nom du secret.
- Remplace deux tirets dans n’importe quel nom par le KeyDelimiter, qui est le délimiteur utilisé dans la configuration (généralement un signe deux-points). Azure Key Vault n’autorise pas de signe deux-points dans les noms de secrets.

public class PrefixKeyVaultSecretManager : KeyVaultSecretManager
{
    private readonly string _prefix;

    public PrefixKeyVaultSecretManager(string prefix)
    {
        _prefix = $"{prefix}-";
    }

    public override bool Load(SecretProperties secret)
    {
        return secret.Name.StartsWith(_prefix);
    }

    public override string GetKey(KeyVaultSecret secret)
    {
        return secret.Name
            .Substring(_prefix.Length)
            .Replace("--", ConfigurationPath.KeyDelimiter);
    }
}

Lorsque cette approche est implémentée :

Version de l’application spécifiée dans le fichier projet de l’application. Dans l’exemple suivant, la version de l’application est définie sur 5.0.0.0 :
```
<PropertyGroup>
  <Version>5.0.0.0</Version>
</PropertyGroup>
```
Vérifiez qu’une propriété <UserSecretsId> est présente dans le fichier projet de l’application, où {GUID} est un GUID fourni par l’utilisateur :
```
<PropertyGroup>
  <UserSecretsId>{GUID}</UserSecretsId>
</PropertyGroup>
```
Enregistrez les secrets suivants localement avec Secret Manager :
```
dotnet user-secrets set "5000-AppSecret" "5.0.0.0_secret_value_dev"
dotnet user-secrets set "5100-AppSecret" "5.1.0.0_secret_value_dev"
```

Les secrets sont enregistrés dans Azure Key Vault à l’aide des commandes Azure CLI suivantes :

az keyvault secret set --vault-name {KEY VAULT NAME} --name "5000-AppSecret" --value "5.0.0.0_secret_value_prod"
az keyvault secret set --vault-name {KEY VAULT NAME} --name "5100-AppSecret" --value "5.1.0.0_secret_value_prod"

Lorsque l'application est exécutée, les secrets du coffre de clés sont chargés. Le secret de chaîne pour 5000-AppSecret est mis en correspondance avec la version de l’application spécifiée dans le fichier projet de l’application (5.0.0.0).
La version ( 5000 avec le tiret) est supprimée du nom de la clé. Dans l’application, la lecture de la configuration avec la clé AppSecret charge la valeur de secret.
Si la version de l’application est modifiée dans le fichier projet 5.1.0.0 et que l’application est réexécutée, la valeur secrète retournée est 5.1.0.0_secret_value_dev dans l’environnement de développement et 5.1.0.0_secret_value_prod en production.

Notes

Vous pouvez également fournir votre propre SecretClient implémentation à AddAzureKeyVault. Un client personnalisé permet de partager une seule instance du client dans l’application.

Lier un tableau à une classe

Le fournisseur peut lire les valeurs de configuration dans un tableau pour la liaison à un tableau POCO.

"Serilog": {
  "WriteTo": [
    {
      "Name": "AzureTableStorage",
      "Args": {
        "storageTableName": "logs",
        "connectionString": "DefaultEnd...ountKey=Eby8...GMGw=="
      }
    },
    {
      "Name": "AzureDocumentDB",
      "Args": {
        "endpointUrl": "https://contoso.documents.azure.com:443",
        "authorizationKey": "Eby8...GMGw=="
      }
    }
  ]
}

La configuration indiquée dans le fichier JSON précédent est stockée dans Azure Key Vault à l’aide de la notation à double tiret (--) et des segments numériques :

Clé	Valeur
`Serilog--WriteTo--0--Name`	`AzureTableStorage`
`Serilog--WriteTo--0--Args--storageTableName`	`logs`
`Serilog--WriteTo--0--Args--connectionString`	`DefaultEnd...ountKey=Eby8...GMGw==`
`Serilog--WriteTo--1--Name`	`AzureDocumentDB`
`Serilog--WriteTo--1--Args--endpointUrl`	`https://contoso.documents.azure.com:443`
`Serilog--WriteTo--1--Args--authorizationKey`	`Eby8...GMGw==`

Recharger les secrets

Les secrets sont mis en cache jusqu’à ce que IConfigurationRoot.Reload soit appelé. Les secrets désactivés ou mis à jour ultérieurement dans le coffre ne sont pas respectés par l'application tant que Reload n'est pas exécuté.

Configuration.Reload();

Secrets désactivés et expirés

class SampleKeyVaultSecretManager : KeyVaultSecretManager
{
  public override bool Load(SecretProperties properties) =>
    properties.ExpiresOn.HasValue &&
    properties.ExpiresOn.Value > DateTimeOffset.Now;
}

Passez ce personnalisé KeyVaultSecretManager à AddAzureKeyVault :

// using Azure.Extensions.AspNetCore.Configuration.Secrets;

config.AddAzureKeyVault(
    new Uri($"https://{builder.Configuration["KeyVaultName"]}.vault.azure.net/"),
    new DefaultAzureCredential(),
    new SampleKeyVaultSecretManager());

Les secrets désactivés ne peuvent pas être récupérés à partir du coffre de clés et ne sont jamais inclus.

Résoudre les problèmes

L’application ou le certificat n’est pas configuré correctement dans Microsoft Entra ID.
Le coffre n'existe pas dans Azure Key Vault.
L'application n'est pas autorisée à accéder au coffre.
La stratégie d’accès n’inclut pas les autorisations Get et List .
Dans le coffre, les données de configuration (paire nom-valeur) sont incorrectement nommées, manquantes, ou désactivées.
L’application n’a pas le nom du coffre de clés (KeyVaultName), l’ID d’application Microsoft Entra ID (AzureADApplicationId), l’empreinte du certificat Microsoft Entra ID (AzureADCertThumbprint) ou l’ID d’annuaire Microsoft Entra ID (AzureADDirectoryId) approprié.
Lors de l'ajout de la stratégie d'accès au coffre de clés pour l'application, la stratégie a été créée, mais le bouton Enregistrer n'a pas été sélectionné dans l'interface utilisateur Stratégies d'accès.

Partager via

Fournisseur de configuration Azure Key Vault dans ASP.NET Core

Paquets

Exemple d'application

Stockage secret dans l’environnement de développement

Stockage secret dans l’environnement de production avec Azure Key Vault

Utiliser l’ID d’application et le certificat X.509 pour les applications non hébergées sur Azure

Utiliser des identités managées pour des ressources Azure

Options de configuration

Utiliser un préfixe de nom de clé

Lier un tableau à une classe

Recharger les secrets

Secrets désactivés et expirés

Résoudre les problèmes

Ressources supplémentaires

Paquets

Exemple d'application

Stockage secret dans l’environnement de développement

Stockage secret dans l’environnement de production avec Azure Key Vault

Utiliser l’ID d’application et le certificat X.509 pour les applications non hébergées sur Azure

Utiliser des identités managées pour des ressources Azure

Options de configuration

Utiliser un préfixe de nom de clé

Lier un tableau à une classe

Recharger les secrets

Secrets désactivés et expirés

Résoudre les problèmes

Ressources supplémentaires

Ressources supplémentaires