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

Di Rick Anderson e Kirk Larkin

Visualizzare o scaricare il codice di esempio (procedura per il download)

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 segreti di test e produzione di Azure possono essere archiviati e protetti con il provider di configurazione di Azure Key Vault.

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, vedere questo problema di GitHub.

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 utente. Un database predefinito stringa di connessione è incluso nel file del appsettings.json progetto con la chiave DefaultConnection. Il stringa di connessione predefinito è per LocalDB, che viene eseguito in modalità utente e non richiede una password. Durante la distribuzione dell'app, il DefaultConnection valore della chiave può essere sottoposto a override con il valore di una variabile di ambiente. La variabile di ambiente può archiviare il stringa di connessione completo con credenziali riservate.

Avviso

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

Il separatore : non funziona con le chiavi gerarchiche delle variabili di ambiente in tutte le piattaforme. Ad esempio, il : separatore non è supportato da Bash. Il doppio carattere di sottolineatura, __, è:

• Supportato da tutte le piattaforme.
• Sostituito automaticamente da due punti, :.

Secret Manager

Lo strumento Secret Manager 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. I segreti dell'app sono associati a un progetto specifico o condivisi tra diversi progetti. I segreti dell'app non vengono controllati nel controllo del codice sorgente.

Avviso

Lo strumento 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.

Funzionamento dello strumento Secret Manager

Lo strumento 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

Nei percorsi di file precedenti sostituire <user_secrets_id> con il UserSecretsId valore specificato nel file di progetto.

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

Abilitare l'archiviazione privata

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

Usare la CLI

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

dotnet user-secrets init

Il comando precedente 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.

<PropertyGroup>
  <TargetFramework>netcoreapp3.1</TargetFramework>
  <UserSecretsId>79a3edd0-2092-40a2-a04d-dcb46d5ca9ed</UserSecretsId>
</PropertyGroup>

Usare Visual Studio

In Visual Studio fare clic con il pulsante destro del mouse sul progetto in Esplora soluzioni e scegliere 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 sull'assembly è disabilitata, aggiungere manualmente in UserSecretsIdAttribute AssemblyInfo.cs. Ad esempio:

[assembly: UserSecretsId("your_user_secrets_id")]

Quando si aggiunge manualmente l'attributo UserSecretsId a 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 UserSecretsId progetto. Ad esempio, eseguire il comando seguente dalla directory in cui è presente il file di progetto:

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

Nell'esempio precedente i due punti indicano che Movies è un valore letterale oggetto con una ServiceApiKey proprietà .

Lo strumento Secret Manager può essere usato anche da altre directory. Usare l'opzione --project per specificare il percorso del file system in corrispondenza del quale esiste il file di progetto. Ad esempio:

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

Struttura JSON flat in Visual Studio

Il movimento Gestisci segreti utente di Visual Studio apre un secrets.json file nell'editor di testo. Sostituire il contenuto di secrets.json con le coppie chiave-valore da archiviare. Ad 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 dotnet user-secrets remove o dotnet user-secrets set. Ad esempio, l'esecuzione dotnet user-secrets remove "Movies:ConnectionString" comprime il valore letterale dell'oggetto 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 input.json contenuto del file viene inviato tramite pipe al set comando .

Windows

Aprire una shell dei comandi ed eseguire il comando seguente:

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

Linux/macOS

Aprire una shell dei comandi ed eseguire il comando seguente:

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 .NET.

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

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

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

app.Run();

WebApplication.CreateBuilder inizializza una nuova istanza della classe WebApplicationBuilder con valori predefiniti preconfigurati. L'inizializzato WebApplicationBuilder (builder) fornisce la configurazione predefinita e chiama AddUserSecrets quando EnvironmentName è Development:

Leggere il segreto tramite l'API di configurazione

Si considerino gli esempi seguenti di lettura della 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 Pagine:

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.

Eseguire il mapping dei segreti a poco

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

Si supponga che il file dell'app secrets.json 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 a poco, usare la funzionalità di associazione dell'oggetto grafico dell'API di configurazione .NET. Il codice seguente viene associato a un poco personalizzato MovieSettings e accede al valore della ServiceApiKey proprietà:

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

I Movies:ConnectionString segreti e Movies:ServiceApiKey vengono mappati alle rispettive proprietà in MovieSettings:

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

    public string ServiceApiKey { get; set; }
}

Sostituzione di stringhe con segreti

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

Ad esempio, un database stringa di connessione archiviato in appsettings.json non deve includere una password. Archiviare invece la password come segreto e includere la password nel stringa di connessione in fase di esecuzione. Ad esempio:

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

Sostituire il <secret value> segnaposto nell'esempio precedente con il valore della password. Impostare il valore del segreto sulla proprietà di Password un SqlConnectionStringBuilder oggetto per includerlo come valore della password nel 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 il file dell'app secrets.json 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 precedente, i due punti nei nomi delle chiavi indicano la gerarchia di oggetti all'interno di secrets.json.

Rimuovere un singolo segreto

Si supponga che il file dell'app secrets.json 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"

Il file dell'app secrets.json è stato modificato per rimuovere la coppia chiave-valore associata alla Movies:ConnectionString chiave:

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

dotnet user-secrets list visualizza il messaggio seguente:

Movies:ServiceApiKey = 12345

Rimuovere tutti i segreti

Si supponga che il file dell'app secrets.json 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 sono stati eliminati dal secrets.json file:

{}

In esecuzione dotnet user-secrets list viene visualizzato 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:

Migrazione dei segreti utente da ASP.NET Framework a ASP.NET Core

Vedere il problema in GitHub.

Segreti utente in applicazioni non Web

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

Tramite PowerShell:

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

Uso dell'interfaccia della riga di comando di .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 segreto impostato con la chiave "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"]);
    }
}

Risorse aggiuntive

• Vedere questo problema e questo problema per informazioni sull'accesso ai segreti utente da IIS.
• Configurazione in ASP.NET Core
• Provider di configurazione di Azure Key Vault in ASP.NET Core