Armazenar segredos de aplicativo com segurança durante o desenvolvimentoStore application secrets safely during development

Para se conectar com recursos protegidos e outros serviços, os aplicativos ASP.NET Core normalmente precisam usar cadeias de conexão, senhas ou outras credenciais que contêm informações confidenciais.To connect with protected resources and other services, ASP.NET Core applications typically need to use connection strings, passwords, or other credentials that contain sensitive information. Essas informações confidenciais são chamadas segredos.These sensitive pieces of information are called secrets. Uma prática recomendada é não incluir segredos no código-fonte e não armazená-los no controle do código-fonte.It's a best practice to not include secrets in source code and making sure not to store secrets in source control. Em vez disso, você deve usar o modelo de configuração do ASP.NET Core para ler os segredos de locais mais seguros.Instead, you should use the ASP.NET Core configuration model to read the secrets from more secure locations.

Você precisa separar os segredos para acessar os recursos de desenvolvimento e de preparo daqueles que são usados para acessar recursos de produção, pois diferentes pessoas precisarão acessar esses diferentes conjuntos de segredos.You must separate the secrets for accessing development and staging resources from the ones used for accessing production resources, because different individuals will need access to those different sets of secrets. Para armazenar segredos usados durante o desenvolvimento, as abordagens comuns são armazenar segredos em variáveis de ambiente ou por meio do uso da ferramenta Secret Manager do ASP.NET Core.To store secrets used during development, common approaches are to either store secrets in environment variables or by using the ASP.NET Core Secret Manager tool. Para obter mais armazenamento seguro em ambientes de produção, os microsserviços podem armazenar segredos em um Azure Key Vault.For more secure storage in production environments, microservices can store secrets in an Azure Key Vault.

Armazenar segredos em variáveis de ambienteStore secrets in environment variables

Uma maneira de manter segredos fora do código-fonte é para os desenvolvedores definirem segredos baseados em cadeia de caracteres como variáveis de ambiente em seus computadores de desenvolvimento.One way to keep secrets out of source code is for developers to set string-based secrets as environment variables on their development machines. Ao usar variáveis de ambiente para armazenar segredos com nomes hierárquicos, como aqueles aninhados em seções de configuração, você precisa nomear as variáveis para incluir a hierarquia completa de suas seções, delimitada por dois-pontos (:).When you use environment variables to store secrets with hierarchical names, such as the ones nested in configuration sections, you must name the variables to include the complete hierarchy of its sections, delimited with colons (:).

Por exemplo, a definição de uma variável de ambiente Logging:LogLevel:Default para o valor Debug seria equivalente a um valor de configuração do arquivo JSON a seguir:For example, setting an environment variable Logging:LogLevel:Default to Debug value would be equivalent to a configuration value from the following JSON file:

{
    "Logging": {
        "LogLevel": {
            "Default": "Debug"
        }
    }
}

Para acessar esses valores de variáveis de ambiente, o aplicativo precisa apenas chamar AddEnvironmentVariables em seu ConfigurationBuilder ao construir um objeto IConfigurationRoot.To access these values from environment variables, the application just needs to call AddEnvironmentVariables on its ConfigurationBuilder when constructing an IConfigurationRoot object.

Observe que as variáveis de ambiente geralmente são armazenadas como texto sem formatação. Portanto, se o computador ou o processo com variáveis de ambiente estiver comprometido, os valores das variáveis de ambiente estarão visíveis.Note that environment variables are commonly stored as plain text, so if the machine or process with the environment variables is compromised, the environment variable values will be visible.

Armazenar segredos com o Secret Manager do ASP.NET CoreStore secrets with the ASP.NET Core Secret Manager

A ferramenta Secret Manager do ASP.NET Core oferece outro método de manter segredos fora do código-fonte.The ASP.NET Core Secret Manager tool provides another method of keeping secrets out of source code. Para usar a ferramenta Secret Manager, instale o pacote Microsoft.Extensions.Configuration.SecretManager no arquivo de projeto.To use the Secret Manager tool, install the package Microsoft.Extensions.Configuration.SecretManager in your project file. Quando essa dependência estiver presente e tiver sido restaurada, o comando dotnet user-secrets poderá ser usado para definir o valor dos segredos na linha de comando.Once that dependency is present and has been restored, the dotnet user-secrets command can be used to set the value of secrets from the command line. Esses segredos serão armazenados em um arquivo JSON no diretório do perfil do usuário (os detalhes variam de acordo com o sistema operacional), fora do código-fonte.These secrets will be stored in a JSON file in the user’s profile directory (details vary by OS), away from source code.

Os segredos definidos pela ferramenta Secret Manager são organizados pela propriedade UserSecretsId do projeto que está usando os segredos.Secrets set by the Secret Manager tool are organized by the UserSecretsId property of the project that's using the secrets. Portanto, você precisa definir a propriedade UserSecretsId em seu arquivo de projeto, como mostra o snippet a seguir.Therefore, you must be sure to set the UserSecretsId property in your project file, as shown in the snippet below. O valor padrão é um GUID atribuído pelo Visual Studio, mas a cadeia de caracteres real não é importante, desde que seja exclusiva no seu computador.The default value is a GUID assigned by Visual Studio, but the actual string is not important as long as it's unique in your computer.

<PropertyGroup>
    <UserSecretsId>UniqueIdentifyingString</UserSecretsId>
</PropertyGroup>

O uso de segredos armazenados com o Secret Manager em um aplicativo é realizado chamando AddUserSecrets<T> na instância ConfigurationBuilder para incluir os segredos do aplicativo em sua configuração.Using secrets stored with Secret Manager in an application is accomplished by calling AddUserSecrets<T> on the ConfigurationBuilder instance to include secrets for the application in its configuration. O parâmetro genérico T deve ser um tipo do assembly ao qual o UserSecretId foi aplicado.The generic parameter T should be a type from the assembly that the UserSecretId was applied to. Geralmente, basta usar o AddUserSecrets<Startup>.Usually using AddUserSecrets<Startup> is fine.

O AddUserSecrets<Startup>() está incluído nas opções padrão do ambiente de desenvolvimento quando o método CreateDefaultBuilder é usado em Program.cs.The AddUserSecrets<Startup>() is included in the default options for the Development environment when using the CreateDefaultBuilder method in Program.cs.