AWS Secrets Manager in .NET: How To Load Your Secrets Straight into IConfiguration

If you build .NET apps that run on AWS, you have probably lived this moment. A connection string, an API key, maybe a signing secret, all sitting in appsettings.json where they really should not be. So you move them to AWS Secrets Manager, which is the right call, and then you notice the boring part. Now you have to write code to fetch the secret, parse it, and feed every value into the rest of your app.

I built a small NuGet package to make that last part disappear, which is exactly what you want from secrets handling. It is called RF.AWSSecretsManager.Configuration, and it connects AWS Secrets Manager to the standard .NET configuration system. The rest of your code does not change at all.

Here is the whole idea in one sentence. Your secret lives in AWS as JSON, the package reads it once at startup, and every value shows up in IConfiguration as if it had always been there.

The problem with the usual approach

Most teams start by reading the secret by hand. You create an AWS SDK client, call GetSecretValue, deserialize the JSON, and then copy values into your options classes. It works, but it spreads AWS specific code across your startup, it usually ends up logging things it should not, and it does not play nicely with the configuration system that the rest of .NET already uses.

The cleaner pattern is to treat Secrets Manager as just another configuration source, the same way appsettings.json and environment variables are sources. That is what this package does.

Installing it

dotnet add package RF.AWSSecretsManager.Configuration

It targets net8.0 and net10.0, and it uses System.Text.Json under the hood. There is no Newtonsoft.Json dependency to drag along.

The simplest possible example

Store your secret in AWS as JSON, for example a secret named my/app/secrets that contains this:

{
  "MySetting": "Some value"
}

Then add one line when you build configuration:

using Microsoft.Extensions.Configuration;
using RF.AWSSecretsManager.Configuration;

var configuration = new ConfigurationBuilder()
    .AddJsonFile("appsettings.json", optional: true)
    .AddAWSSecretsManager("my/app/secrets")
    .Build();

var value = configuration["MySetting"]; // "Some value"

That is the entire integration. Credentials and region come from the default AWS SDK chain, so environment variables, a shared credentials file, or an IAM role all work without extra setup.

How the JSON becomes configuration keys

Configuration in .NET is flat, with keys like ConnectionStrings:Default. Secrets are often nested. The package bridges that gap by flattening nested objects with a colon, which is the same separator the configuration system already uses.

So a secret like this:

{
  "ConnectionStrings": {
    "Default": "Server=db;Database=app;User Id=svc;Password=p"
  },
  "Feature": {
    "Timeout": 30
  }
}

turns into these keys:

ConnectionStrings:Default
Feature:Timeout

Which means your existing GetConnectionString("Default") call and your bound options classes keep working without any changes. One note worth knowing up front: in this version, JSON arrays are skipped on purpose. They do not create keys and they do not throw. Keep your secrets as flat or nested objects and you are good.

Store the secret as a JSON object

A quick word on how to shape the secret, because it matters. AWS Secrets Manager stores a single string per secret, and the console gives you two editors for it. The Key/value editor writes a JSON object for you, so if you use that you are already set. The Plaintext editor stores exactly what you type, which might be JSON or might be a single raw value like one password.

This package expects that string to be a JSON object, and there is a good reason. IConfiguration is a set of keys and values, and a JSON object is the thing that carries both the key names and their values together. A bare value like p@ssw0rd has a value but no key, so there would be nothing to file it under. That is exactly the gap this package fills: your JSON keys become your configuration keys, with no glue code in between.

Two things follow from that:

A single raw value is not loaded in this version. If your secret is just one string, wrap it as one JSON property and you are good:

{
  "Db:Password": "p@ssw0rd"
}

If the secret is not valid JSON at all, startup fails fast with a clear message rather than guessing what you meant. That is on purpose.

Loading a single raw value keyed by the secret name is on the roadmap. For now, JSON objects are the format that keeps every value addressable by name, which is what the configuration system wants.

Using it in ASP.NET Core

In a minimal hosting app you can call the extension right on the configuration builder:

var builder = WebApplication.CreateBuilder(args);

builder.Configuration.AddAWSSecretsManager("my/app/secrets");

var app = builder.Build();

From here, anything that reads IConfiguration, including the options pattern, sees the values from Secrets Manager merged in with your other sources.

It is careful with your secrets

This is the part I care about most, because a config helper that leaks secrets is worse than no helper at all.

The package never writes secret values to logs. Not on success, not on failure. The only thing it will log is the secret name and error details, and even the name can be masked if you want an extra layer of caution:

.AddAWSSecretsManager("my/app/secrets", options =>
{
    options.MaskSecretNameInLogs = true;
    // "my/app/secrets" shows up as "my/***ts"
});

Pair that with a least privilege IAM policy so the app can read only the secrets it actually needs:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": ["secretsmanager:GetSecretValue"],
      "Resource": "arn:aws:secretsmanager:us-east-1:123456789012:secret:my/app/secrets-*"
    }
  ]
}

When you need more control over the client

Most apps are happy with the default client. When you need a specific region or a client you built yourself, pass it in:

using Amazon;
using Amazon.SecretsManager;

IAmazonSecretsManager client = new AmazonSecretsManagerClient(RegionEndpoint.USEast1);

var configuration = new ConfigurationBuilder()
    .AddAWSSecretsManager("my/app/secrets", client)
    .Build();

When you supply the client, the package leaves it alone and does not dispose it, since you own its lifetime. There are also overloads that accept an ILogger or an ILoggerFactory with a category name, which fit nicely into dependency injection.

What actually happens at startup

A few behaviors are worth knowing so there are no surprises in production.

The secret is read once, while configuration is being built. If the secret is missing or the payload is not valid JSON, startup fails fast with a clear error instead of letting your app run in a half configured state. Transient AWS issues like throttling or a brief 5xx are retried with exponential backoff, three attempts with a growing delay, before giving up. And because the values flow through the normal configuration pipeline, your secret never has to be passed around by hand.

Loading once at startup is the right default for most services, and it keeps the behavior predictable.

When this is a good fit, and when it is not

It fits well when you have one JSON secret per app or per environment, you want those values in IConfiguration with no custom plumbing, and you care about not leaking secrets into logs.

It is not trying to be everything yet. If you need automatic refresh when a secret rotates, or you want to merge many secrets at once, those are on the roadmap rather than in the box today. More on that next.

What is coming next

The current version is intentionally small and focused. The features I am looking at for upcoming releases include an optional mode so startup can continue when a secret is absent, refresh support so rotated secrets reload without a restart, a key prefix option for scoping, array handling, and loading more than one secret. If one of these matters to you, that is genuinely useful feedback, and the issue tracker is the best place to say so.