VaultSharp

The most comprehensive cross-platform .NET Library for HashiCorp's Vault - A Secret Management System.

VaultSharp NuGet:

VaultSharp Latest Documentation: Inline Below and also at: https://rajanadar.github.io/VaultSharp/

VaultSharp Questions/Clarifications: Ask on Stack Overflow with the tag vaultsharp

VaultSharp Gitter Lobby: Gitter Lobby

Report Issues/Feedback: Create a VaultSharp GitHub issue

Contributing Guidlines: VaultSharp Contribution Guidelines

What is VaultSharp?

• VaultSharp is a .NET Standard 1.3, .NET Standard 2.0, .NET Standard 2.1, .NET Framework 4.5, .NET Framework 4.6.x, .NET Framework 4.7.x, .NET Framework 4.8, .NET 5.0, .NET 6.0, .NET 7.0 and .NET 8.0 based cross-platform C# Library that can be used in any .NET application to interact with Hashicorp's Vault.
• The Vault system is a secret management system built as an Http Service by Hashicorp.

VaultSharp has been re-designed ground up, to give a structured user experience across the various auth methods, secrets engines & system apis. Also, the Intellisense on IVaultClient class should help. I have tried to add a lot of documentation.

Give me a quick snippet for use!

• Add a Nuget reference to VaultSharp as follows Install-Package VaultSharp -Version <latest_version>
• Instantiate a IVaultClient as follows:

// Initialize one of the several auth methods.
IAuthMethodInfo authMethod = new TokenAuthMethodInfo("MY_VAULT_TOKEN");

// Initialize settings. You can also set proxies, custom delegates etc. here.
var vaultClientSettings = new VaultClientSettings("https://MY_VAULT_SERVER:8200", authMethod);

IVaultClient vaultClient = new VaultClient(vaultClientSettings);

// Use client to read a key-value secret.

// Very important to provide mountpath and secret name as two separate parameters. Don't provide a single combined string.
// Please use named parameters for 100% clarity of code. (the method also takes version and wrapTimeToLive as params)

Secret<SecretData> kv2Secret = await vaultClient.V1.Secrets.KeyValue.V2
                               .ReadSecretAsync(path: "secretPath", mountPoint: "mountPointIfNotDefault");

// Generate a dynamic Consul credential
Secret<ConsulCredentials> consulCreds = await vaultClient.V1.Secrets.Consul.GetCredentialsAsync(consulRole, consulMount);
string consulToken = consulCreds.Data.Token;

Gist of the features

• VaultSharp supports
  • All the Auth Methods for Logging into Vault. (AppRole, AWS, Azure, GitHub, Google Cloud, JWT/OIDC, Kubernetes, LDAP, Okta, RADIUS, TLS, Tokens & UserPass)
  • All the secret engines to get dynamic credentials. (AD, AWS EC2 and IAM, Consul, Cubbyhole, Databases, Google Cloud, Key-Value, Nomad, PKI, RabbitMQ, SSH and TOTP)
  • Several system APIs including enterprise vault apis
• You can also bring your own "Auth Method" by providing a custom delegate to fetch a token from anywhere.
• VaultSharp has first class support for Consul engine.
• KeyValue engine supports both v1 and v2 apis.
• Abundant intellisense.
• Provides hooks into http-clients to set custom proxy settings etc.

VaultSharp - Supported .NET Platforms and Implementations

VaultSharp is built on .NET Standard 1.3 & .NET Standard 2.0 & .NET Standard 2.1 & .NET Frameworks 4.5, 4.6.x, 4.7.x, 4.8 & .NET 5, .NET 6, .NET 7, .NET 8. This makes it highly compatible and cross-platform.

The following implementations are supported due to that.

• .NET Core 1.x, 2.x, 3.x
• .NET Framework 4.5, 4.6, 4.6.1, 4.6.2, 4.7, 4.7.1, 4.7.2 and 4.8
• .NET 5.0
• .NET 6.0
• .NET 7.0
• .NET 8.0
• Mono 4.x and above
• Xamarin.iOS 10.x and above
• Xamarin Mac 3.x and above
• Xamarin.Android 7.x and above
• UWP 10.x and above

Source: https://github.com/dotnet/standard/blob/master/docs/versions.md

VaultSharp will follow the .NET EOL dates mentioned here:

• https://learn.microsoft.com/en-us/lifecycle/products/microsoft-net-framework
• https://dotnet.microsoft.com/en-us/platform/support/policy/dotnet-core
• https://learn.microsoft.com/en-us/dotnet/standard/frameworks#supported-target-frameworks

VaultSharp and Consul Support

• VaultSharp supports dynamic Consul credential generation.
• Please look at the API usage in the 'Consul' section of 'Secrets Engines' below, to see all the Consul related methods in action.

VaultSharp and Automatic Token Refresh

• VaultSharp DOES NOT support automatic token refresh.
• It is the responsibility of the host application to refresh the login token as per its expiry.
• The host app is free to use the vaultClient.V1.Auth.ResetVaultToken(); method to refresh the token from time to time.
• The host app is also free to re-initialize the entire VaultClient instance. This is helpful when you use AWS Signatures etc. where even if you try to just reset the vault token, it may fail because the signature time is pretty old. In those cases, feel free to re-initialize the whole vaultclient instance

VaultSharp and VaultClient Dependency Injection Lifetime

• If the vault login token expiry is way more than the deployment cadence of your application, then the recommended lifetime scope for VaultSharp's IVaultClient is Singleton. This is because, it will login only once to Vault to get the auth token and use it for the rest of all the vault calls you make.
• The only use-case when the Singleton lifetime will fail you is if your login token expiry is less than your application's deployment cadence. In that case, you have to either write your automatic token renewal logic OR use a RequestScoped lifetime for DI. Renewal logic is more performant than request scoping. This is because, you wouldn't want vaultsharp to request a login token for every web request of yours.

VaultSharp and Automatic Built-in Client Side failover

• VaultSharp DOES NOT support built-in client-side failover either by supporting multiple endpoint URI's or by supporting roundrobin DNS.
• I repeat, it DOES NOT.
• It works off a single URL that you provide. Any sort of fail-over etc. needs to be done by you.
• You are free to instantiate a new instance of VaultClient with a different URI.

VaultSharp and Immediate Login Failure Detection

• By DEFAULT, VaultSharp performs a lazy login to Vault.
• What this means is that, once you initialize VaultSharp with AuthInfo, VaultSharp will not try to immediately login into Vault.
• It'll attempt to login to Vault, only when the first real functional operation is requested. E.g. ReadSecretAsync etc.
• This has the pro that the acquired token can live as long as possible.
• The downside to this is that, any login issues will be a non-app startup discovery (assuming VaultClient is initialized at app startup) which may be not desirable at all. Folks may want to know that Vault Login failed as early as possible.
• VaultSharp now supports this feature starting version 1.6.0.3
• Imemdiately after initializing vault client, invoke the login method to force a login.

IVaultClient vaultClient = new VaultClient(vaultClientSettings);
vaultClient.V1.Auth.PerformImmediateLogin();

• Please note that this will not work for Token Authentication since you already have a vault token.

Auth Methods

• VaultSharp supports all authentication methods supported by the Vault Service
• Here is a sample to instantiate the vault client with each of the authentication backends.

AliCloud Auth Method

// setup the AliCloud based auth to get the right token.

IAuthMethodInfo authMethod = new AliCloudAuthMethodInfo(roleName, base64EncodedIdentityRequestUrl, base64EncodedIdentityRequestHeaders);
var vaultClientSettings = new VaultClientSettings("https://MY_VAULT_SERVER:8200", authMethod);

IVaultClient vaultClient = new VaultClient(vaultClientSettings);

// any operations done using the vaultClient will use the
// vault token/policies mapped to the AliCloud jwt

App Role Auth Method

// setup the AppRole based auth to get the right token.

IAuthMethodInfo authMethod = new AppRoleAuthMethodInfo(roleId, secretId);
var vaultClientSettings = new VaultClientSettings("https://MY_VAULT_SERVER:8200", authMethod);

IVaultClient vaultClient = new VaultClient(vaultClientSettings);

// any operations done using the vaultClient will use the
// vault token/policies mapped to the app role and secret id.

AWS Auth Method

AWS Auth method has 2 flavors. An EC2 way and an IAM way. Here are examples for both.

AWS Auth Method - EC2

// setup the AWS-EC2 based auth to get the right token.

IAuthMethodInfo authMethod = new EC2AWSAuthMethodInfo(pkcs7, null, null, nonce, roleName);
var vaultClientSettings = new VaultClientSettings("https://MY_VAULT_SERVER:8200", authMethod);

IVaultClient vaultClient = new VaultClient(vaultClientSettings);

// any operations done using the vaultClient will use the
// vault token/policies mapped to the aws-ec2 role

// setup the AWS-EC2 based auth to