Elvia.Configuration
8.0.0
dotnet add package Elvia.Configuration --version 8.0.0
NuGet\Install-Package Elvia.Configuration -Version 8.0.0
<PackageReference Include="Elvia.Configuration" Version="8.0.0" />
<PackageVersion Include="Elvia.Configuration" Version="8.0.0" />
<PackageReference Include="Elvia.Configuration" />
paket add Elvia.Configuration --version 8.0.0
#r "nuget: Elvia.Configuration, 8.0.0"
#:package Elvia.Configuration@8.0.0
#addin nuget:?package=Elvia.Configuration&version=8.0.0
#tool nuget:?package=Elvia.Configuration&version=8.0.0
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.
Authentication and environment variables
Authentication uses the first applicable method in this order:
VAULT_TOKENselects Vault token authentication.- Kubernetes service-account authentication is selected in an Atlas cluster, that is a
Kubernetes pod with the mounted service-account files and
ELVIA_ENVIRONMENTset. ROLE_IDselects AppRole authentication.- Outside Atlas, including Kubernetes pods without
ELVIA_ENVIRONMENT(for exampleelvia-runner), Entra ID is the local-development fallback, andhttps://vault.dev-elvia.iois the default address whenVAULT_ADDRis not set. A configuredGITHUB_TOKENis 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 | Versions 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. |
-
net10.0
- Microsoft.Extensions.Caching.Memory (>= 11.0.0)
- Microsoft.Extensions.Configuration (>= 11.0.0)
- Microsoft.Extensions.Configuration.Json (>= 11.0.0)
- Microsoft.Extensions.Http.Resilience (>= 11.0.0)
- Microsoft.Extensions.Logging.Abstractions (>= 11.0.0)
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 |