Elvia.Configuration 8.0.0

dotnet add package Elvia.Configuration --version 8.0.0
                    
NuGet\Install-Package Elvia.Configuration -Version 8.0.0
                    
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="Elvia.Configuration" Version="8.0.0" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="Elvia.Configuration" Version="8.0.0" />
                    
Directory.Packages.props
<PackageReference Include="Elvia.Configuration" />
                    
Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add Elvia.Configuration --version 8.0.0
                    
#r "nuget: Elvia.Configuration, 8.0.0"
                    
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
#:package Elvia.Configuration@8.0.0
                    
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.
#addin nuget:?package=Elvia.Configuration&version=8.0.0
                    
Install as a Cake Addin
#tool nuget:?package=Elvia.Configuration&version=8.0.0
                    
Install as a Cake Tool

libraries-elvia-config-lib

Get secrets from HashiCorp Vault. The library targets .NET 10 or later.

Install the package:

dotnet add package Elvia.Configuration

Authentication methods are selected in this order: Vault token, Kubernetes in Atlas, AppRole (ROLE_ID), then Entra ID outside Atlas.

See CHANGELOG.md for breaking changes and release history.

Quick start

Use the configuration provider when Vault secrets should be available through IConfiguration:

using Elvia.Configuration;

var builder = WebApplication.CreateBuilder(args);
builder.Configuration.AddHashiVaultSecrets();

var environment = builder.Configuration.EnsureHasValue("shared:kv:info:environment");

Use /-separated paths with the static API for direct asynchronous lookups:

using Elvia.Configuration.HashiVault;

var environment = await HashiVault.EnsureHasValueAsync("shared/kv/info/environment");

IConfiguration lookups are synchronous. The provider loads secrets lazily, so the first lookup and refreshes after cache expiry can block while Vault is contacted. Prefer the async API in asynchronous code. Async methods accept an optional CancellationToken as their last parameter.

Settings are controlled by environment variables and Atlas cluster configuration; no options callback is needed. Use HashiVault.CreateVaultClient() for an independent client for direct Vault operations; reuse and dispose independent clients after their operations finish. See the sections below for authentication, caching, ownership, and advanced operations.

See https://elvia.atlassian.net/wiki/spaces/Utviklerhandbok/pages/1944912100/Use+of+Hashicorp+Vault+from+dotnet+core

Authentication and environment variables

Authentication uses the first applicable method in this order:

  1. VAULT_TOKEN selects Vault token authentication.
  2. Kubernetes service-account authentication is selected in an Atlas cluster, that is a Kubernetes pod with the mounted service-account files and ELVIA_ENVIRONMENT set.
  3. ROLE_ID selects AppRole authentication.
  4. Outside Atlas, including Kubernetes pods without ELVIA_ENVIRONMENT (for example elvia-runner), Entra ID is the local-development fallback, and https://vault.dev-elvia.io is the default address when VAULT_ADDR is not set. A configured GITHUB_TOKEN is not supported and does not select an authentication method.

The same selection logic validates the configuration when a client is created and chooses the method at login. VAULT_ADDR is only required when VAULT_TOKEN or ROLE_ID authentication is selected, and explicit MOUNT_PATH together with ROLE bypasses service-account name parsing.

Set environment variables before creating a configuration root or making the first static Vault call. These are the environment variables read by the library:

Environment variable Purpose
VAULT_ADDR Vault URL
VAULT_TOKEN Vault token authentication
ROLE_ID AppRole authentication
MOUNT_PATH Kubernetes auth mount override
ROLE Kubernetes auth role override
SERVICE_ACCOUNT_PATH Kubernetes service-account token file
KUBERNETES_NAMESPACE Kubernetes namespace
KUBERNETES_SERVICE_HOST Kubernetes-injected in-cluster API host
KUBERNETES_SERVICE_PORT Kubernetes-injected in-cluster API port
VAULT_CACERT Path to the Vault CA certificate file
ELVIA_ENVIRONMENT Atlas environment marker
ELVIA_VAULT_CACHE_TTL_SECONDS Secret-cache lifetime in seconds
GITHUB_TOKEN Detected only to report that the removed GitHub auth method is unsupported

VAULT_ADDR overrides the Atlas ConfigMap hostname, and VAULT_CACERT selects a Vault CA file instead of the ConfigMap CA. Kubernetes settings in the vault ConfigMap are read once per client. The default service-account token path is /var/run/secrets/kubernetes.io/serviceaccount/token.

Entra ID is intended for local development and is blocked when VAULT_ADDR targets the production Vault host vault.elvia.io. For production, configure a Vault token with VAULT_TOKEN, or use the Atlas Kubernetes authentication setup.

The local Entra ID token cache is stored per Vault host at <LocalApplicationData>/Elvia/Vault/token-{host}.json (for example, under the user's local application data directory on Windows). On Linux and macOS, the cache directory and file use owner-only permissions.

Vault paths and key matching

Vault paths can be written with / separators or as configuration keys with : separators. For example, the static API path system/kv/path/key corresponds to the configuration key system:kv:path:key. The path is system/kv/path, and key is the field in that secret; kv is the KV engine segment. Use / paths with the static HashiVault methods and : keys when reading from IConfiguration.

KV v1 and v2 mounts are both supported. The client checks the mount's KV version and uses the corresponding Vault API path; successful mount-version checks are cached for one hour. If Vault denies mount metadata access, the client falls back to KV v1.

Configuration key matching is case-insensitive. Hyphens and underscores are treated as equivalent, and matching also tries forms with separators removed. For example, client-id, client_id, and clientid can resolve to the same Vault field.

Secret lookup and caching

The configuration provider is lazy: registering it or building a root does not preload secrets. The first lookup and refreshes after cache expiry can make synchronous network calls to Vault. Successful secret dictionaries are cached per client and dictionary path for five seconds by default. Set ELVIA_VAULT_CACHE_TTL_SECONDS before client creation to override this with a non-negative integer number of seconds (digits only, up to 2147483647). A value of 0 disables secret caching; negative or invalid values fail at client creation.

Concurrent lookups of the same dictionary share a load when caching is enabled. Failed loads and missing data are not cached, and expired values are not served after a failed refresh. Canceling a lookup cancels only that caller's wait on a shared load; with caching disabled, cancellation is passed to the Vault request. A TTL of 0 disables the cache for both parsed dictionaries and their underlying raw Vault responses. Returned dictionaries are independent mutable copies. Mount KV-version metadata has a separate one-hour cache.

Additional Vault operations

The static HashiVault API includes listing and configuration-section helpers. Transit and TOTP operations are available on an independent IVaultClient created by the static factory:

var names = await HashiVault.ListSecretsAsync("system/kv/path");
var section = HashiVault.GetSection("system:kv:path");
var value = section["key"];

var client = HashiVault.CreateVaultClient();
try
{
    var ciphertext = await client.EncryptText("transit", "key", "secret text");
    var isValid = await client.VerifyTotp("user-id", "123456");
}
finally
{
    (client as IDisposable)?.Dispose();
}

ListSecrets lists names in a Vault folder; GetSection exposes a Vault path as an IConfigurationSection. Transit clients also support decrypting, base64 encryption/decryption, and signing/verifying signatures. TOTP clients can register a user (returning a URL and base64 QR code) and verify a code. Reuse the client and dispose it after its operations complete.

To load a Google service-account key from Vault, call the static configuration extension:

builder.Configuration.UseGoogleServiceAccount(
    "mdmx/kv/gcp-serviceaccounts/ingress-structuredata");

This reads the service-account-key field, writes credentials to an absolute process-specific temporary file (not the working directory), and sets GOOGLE_APPLICATION_CREDENTIALS to that file. The file is cleaned up on process exit on a best-effort basis.

Errors

Secret lookups such as EnsureHasValue and GetGenericSecret throw ConfigurationException. Configuration errors are reported directly (for example Not configured: {path}), while unexpected failures are wrapped once with the original error as InnerException. Vault login failures throw VaultAuthenticationException, which derives from ConfigurationException; the underlying cause, such as a Vault response and its status code, is available as InnerException.

Vault client lifetime

Reuse clients rather than creating one per request. Connections are pooled and renewed after five minutes to pick up DNS changes; requests include Elvia.Configuration/{AssemblyInformationalVersion} as their User-Agent. Configured CA validation and hostname checks still apply.

The static HashiVault methods share a process-lifetime client. HashiVault.CreateVaultClient() instead returns an independent, caller-owned client: after all its operations have completed, dispose it via IDisposable:

var client = HashiVault.CreateVaultClient();
using var lifetime = (IDisposable)client;
var secret = await client.GetGenericSecret("shared/kv/info/environment");

Disposing a configuration root built with the default AddHashiVaultSecrets() factory disposes its Vault client. Clients returned by HashiVault.CreateVaultClient() or by an injected IVaultClientFactory are caller-owned; the configuration provider does not dispose them. Providers over the shared static client do not own it. Finish outstanding reads before disposal.

Kubernetes cluster settings

Service account routing metadata supports both legacy and projected JWT claim formats. The library only decodes the payload to select the Vault role/mount; it does not validate the JWT signature, issuer or expiry. Vault authenticates the original, unchanged token.

The library no longer references System.IdentityModel.Tokens.Jwt or Microsoft.IdentityModel.Protocols.OpenIdConnect directly. Applications using those APIs must add their own explicit package references, even if another dependency currently provides them transitively.

When using Atlas cluster configuration, each Vault client reads the named ConfigMap vault in namespace vault once and reuses vault_hostname, vault_cacert (base64) and vault_base_mountpoint, including on re-authentication. The service account needs RBAC get permission on configmaps/vault; list permission is not required. A missing required ConfigMap causes an explanatory ConfigurationException.

This read uses a direct HTTPS GET /api/v1/namespaces/vault/configmaps/vault, without the KubernetesClient package. Atlas detection requires ELVIA_ENVIRONMENT in addition to in-cluster detection: KUBERNETES_SERVICE_HOST, KUBERNETES_SERVICE_PORT and the mounted token and ca.crt files under /var/run/secrets/kubernetes.io/serviceaccount/. A Kubernetes pod without ELVIA_ENVIRONMENT is not treated as Atlas. The API request uses that token and trusts only that CA, with hostname validation. Outside Atlas the ConfigMap is not read. The Kubernetes API connection cannot be configured explicitly. SERVICE_ACCOUNT_PATH selects the JWT used for Vault login, not the Kubernetes API token. The temporary Kubernetes HTTP client is disposed after reading the map. HTTP errors propagate, and redirects are rejected rather than followed.

Existing overrides retain priority: VAULT_ADDR overrides the cluster hostname, VAULT_CACERT selects a CA file instead of the cluster CA, and MOUNT_PATH together with ROLE overrides convention-based Kubernetes authentication. Without vault_base_mountpoint, the auth mount defaults to kubernetes/{namespace}/{serviceAccount}. Create a new client to pick up changed cluster settings.

Product Compatible and additional computed target framework versions.
.NET net10.0 is compatible.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages (13)

Showing the top 5 NuGet packages that depend on Elvia.Configuration:

Package Downloads
Elvia.Edna.Events

Publish and consume events on Elvia's Kafka platform (EDNA) with schema registry support, OpenTelemetry tracing and metrics, and Meldingsportalen message logging.

Elvia.KvalitetsportalLogger

Library for KvalitetsportalLogger.

Elvia.Mdmx.Apps.Shared

Shared library for MDMx applications.

Elvia.Elvid.Bff.UserClient

Package Description

Elvia.Edna.Dataproduct

Package Description

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
8.0.0 0 11/16/2026
8.0.0-beta2 250 10/27/2026
8.0.0-beta1 127 10/15/2026
7.0.1-preview.1-54 48 11/15/2026
7.0.1-preview.1-53 51 11/14/2026
7.0.1-preview.1-52 48 11/12/2026
7.0.1-preview.1-51 46 11/11/2026
7.0.1-preview.1-50 65 10/31/2026
7.0.1-preview.1-49 61 10/30/2026
7.0.1-preview.1-48 57 10/30/2026
7.0.1-preview.1-47 67 10/29/2026
7.0.1-preview.1-46 72 10/23/2026
7.0.1-preview.1-45 63 10/20/2026
7.0.1-preview.1-44 75 10/14/2026
7.0.1-preview.1-40 72 9/28/2026
7.0.1-preview.1-39 81 9/22/2026
7.0.1-preview.1-38 95 9/19/2026
7.0.1-preview.1-37 83 9/19/2026
7.0.1-preview.1-36 78 9/18/2026
7.0.1-preview.1-35 84 9/16/2026
Loading failed