Blip.Starter.Common.Secrets 0.0.19

Blip.Starter.Common.Secrets

First of all, please read all pages of our Secrets documentation.

Secrets are confidential information that should not be exposed in your code. This includes passwords, API keys, tokens, etc.

This library provides a way to retrieve secrets from a secret storage. Currently, we support Hashicorp Vault as our secret storage.

Follow the configuration above to be able to configure. Please also read our documentation about .NET secrets accesses.

Configuring your application

To configure your application you need to add Blip.Starter.Common.Secrets NuGet package to your project.

The NuGet package is published in our private NuGet repository: https://dev.azure.com/curupira/BLiP/_artifacts/feed/BlipNuget/NuGet/Blip.Starter.Common.Secrets/overview

To access it locally you will need to install Azure Artifacts credential provider.

To configure this library you need to provide a ISecretConfiguration. You may create yourself one programatically or use the DefaultSecretConfiguration which uses several environment variables to configure the library:

Here's specific engine configuration:

ASP.NET Core

To integrate this library with a ASP.NET Core application, go to your Startup.cs file or anywhere you configure the framework and add the following code:

// You can change the configuration if needed, but prefer changing the configuration with environment variables without hardcoding it to your code.
ISecretConfiguration configuration = DefaultSecretConfiguration();

// Creates the environment from environment variables.
var environment = Blip.Starter.Common.Env.Environment.FromEnvironmentVariables();

// Adds the secrets to the configuration builder, using the 'SecretConfigurationExtensions' extension.
// You may ommit all attributes and let the configuration be loaded from environment variables.
// You may also hardcode the engine to be used here, by providing the engine parameter, but prefer using the environment variable. 
builder.Configuration.AddSecrets(
    environment: environment,
    configuration: configuration);

Manual configuration

If you are not using ASP.NET you can configure the library manually and get the secrets dictionary manually, without integrating it with the Microsoft's ConfigurationBuilder:

// You can change the configuration if needed, but prefer changing the configuration with environment variables without hardcoding it to your code.
ISecretConfiguration configuration = DefaultSecretConfiguration();

// Creates the environment from environment variables.
var environment = Blip.Starter.Common.Env.Environment.FromEnvironmentVariables();

// Load the secrets from the secret storage.
// If disabled (default) this will return an empty dictionary.
var dictionary = await SecretStarter.Load(
    engine: SecretEngine.Vault,
    environment: environment,
    configuration: configuration);

// Access the secrets using the returned dictionary.
// Embedded json objects are also supported, but to access them you need to use ':' to separate the keys.
// Example: "secretKey:myEmbeddedSecret"

Writing custom secrets

Your application can also write custom secrets under a specific folder structure that fits your needs.

Step one

Insert the .AddVaultEngine on your DI registration so it can use an IEngine, like the example below.

//first scenario: you already initialized your environment and configuration values
            builder.Services.AddVaultEngine(
               environment: environment,
               configuration: configuration
               );

//or let the library initiate the service
             builder.Services.AddVaultEngine();

Step two

In your application code, you can receive an IEngine instance through the DI container, like the example below

        private readonly IEngine _engine;

        public WeatherForecastController(IEngine engine)
        {
            _engine = engine;
        }

Step three

Now you can invoke the methods with the following parameters

• PatchSecretsAsync: allows you to update if the data already exists or create the secrets data

var path = "testbot@msging.net/sense-config";
Dictionary<string, object> dictionaryToSave = new Dictionary<string, object>();

await _engine.PatchSecretsAsync(path, dictionaryToSave);

• CreateSecretsAsync: allows you to create the secrets data and/or replace all the stored date

var path = "testbot@msging.net/sense-config";
Dictionary<string, object> dictionaryToSave = new Dictionary<string, object>();

await _engine.CreateSecretsAsync(path, dictionaryToSave);

Reading custom secrets

All custom secrets will be stored on vault in a specific directory. If your application is named msging-server and is inside the take cluster, if you save to the path testbot@msging.net/sense-config the final stored key value will be the following:

take / msging-server / custom / testbot@msging.net / sense-configs

To read you may use the ReadSecretsAsync from the IEngine:

var path = "testbot@msging.net/sense-config";

// Using same values as the writing example, this will read the secret on the custom's secret path:
// take / msging-server / custom / testbot@msging.net / sense-configs
var secrets = await _engine.ReadSecretAsync(path);

Adding secrets to the secret storage

To add new secrets in our production secret storage you must create a new service request.

TODO: add SR link and owner team