Stockage sécurisé des secrets d’application en développement dans ASP.NET Core

Par Rick Anderson et Kirk Larkin

Cet article explique comment gérer des données sensibles pour une application ASP.NET Core sur un ordinateur de développement. Ne stockez jamais de mots de passe ou d’autres données sensibles dans le code source ou les fichiers de configuration. Les secrets de production ne doivent pas être utilisés pour le développement ou les tests. Les secrets ne doivent pas être déployés avec l'application. Les secrets de production doivent être accessibles par le biais d’un moyen contrôlé comme Azure Key Vault. Les secrets de test et de production Azure peuvent être stockés et protégés avec le fournisseur de configuration Azure Key Vault.

Afficher ou télécharger l’exemple de code (comment télécharger)

Pour plus d’informations sur l’authentification pour les applications de test et de production déployées, consultez Flux d’authentification sécurisés.

Pour utiliser des secrets utilisateur dans une application console .NET, consultez GitHub dotnet/entityframework.docs issue #3939.

Utiliser des variables d’environnement

Les variables d'environnement sont utilisées pour éviter le stockage des secrets d'application dans le code ou dans les fichiers de configuration locaux. Les variables d'environnement remplacent les valeurs de configuration pour toutes les sources de configuration précédemment spécifiées.

Considérez une application web ASP.NET Core dans laquelle la sécurité des comptes individuels est activée. Une chaîne de connexion à la base de données par défaut est incluse dans le fichier appsettings.json du projet avec la clé DefaultConnection. La chaîne de connexion par défaut est pour Base de données locale, qui s'exécute en mode utilisateur et ne nécessite pas de mot de passe. Pendant le déploiement de l’application, vous pouvez remplacer la DefaultConnection valeur de clé par la valeur d’une variable d’environnement. La variable d’environnement peut stocker le chaîne de connexion complet avec des informations d’identification sensibles.

Warning

Les variables d’environnement sont généralement stockées sous forme de texte brut et non chiffré. Si l’ordinateur ou le processus est compromis, les variables d’environnement sont accessibles aux parties non approuvées. Des mesures supplémentaires pour empêcher la divulgation de secrets utilisateur peuvent être requises.

Le séparateur deux-points (:) ne fonctionne pas avec les clés hiérarchiques des variables d’environnement sur toutes les plateformes. Par exemple, Bash ne prend pas en charge le signe deux-points (:) comme séparateur. Toutes les plateformes prennent en charge la syntaxe de trait de soulignement double (__) et la remplacent automatiquement par un signe deux-points (:).

Utiliser l’outil Gestionnaire de secrets

Secret Manager est un outil qui stocke des données sensibles pendant le développement d’applications. Dans ce contexte, un élément de données sensibles est un secret d’application.

• Les secrets d'application sont stockés dans un emplacement distinct de l'arborescence du projet.
• Ils sont associés à un projet spécifique ou partagés entre plusieurs projets.
• Ils ne sont pas enregistrés dans le système de gestion de versions.

Warning

Secret Manager ne chiffre pas les secrets stockés et ne doit pas être traité comme un magasin approuvé. C'est uniquement à des fins de développement. Les clés et les valeurs sont stockées dans un fichier de configuration JSON dans le répertoire du profil utilisateur.

Secret Manager masque les détails de l’implémentation, tels que l’emplacement et la façon dont les valeurs sont stockées. Vous pouvez utiliser l'outil sans connaître ces détails de mise en œuvre. Les valeurs sont stockées dans un fichier JSON dans le dossier de profil utilisateur de la machine locale :

Windows

Chemin du système de fichiers :

%APPDATA%\Microsoft\UserSecrets\<user_secrets_id>\secrets.json

Linux / macOS

Chemin du système de fichiers :

~/.microsoft/usersecrets/<user_secrets_id>/secrets.json

Dans le chemin du système de fichiers, remplacez la <user_secrets_id> partie par la UserSecretsId valeur spécifiée dans votre fichier projet.

N’écrivez pas de code qui dépend de l’emplacement ou du format des données enregistrées avec Secret Manager. Ces détails d’implémentation peuvent changer. Par exemple, les valeurs secrètes ne sont pas chiffrées.

Activer le stockage secret

Secret Manager fonctionne sur les paramètres de configuration spécifiques au projet stockés dans votre profil utilisateur.

Utiliser l’interface CLI

Secret Manager inclut une init commande. Pour utiliser les secrets utilisateur, exécutez la commande suivante dans le répertoire du projet :

dotnet user-secrets init

Cette commande ajoute un UserSecretsId élément dans un PropertyGroup fichier projet. Par défaut, le texte interne de UserSecretsId est un GUID. Le texte intérieur est arbitraire, mais unique au projet. L’exemple suivant montre une valeur GUID de 0000a1a1-b2b2-c3c3-d4d4-eeeeee555555.

<Project Sdk="Microsoft.NET.Sdk.Web">

  <PropertyGroup>
    <TargetFramework>net9.0</TargetFramework>
    <UserSecretsId>0000a1a1-b2b2-c3c3-d4d4-eeeeee555555</UserSecretsId>
  </PropertyGroup>

</Project>

Utiliser Visual Studio

Dans Visual Studio, cliquez avec le bouton droit sur le projet dans l'Explorateur de solutions et sélectionnez Gérer les secrets utilisateur dans le menu contextuel. Ce geste ajoute un élément UserSecretsId, rempli d'un GUID, au fichier de projet.

Si « GenerateAssemblyInfo » est « false »

Si la génération des attributs d’informations d’assembly (GenerateAssemblyInfo) est désactivée (définie sur false), ajoutez manuellement le UserSecretsIdAttribute dans le fichier AssemblyInfo.cs. Par exemple:

[assembly: UserSecretsId("your_user_secrets_id")]

Lorsque vous ajoutez manuellement l’attribut UserSecretsId au fichier AssemblyInfo.cs , la UserSecretsId valeur doit correspondre à la valeur dans le fichier projet.

Définir un secret

Définissez un secret d'application composé d'une clé et de sa valeur. Le secret est associé à la valeur UserSecretsId du projet. Par exemple, exécutez la commande suivante à partir du répertoire dans lequel se trouve le fichier projet :

dotnet user-secrets set "Movies:ServiceApiKey" "12345"

Dans cet exemple, les deux-points indiquent qu’il s’agit de Movies un littéral d’objet avec une propriété ServiceApiKey.

Vous pouvez également utiliser Secret Manager à partir d’autres répertoires. Incluez l’option --project permettant de fournir le chemin du système de fichiers auquel le fichier projet existe. Par exemple:

dotnet user-secrets set "Movies:ServiceApiKey" "12345" --project "C:\apps\WebApp1\src\WebApp1"

L’aplatissement de la structure JSON dans Visual Studio

Le mouvement Visual Studio Manage User Secrets ouvre un fichier secrets.json dans l’éditeur de texte. Remplacez le contenu du fichier secrets.json par les paires clé-valeur à stocker. Par exemple:

{
  "Movies": {
    "ConnectionString": "Server=(localdb)\\mssqllocaldb;Database=Movie-1;Trusted_Connection=True;MultipleActiveResultSets=true",
    "ServiceApiKey": "12345"
  }
}

La structure JSON est mise à plat après des modifications via la commande dotnet user-secrets remove ou dotnet user-secrets set. Par exemple, l'exécution de dotnet user-secrets remove "Movies:ConnectionString" réduit le littéral d'objet Movies. Le fichier modifié ressemble au JSON suivant :

{
  "Movies:ServiceApiKey": "12345"
}

Définir plusieurs secrets

Un lot de secrets peut être défini en redirigeant JSON vers la commande set. Dans l’exemple suivant, le contenu du fichier input.json est redirigé vers la set commande.

Windows

Exécutez la commande suivante:

type .\input.json | dotnet user-secrets set

Linux / macOS

Exécutez la commande suivante dans un terminal :

cat ./input.json | dotnet user-secrets set

Accéder à un secret

Pour accéder à un secret, procédez comme suit :

1. Inscrivez la source de configuration des secrets utilisateur.

2. Lisez le secret via l’API configuration.

Enregistrer la source de configuration des secrets d'utilisateur

Le fournisseur de configuration des secrets utilisateur enregistre la source de configuration appropriée avec l'API de configuration .NET.

Les applications web ASP.NET Core créées avec la commande dotnet new ou Visual Studio génèrent le code suivant :

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

app.MapGet("/", () => "Hello World!");

app.Run();

La méthode WebApplication.CreateBuilder initialise une nouvelle instance de la WebApplicationBuilder classe avec des valeurs par défaut préconfigurées. L’élément initialisé WebApplicationBuilder (builder) fournit une configuration par défaut et appelle la méthode AddUserSecrets lorsque la propriété EnvironmentName est définie sur Development.

Lire le secret via l'API de configuration

Les exemples suivants montrent comment lire la Movies:ServiceApiKey clé :

le fichier Program.cs

var builder = WebApplication.CreateBuilder(args);
var movieApiKey = builder.Configuration["Movies:ServiceApiKey"];

var app = builder.Build();

app.MapGet("/", () => movieApiKey);

app.Run();

Razor Modèle de page Pages

public class IndexModel : PageModel
{
    private readonly IConfiguration _config;

    public IndexModel(IConfiguration config)
    {
        _config = config;
    }

    public void OnGet()
    {
        var moviesApiKey = _config["Movies:ServiceApiKey"];

        // call Movies service with the API key
    }
}

Pour plus d’informations, consultez Configuration dans ASP.NET Core.

Cartographier les secrets d'un POCO

Le mappage d'un littéral d'objet entier à un POCO (une classe .NET simple avec des propriétés) est utile pour agréger les propriétés associées.

Supposons que le fichier secrets.json de l’application contient les deux secrets suivants :

{
  "Movies:ConnectionString": "Server=(localdb)\\mssqllocaldb;Database=Movie-1;Trusted_Connection=True;MultipleActiveResultSets=true",
  "Movies:ServiceApiKey": "12345"
}

Pour mapper les secrets précédents à un POCO, utilisez la fonctionnalité de liaison de graphe d'objet de l'API de configuration .NET. Le code suivant se lie à un POCO personnalisé MovieSettings et accède à la valeur de la propriété ServiceApiKey :

var moviesConfig = 
    Configuration.GetSection("Movies").Get<MovieSettings>();
_moviesApiKey = moviesConfig.ServiceApiKey;

Les secrets Movies:ConnectionString et Movies:ServiceApiKey sont mappés aux propriétés respectives dans MovieSettings :

public class MovieSettings
{
    public string ConnectionString { get; set; }

    public string ServiceApiKey { get; set; }
}

Utiliser le remplacement de chaîne avec des secrets

Le stockage des mots de passe en texte brut n'est pas sécurisé. Ne stockez jamais de secrets dans un fichier de configuration tel que appsettings.json, qui peut être archivé dans un référentiel de code source.

Par exemple, une base de données chaîne de connexion stockée dans un fichier appsettings.json ne doit pas inclure de mot de passe. Au lieu de cela, stockez le mot de passe en tant que secret et incluez le mot de passe dans le chaîne de connexion au moment de l’exécution. Par exemple:

dotnet user-secrets set "DbPassword" "`<secret value>`"

Remplacez l’espace réservé <secret value> dans l’exemple par la valeur du mot de passe. Définissez la valeur du secret sur la propriété d’un SqlConnectionStringBuilderPassword objet pour l’inclure comme valeur de mot de passe dans l’chaîne de connexion :

using System.Data.SqlClient;

var builder = WebApplication.CreateBuilder(args);

var conStrBuilder = new SqlConnectionStringBuilder(
        builder.Configuration.GetConnectionString("Movies"));
conStrBuilder.Password = builder.Configuration["DbPassword"];
var connection = conStrBuilder.ConnectionString;

var app = builder.Build();

app.MapGet("/", () => connection);

app.Run();

Lister les secrets

Supposons que le fichier secrets.json de l’application contient les deux secrets suivants :

{
  "Movies:ConnectionString": "Server=(localdb)\\mssqllocaldb;Database=Movie-1;Trusted_Connection=True;MultipleActiveResultSets=true",
  "Movies:ServiceApiKey": "12345"
}

Exécutez la commande suivante à partir du répertoire dans lequel se trouve le fichier projet :

dotnet user-secrets list

Vous obtenez la sortie suivante :

Movies:ConnectionString = Server=(localdb)\mssqllocaldb;Database=Movie-1;Trusted_Connection=True;MultipleActiveResultSets=true
Movies:ServiceApiKey = 12345

Dans l’exemple, un signe deux-points (:) dans les noms de clés désigne la hiérarchie d’objets dans le fichier secrets.json .

Supprimer un seul secret

Supposons que le fichier secrets.json de l’application contient les deux secrets suivants :

{
  "Movies:ConnectionString": "Server=(localdb)\\mssqllocaldb;Database=Movie-1;Trusted_Connection=True;MultipleActiveResultSets=true",
  "Movies:ServiceApiKey": "12345"
}

Exécutez la commande suivante à partir du répertoire dans lequel se trouve le fichier projet :

dotnet user-secrets remove "Movies:ConnectionString"

Le fichier secrets.json application est modifié pour supprimer la paire clé-valeur associée à la Movies:ConnectionString clé :

{
  "Movies": {
    "ServiceApiKey": "12345"
  }
}

La dotnet user-secrets list commande affiche le message suivant :

Movies:ServiceApiKey = 12345

Supprimer tous les secrets

Supposons que le fichier secrets.json de l’application contient les deux secrets suivants :

{
  "Movies:ConnectionString": "Server=(localdb)\\mssqllocaldb;Database=Movie-1;Trusted_Connection=True;MultipleActiveResultSets=true",
  "Movies:ServiceApiKey": "12345"
}

Exécutez la commande suivante à partir du répertoire dans lequel se trouve le fichier projet :

dotnet user-secrets clear

Tous les secrets utilisateur de l’application sont supprimés du fichier secrets.json :

{}

L’exécution de la dotnet user-secrets list commande affiche le message suivant :

No secrets configured for this application.

Gérer les secrets des utilisateurs avec Visual Studio

Pour gérer les secrets utilisateur dans Visual Studio, cliquez avec le bouton droit sur le projet dans Explorateur de solutions, puis sélectionnez Manage User Secrets :

Migrer les secrets utilisateur de ASP.NET Framework vers ASP.NET Core

Vous pouvez migrer vos secrets utilisateur stockés de ASP.NET Framework vers ASP.NET Core. Pour plus d'informations, consultez GitHub dotnet/aspnetcore.docs issue #27611 - Documentation sur les secrets d'utilisateur ne mentionne pas l'incompatibilité avec AssemblyInfo.cs.

Utiliser des secrets utilisateur dans des applications non web

Les projets qui ciblent Microsoft.NET.Sdk.Web incluent automatiquement la prise en charge des secrets utilisateur. Pour les projets qui ciblent Microsoft.NET.Sdk, tels que les applications console, installez explicitement les packages NuGet de l’extension de configuration et des secrets utilisateur.

PowerShell

Install-Package Microsoft.Extensions.Configuration
Install-Package Microsoft.Extensions.Configuration.UserSecrets

.NET CLI

dotnet add package Microsoft.Extensions.Configuration
dotnet add package Microsoft.Extensions.Configuration.UserSecrets

Après avoir installé les packages, initialisez le projet et définissez les secrets de la même façon que pour une application web. L’exemple suivant montre une application de console qui récupère la valeur d’un secret défini avec la clé AppSecret :

using Microsoft.Extensions.Configuration;

namespace ConsoleApp;

class Program
{
    static void Main(string[] args)
    {
        IConfigurationRoot config = new ConfigurationBuilder()
            .AddUserSecrets<Program>()
            .Build();

        Console.WriteLine(config["AppSecret"]);
    }
}

Contenu connexe

• GitHub dotnet/aspnetcore.docs issue #30378 (Débogage sous Internet Information Services (IIS))
• GitHub problème dotnet/aspnetcore.docs #16328 (en cours d’exécution dans IIS)
• Configuration dans ASP.NET Core
• Fournisseur de configuration Azure Key Vault