VaultSharp.Extensions.Configuration
1.0.5
dotnet add package VaultSharp.Extensions.Configuration --version 1.0.5
NuGet\Install-Package VaultSharp.Extensions.Configuration -Version 1.0.5
<PackageReference Include="VaultSharp.Extensions.Configuration" Version="1.0.5" />
paket add VaultSharp.Extensions.Configuration --version 1.0.5
#r "nuget: VaultSharp.Extensions.Configuration, 1.0.5"
// Install VaultSharp.Extensions.Configuration as a Cake Addin #addin nuget:?package=VaultSharp.Extensions.Configuration&version=1.0.5 // Install VaultSharp.Extensions.Configuration as a Cake Tool #tool nuget:?package=VaultSharp.Extensions.Configuration&version=1.0.5
VaultSharp.Extensions.Configuration
VaultSharp.Extensions.Configuration is an extension to VaultSharp that allows reading configuration options from Vault.
VaultSharp.Extensions.Configuration is a .NET Standard 2.0, 2.1, .NET 6.0, .NET 7.0, and .NET 8.0 based cross-platform C# Library.
Get Started
VaultSharp.Extensions.Configuration can be installed using the Nuget package manager or the dotnet CLI.
dotnet add package VaultSharp.Extensions.Configuration
It can be injected as a IConfigurationProvider to load configuration from HashiCorp Vault:
public static IHostBuilder CreateHostBuilder(string[] args) =>
Host.CreateDefaultBuilder(args)
.ConfigureAppConfiguration((hostingContext, config) =>
{
config.AddJsonFile("appsettings.json")
.AddVaultConfiguration(() => new VaultOptions("http://localhost:8200", "root"), "sampleapp", "secret");
})
.ConfigureWebHostDefaults(webBuilder =>
{
webBuilder.UseStartup<Startup>();
});
The AddVaultConfiguration
method accepts several parameters:
Function to provide VaultOptions with Vault connection configuration (optional).
Application alias in Vault data. It's used a part of the path to read secrets.
Mount point of KV secrets. The default value is
secret
(optional).
Monitoring for changes
You can enable monitoring of changes in Vault data and automatic reload by setting VaultOptions.ReloadOnChange
to true
.
The default check interval is 5 minutes, but can be configured.
Data is checked using version information from key metadata.
config.AddVaultConfiguration(
() => new VaultOptions(
"http://localhost:8200",
"root",
reloadOnChange: true,
reloadCheckIntervalSeconds: 60),
"sampleapp",
"secret");
Also you would need to register hosted services VaultChangeWatcher
in your Startup.cs
that will check Vault data for updates:
public void ConfigureServices(IServiceCollection services)
{
services.AddControllers();
services.AddHostedService<VaultChangeWatcher>();
}
Later in your services you can track changes in app configuration using IOptionsSnapshot
or IOptionsMonitor
.
Keep in mind that your service should be registered as scoped or transient to receive updates.
Also IOptionsSnapshot
can return empty value in some cases (it's .net core bug)
Configuration using additional characters for a configuration path
This will be helpful when you want to flatten the structure of the secrets.
For example the following two secret objects will evaluate to the same configuration if for the second object the additionalCharactersForConfigurationPath
option is used with new []{'.'}
value:
{
"secrets":
{
"DB":
{
"ConnectionString": "secret value"
}
}
}
{
"secrets":
{
"DB.ConnectionString": "secret value"
}
}
config.AddVaultConfiguration(
() => new VaultOptions(
"htpp://localhost:8200",
"root",
additionalCharactersForConfigurationPath: new []{'.'}),),
"sampleapp",
"secret");
new VaultOptions("http://localhost:8200", "root", null, null, false, 300, false, new []{'.'}),
Configuration using environment variables
Alternatively, you can configure Vault connection using next environment variables:
VAULT_ADDR
: Address of the Vault instance. Default value is"http://locahost:8200
.VAULT_TOKEN
: Vault token. Used for token-based authentication. Default value isroot
.VAULT_ROLEID
: Vault AppRole ID. Used for AppRole-based authentication.VAULT_SECRET
: Vault AppRole secret. Used for AppRole-based authentication.VAULT_INSECURE
: Allow insecure SSL connections to Vault. Default value isfalse
.
Configuration using code
You can configure Vault connection using any supported auth method (look at https://github.com/rajanadar/VaultSharp#auth-methods):
config.AddVaultConfiguration(
() => new VaultOptions(
"htpp://localhost:8200",
new KerberosAuthMethodInfo(),
reloadOnChange: true,
reloadCheckIntervalSeconds: 60),
"sampleapp",
"secret");
You can enable insecure TLS connections to Vault:
builder.AddVaultConfiguration(
() => new VaultOptions("https://localhost:8200", "root", insecureConnection: true),
"test",
"secret",
this._logger);
Or manually validate TLS certificate:
builder.AddVaultConfiguration(
() => new VaultOptions("https://localhost:8200", "root", additionalCharactersForConfigurationPath: new[] { '.' }, insecureConnection: false, serverCertificateCustomValidationCallback: (message, cert, chain, errors) =>
{
return true; //add your validation logic here
}),
"test",
"secret",
this._logger);
Preparing secrets in Vault
You need to store your secrets with special naming rules.
First of all, all secrets should use KV2 storage and have prefix {app_alias}
or {app_alias}/{env}
.
For example, if your app has alias sampleapp
and environment producton
and you want to have configuration option ConnectionString
your secret path would be or sampleapp
or sampleapp/producton
.
All parameters are grouped and arranged in folders and can be managed within the group. All secret data should use JSON format with secret data inside:
{
"ConnectionString": "secret value",
"Option1": "secret value 2",
}
Nested secrets
There are two ways to create nested parameters.
- Description of nesting directly in Json format (preferred approach):
{
"DB":
{
"ConnectionString": "secret value"
}
}
- Creating a parameter on the desired path "sampleapp/producton/DB":
{
"ConnectionString": "secret value"
}
Limitations
- Currently, only token and AppRole based authentication is supported from configuration. Other types of authentication can be used by code.
- TTL of the secrets is not controlled.
Contributing
Before starting work on a pull request, I suggest commenting on, or raising, an issue on the issue tracker so that we can help and coordinate efforts.
To run tests locally you need to have Docker running and have Vault's default port 8200 free.
Product | Versions Compatible and additional computed target framework versions. |
---|---|
.NET | net5.0 was computed. net5.0-windows was computed. net6.0 is compatible. net6.0-android was computed. net6.0-ios was computed. net6.0-maccatalyst was computed. net6.0-macos was computed. net6.0-tvos was computed. net6.0-windows was computed. net7.0 is compatible. net7.0-android was computed. net7.0-ios was computed. net7.0-maccatalyst was computed. net7.0-macos was computed. net7.0-tvos was computed. net7.0-windows was computed. net8.0 is compatible. net8.0-android was computed. net8.0-browser was computed. net8.0-ios was computed. net8.0-maccatalyst was computed. net8.0-macos was computed. net8.0-tvos was computed. net8.0-windows was computed. |
.NET Core | netcoreapp2.0 was computed. netcoreapp2.1 was computed. netcoreapp2.2 was computed. netcoreapp3.0 was computed. netcoreapp3.1 was computed. |
.NET Standard | netstandard2.0 is compatible. netstandard2.1 is compatible. |
.NET Framework | net461 was computed. net462 was computed. net463 was computed. net47 was computed. net471 was computed. net472 was computed. net48 was computed. net481 was computed. |
MonoAndroid | monoandroid was computed. |
MonoMac | monomac was computed. |
MonoTouch | monotouch was computed. |
Tizen | tizen40 was computed. tizen60 was computed. |
Xamarin.iOS | xamarinios was computed. |
Xamarin.Mac | xamarinmac was computed. |
Xamarin.TVOS | xamarintvos was computed. |
Xamarin.WatchOS | xamarinwatchos was computed. |
-
.NETStandard 2.0
- Microsoft.Extensions.Configuration (>= 6.0.1)
- Microsoft.Extensions.Hosting.Abstractions (>= 6.0.0)
- Microsoft.Extensions.Logging.Abstractions (>= 6.0.3)
- Microsoft.VisualStudio.Threading (>= 17.9.28)
- System.Text.Json (>= 7.0.3)
- VaultSharp (>= 1.13.0.1)
-
.NETStandard 2.1
- Microsoft.Extensions.Configuration (>= 7.0.0)
- Microsoft.Extensions.Hosting.Abstractions (>= 7.0.0)
- Microsoft.Extensions.Logging.Abstractions (>= 7.0.1)
- Microsoft.VisualStudio.Threading (>= 17.9.28)
- System.Text.Json (>= 7.0.3)
- VaultSharp (>= 1.13.0.1)
-
net6.0
- Microsoft.Extensions.Configuration (>= 6.0.1)
- Microsoft.Extensions.Hosting.Abstractions (>= 6.0.0)
- Microsoft.Extensions.Logging.Abstractions (>= 6.0.3)
- Microsoft.VisualStudio.Threading (>= 17.9.28)
- System.Text.Json (>= 7.0.3)
- VaultSharp (>= 1.13.0.1)
-
net7.0
- Microsoft.Extensions.Configuration (>= 7.0.0)
- Microsoft.Extensions.Hosting.Abstractions (>= 7.0.0)
- Microsoft.Extensions.Logging.Abstractions (>= 7.0.1)
- Microsoft.VisualStudio.Threading (>= 17.9.28)
- System.Text.Json (>= 7.0.4)
- VaultSharp (>= 1.13.0.1)
-
net8.0
- Microsoft.Extensions.Configuration (>= 8.0.0)
- Microsoft.Extensions.Hosting.Abstractions (>= 8.0.0)
- Microsoft.Extensions.Logging.Abstractions (>= 8.0.1)
- Microsoft.VisualStudio.Threading (>= 17.9.28)
- System.Text.Json (>= 8.0.4)
- VaultSharp (>= 1.13.0.1)
NuGet packages
This package is not used by any NuGet packages.
GitHub repositories
This package is not used by any popular GitHub repositories.
Version | Downloads | Last updated |
---|---|---|
1.0.5 | 34,113 | 7/10/2024 |
1.0.4 | 228 | 7/9/2024 |
1.0.3 | 21,998 | 4/2/2024 |
1.0.2 | 6,013 | 2/17/2024 |
1.0.1 | 646 | 2/6/2024 |
1.0.0 | 1,740 | 1/30/2024 |
0.6.4 | 53,086 | 9/5/2023 |
0.6.3 | 1,129 | 8/31/2023 |
0.6.2 | 84,638 | 5/5/2023 |
0.5.3 | 20,106 | 2/23/2023 |
0.5.2 | 16,066 | 9/16/2022 |
0.5.1 | 4,404 | 7/26/2022 |
0.4.3 | 17,415 | 5/25/2022 |
0.4.2 | 18,595 | 12/11/2021 |
0.4.1 | 3,425 | 11/18/2021 |
0.4.0 | 4,677 | 10/15/2021 |
0.3.3 | 10,275 | 3/30/2021 |
0.3.2 | 858 | 3/9/2021 |
0.3.1 | 876 | 1/26/2021 |
0.3.0 | 806 | 1/24/2021 |
0.2.2 | 986 | 10/30/2020 |
0.1.5 | 906 | 9/3/2020 |
0.1.4 | 857 | 9/3/2020 |
0.1.3 | 904 | 9/3/2020 |
0.1.2 | 983 | 7/28/2020 |