MathewTaylor.Doppler.Configuration 0.1.0

Doppler Configuration Provider for .NET

A Doppler secrets provider for Microsoft.Extensions.Configuration. It loads your Doppler secrets at host startup and merges them into IConfiguration, so the rest of your app reads them through the same IConfiguration / IOptions<T> surface as any other source — no Doppler-specific code in your domain.

This is the in-process equivalent of the AddAzureKeyVault(...) / AddSecretsManager(...) providers. The secret backend becomes one swappable Add…() line in Program.cs.

Unofficial. Community-maintained and not affiliated with or endorsed by Doppler, Inc. "Doppler" is a trademark of its respective owner.

Why not just the Doppler CLI? doppler run --name-transformer dotnet-env -- dotnet … is great and needs no code, but it requires the CLI on every host and makes the CLI the process parent. This provider loads secrets in-process via the Doppler API, which suits all-in-one Docker dev/test boxes and keeps the loading mechanism identical to your other configuration providers.

Packages

The cache abstraction (IDopplerSecretCache) and the Options.Cache hook live in core; only the concrete FileSecretCache ships in the add-on. A project that doesn't reference the add-on cannot call FileSecretCache — the fallback is excluded at compile time, not just by convention.

Install

dotnet add package MathewTaylor.Doppler.Configuration

# only where you want the cold-start fallback:
dotnet add package MathewTaylor.Doppler.Configuration.FileCache

The id Doppler.Extensions.Configuration is taken by an abandoned 2022 package, hence the MathewTaylor. prefix.

Quick start

using Doppler.Configuration;

var builder = WebApplication.CreateBuilder(args);

builder.Configuration.AddDoppler(options =>
{
    // Token resolves from DOPPLER_TOKEN if you don't set it here.
    options.Optional       = builder.Environment.IsDevelopment();
    options.ReloadInterval = TimeSpan.FromMinutes(5);
});

var app = builder.Build();

Provide the token via environment variable (recommended):

export DOPPLER_TOKEN="dp.st.dev.xxxxxxxx"
dotnet run

Key mapping

Doppler secret names are UPPER_SNAKE_CASE. Configuration keys are hierarchical, delimited by :. The default KeyMapper maps the __ separator to :, matching .NET's environment-variable convention:

Configuration keys are case-insensitive, so casing of the Doppler name doesn't matter for binding. Override options.KeyMapper for a different scheme.

Source ordering

Providers added later win. Add Doppler after appsettings.json and environment variables if Doppler should be authoritative, or before them if local overrides should take precedence:

builder.Configuration
    .AddJsonFile("appsettings.json")
    .AddEnvironmentVariables()
    .AddDoppler();   // Doppler overrides the above

Options

All-in-one Docker dev/test boxes

Pass the token into the container and let the app self-hydrate at startup — no CLI in the image:

# docker-compose.yml
services:
  app:
    build: .
    environment:
      DOPPLER_TOKEN: ${DOPPLER_TOKEN}   # from your shell / .env, never committed

builder.Configuration.AddDoppler(); // reads DOPPLER_TOKEN, fetches at boot

Live reload

Set ReloadInterval and consume via IOptionsMonitor<T>; bound options refresh automatically when a reload detects changes. Background reload failures are swallowed so a transient Doppler outage never crashes a running host.

Resilience and the cold-start cache

There are two distinct outage windows:

• Doppler goes down while the app is running — already covered. Secrets stay in the provider's in-memory store after the first successful load, and background reloads never clear them on failure. No cache needed.
• Cold start while Doppler is unreachable (container restart mid-outage) — the only real gap. With Optional = false the host won't boot; with Optional = true it boots with no secrets. For this case only, you can opt into an encrypted on-disk snapshot.

In production, failing fast on a cold start is usually safest — let your orchestrator retry. The cache is most useful on local/dev/test boxes. It lives in the separate MathewTaylor.Doppler.Configuration.FileCache package, is opt-in and always encrypted (no plaintext-on-disk default):

var key = Convert.FromHexString(Environment.GetEnvironmentVariable("DOPPLER_CACHE_KEY")!); // 32 bytes

builder.Configuration.AddDoppler(o =>
{
    o.Cache = FileSecretCache.WithAesGcm("/var/lib/myapp/doppler.snapshot", key);
});

On every successful fetch the snapshot is refreshed (AES-256-GCM, 0600 perms on Unix). If a startup fetch fails and a valid snapshot exists, the provider loads it (degraded but running) instead of throwing. A tampered or wrong-key snapshot is treated as no cache. Supply your own protect/unprotect delegates via the FileSecretCache constructor (e.g. Windows DPAPI) or implement IDopplerSecretCache for a different store.

Security notes

• Secret values are never logged by this library.
• Treat the service token like any credential — inject it via environment, never commit it.
• Scoped service tokens (read-only, single config) are strongly preferred over personal tokens.

How it works

The provider implements the standard IConfigurationSource / ConfigurationProvider contract. At build time it calls Doppler's GET /v3/configs/config/secrets/download?format=json endpoint with Authorization: Bearer <token>, flattens the returned JSON object, applies the key mapper, and populates the provider's Data. Loading is sync-over-async inside Load() — the same approach the framework's own Azure Key Vault provider uses — and runs once at startup, off the request path.

License

MIT