Archiviazione sicura dei segreti dell'app nello sviluppo in ASP.NET Core

Di Rick Anderson e Kirk Larkin

Questo articolo illustra come gestire i dati sensibili per un'app ASP.NET Core in un computer di sviluppo. Non archiviare mai password o altri dati sensibili nel codice sorgente o nei file di configurazione. I segreti di produzione non devono essere usati per lo sviluppo o il test. I segreti non devono essere distribuiti con l'app. È necessario accedere ai segreti di produzione tramite un mezzo controllato, ad esempio Azure Key Vault. I credenziali di test e produzione di Azure possono essere archiviati e protetti con il provider di Azure Key Vault per la configurazione.

Visualizzare o scaricare il codice di esempio (come scaricare)

Per altre informazioni sull'autenticazione per le app di test e produzione distribuite, vedere Proteggere i flussi di autenticazione.

Per usare i segreti utente in un'app console .NET, vedi issue #3939 di GitHub dotnet/entityframework.docs.

Lavorare con le variabili di ambiente

Le variabili di ambiente vengono usate per evitare l'archiviazione dei segreti dell'app nel codice o nei file di configurazione locali. Le variabili di ambiente sostituiscono i valori di configurazione per tutte le origini di configurazione specificate in precedenza.

Si consideri un'app Web ASP.NET Core in cui è abilitata la sicurezza dei singoli account . Una stringa di connessione al database predefinita è inclusa nel file appsettings.json del progetto con la chiave DefaultConnection. La stringa di connessione predefinita è per LocalDB, che viene eseguito in modalità utente e non richiede una password. Durante la distribuzione dell'app, è possibile sovrascrivere il valore della chiave DefaultConnection con quello di una variabile di ambiente. La variabile di ambiente potrebbe archiviare il stringa di connessione completo con credenziali riservate.

Warning

Le variabili di ambiente vengono in genere archiviate come testo normale e non crittografato. Se il computer o il processo è compromesso, le variabili di ambiente sono accessibili alle parti non attendibili. Potrebbero essere necessarie misure aggiuntive per impedire la divulgazione dei segreti utente.

Il separatore di due punti (:) non funziona con le chiavi gerarchiche delle variabili di ambiente su tutte le piattaforme. Ad esempio, Bash non supporta i due punti (:) come separatore. Tutte le piattaforme supportano la sintassi del doppio carattere di sottolineatura (__) e la sostituiscono automaticamente con due punti (:).

Usare lo strumento Secret Manager

Secret Manager è uno strumento che archivia i dati sensibili durante lo sviluppo di applicazioni. In questo contesto, una parte di dati sensibili è un segreto dell'app.

• I segreti dell'app vengono archiviati in una posizione separata dall'albero del progetto.
• Sono associati a un progetto specifico o condivisi tra diversi progetti.
• Non vengono sottoposte al controllo del codice sorgente.

Warning

Secret Manager non crittografa i segreti archiviati e non deve essere considerato come archivio attendibile. È solo a scopo di sviluppo. Le chiavi e i valori vengono archiviati in un file di configurazione JSON nella directory del profilo utente.

Secret Manager nasconde i dettagli di implementazione, ad esempio dove e come vengono archiviati i valori. È possibile usare lo strumento senza conoscere questi dettagli di implementazione. I valori vengono archiviati in un file JSON nella cartella del profilo utente del computer locale:

Windows

Percorso del file system:

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

Linux/macOS

Percorso del file system:

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

Nel percorso del file system, sostituisci la parte <user_secrets_id> con il valore UserSecretsId specificato nel file di progetto.

Non scrivere codice che dipende dalla posizione o dal formato dei dati salvati con Secret Manager. Questi dettagli di implementazione potrebbero cambiare. Ad esempio, i valori dei segreti non vengono crittografati.

Abilitare l'archiviazione privata

Secret Manager opera sulle impostazioni di configurazione specifiche del progetto archiviate nel profilo utente.

Usare la CLI

Secret Manager include un comando init. Per usare i segreti utente, eseguire il comando seguente nella directory del progetto:

dotnet user-secrets init

Questo comando aggiunge un UserSecretsId elemento all'interno di un PropertyGroup file di progetto. Per impostazione predefinita, il testo interno di UserSecretsId è un GUID. Il testo interno è arbitrario, ma è univoco per il progetto. Nell'esempio seguente viene illustrato un valore GUID di 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>

Usare Visual Studio

In Visual Studio, fare clic con il pulsante destro del mouse sul progetto in Esplora Soluzioni e selezionare Gestisci segreti utente dal menu di scelta rapida. Questo movimento aggiunge un UserSecretsId elemento, popolato con un GUID, al file di progetto.

Se 'GenerateAssemblyInfo' è 'false'

Se la generazione degli attributi delle informazioni dell'assembly (GenerateAssemblyInfo) è disabilitata (impostata su false), aggiungere manualmente UserSecretsIdAttribute nel file AssemblyInfo.cs. Per esempio:

[assembly: UserSecretsId("your_user_secrets_id")]

Quando si aggiunge manualmente l'attributo UserSecretsId al file AssemblyInfo.cs , il UserSecretsId valore deve corrispondere al valore nel file di progetto.

Impostare un segreto

Definire un segreto dell'app costituito da una chiave e dal relativo valore. Il segreto è associato al valore del progetto UserSecretsId. Ad esempio, eseguire il comando seguente dalla directory in cui è presente il file di progetto:

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

In questo esempio, i due punti indicano che Movies è un oggetto letterale con una proprietà ServiceApiKey.

È anche possibile usare Secret Manager da altre directory. Includere l'opzione --project per specificare il percorso del file system in corrispondenza del quale esiste il file di progetto. Per esempio:

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

Appiattimento della struttura JSON in Visual Studio

Il movimento Visual Studio Gestisci segreti utente apre un file secrets.json nell'editor di testo. Sostituire il contenuto del file secrets.json con le coppie chiave-valore da archiviare. Per esempio:

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

La struttura JSON viene appiattita dopo le modifiche tramite il dotnet user-secrets remove comando o dotnet user-secrets set . Ad esempio, eseguendo dotnet user-secrets remove "Movies:ConnectionString" collassa l'oggetto letterale Movies. Il file modificato è simile al codice JSON seguente:

{
  "Movies:ServiceApiKey": "12345"
}

Impostare più segreti

È possibile impostare un batch di segreti inviando json al set comando. Nell'esempio seguente il contenuto del fileinput.json viene inviato tramite pipe al set comando .

Windows

Esegui questo comando:

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

Linux/macOS

Eseguire il comando seguente in un terminale:

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

Accedere a un segreto

Per accedere a un segreto, completare la procedura seguente:

1. Registrare l'origine di configurazione dei segreti utente.

2. Leggere il segreto tramite l'API di configurazione.

Registrare l'origine di configurazione dei segreti utente

Il provider di configurazione dei segreti utente registra l'origine di configurazione appropriata con l'API di configurazione di .NET.

Le app web ASP.NET Core create con il comando dotnet new o con Visual Studio generano il codice seguente:

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

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

app.Run();

Il metodo WebApplication.CreateBuilder inizializza una nuova istanza della WebApplicationBuilder classe con impostazioni predefinite preconfigurate. L'elemento inizializzato WebApplicationBuilder (builder) fornisce la configurazione predefinita e chiama il metodo AddUserSecrets quando la proprietà EnvironmentName è Development.

Leggere il segreto tramite l'API di configurazione

Gli esempi seguenti illustrano come leggere la Movies:ServiceApiKey chiave:

Program.cs file

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

var app = builder.Build();

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

app.Run();

Razor Modello di pagina di 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
    }
}

Per altre informazioni, vedere Configurazione in ASP.NET Core.

Mappare i segreti su un POCO

Il mapping di un intero oggetto letterale a un POCO (una semplice classe .NET con proprietà) è utile per l'aggregazione di proprietà correlate.

Si supponga che l'applicazione secrets.json file contenga i due segreti seguenti:

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

Per eseguire il mapping dei segreti precedenti in un POCO, usare la funzionalità di associazione di grafi di oggetti dell'API di configurazione .NET. Il codice seguente si associa a un POCO personalizzato MovieSettings e accede al valore della proprietà ServiceApiKey.

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

Vengono mappati i Movies:ConnectionString e Movies:ServiceApiKey segreti alle rispettive proprietà in MovieSettings:

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

    public string ServiceApiKey { get; set; }
}

Usare la sostituzione di stringhe con segreti

L'archiviazione delle password in testo normale non è sicura. Non archiviare mai segreti in un file di configurazione, ad esempio appsettings.json, che potrebbe essere archiviato in un repository di codice sorgente.

Ad esempio, un database stringa di connessione archiviato in un file appsettings.json non deve includere una password. Invece, archiviare la password come segreto e includere la password nella stringa di connessione durante l'esecuzione. Per esempio:

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

Sostituire il <secret value> segnaposto nell'esempio con il valore della password. Impostare il valore del segreto sulla proprietà dell'oggetto SqlConnectionStringBuilderPassword per includerlo come valore della password nella stringa di connessione.

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

Elencare i segreti

Si supponga che l'applicazione secrets.json file contenga i due segreti seguenti:

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

Eseguire il comando seguente dalla directory in cui è presente il file di progetto:

dotnet user-secrets list

Viene visualizzato l'output seguente:

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

Nell'esempio, i due punti (:) nei nomi delle chiavi indicano la gerarchia di oggetti all'interno del file secrets.json .

Rimuovere un singolo segreto

Si supponga che l'applicazione secrets.json file contenga i due segreti seguenti:

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

Eseguire il comando seguente dalla directory in cui è presente il file di progetto:

dotnet user-secrets remove "Movies:ConnectionString"

L'applicazione secrets.json file viene modificato per rimuovere la coppia chiave-valore associata alla Movies:ConnectionString chiave:

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

Il dotnet user-secrets list comando visualizza il messaggio seguente:

Movies:ServiceApiKey = 12345

Rimuovere tutti i segreti

Si supponga che l'applicazione secrets.json file contenga i due segreti seguenti:

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

Eseguire il comando seguente dalla directory in cui è presente il file di progetto:

dotnet user-secrets clear

Tutti i segreti utente per l'app vengono eliminati dal file secrets.json :

{}

L'esecuzione del dotnet user-secrets list comando visualizza il messaggio seguente:

No secrets configured for this application.

Gestire i segreti utente con Visual Studio

Per gestire i segreti utente in Visual Studio, fare clic con il pulsante destro del mouse sul progetto in Esplora soluzioni e selezionare Gestisci segreti utente:

Eseguire la migrazione dei segreti utente da ASP.NET Framework a ASP.NET Core

È possibile eseguire la migrazione dei segreti utente archiviati da ASP.NET Framework a ASP.NET Core. Per altre informazioni, vedere GitHub dotnet/aspnetcore.docs issue #27611 - La documentazione relativa ai segreti utente non menziona l'incompatibilità con AssemblyInfo.cs.

Usare i segreti utente nelle applicazioni non Web

I progetti che mirano a Microsoft.NET.Sdk.Web automaticamente includono il supporto per i segreti utente. Per i progetti destinati a Microsoft.NET.Sdk, ad esempio le applicazioni console, installare esplicitamente i pacchetti NuGet dell'estensione di configurazione e dei segreti utente.

PowerShell

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

interfaccia della riga di comando .NET

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

Dopo aver installato i pacchetti, inizializzare il progetto e impostare i segreti come per un'app Web. L'esempio seguente mostra un'applicazione console che recupera il valore di un set di segreti con la AppSecret chiave :

using Microsoft.Extensions.Configuration;

namespace ConsoleApp;

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

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

Contenuti correlati

• GitHub issue dotnet/aspnetcore.docs #30378 (Debug con Internet Information Services (IIS))
• GitHub problema dotnet/aspnetcore.docs #16328 (in esecuzione in IIS)
• Configurazione in ASP.NET Core
• Azure Key Vault configuration provider (Provider di configurazione di Azure Key Vault)