Kralizek AWS Secrets Manager Configuration Extensions

When secrets are loaded into the .NET configuration system, you can control how their names (keys) are transformed:

• Built-in Mapping: Use SecretKeyMappingOptions to shape configuration keys using predefined logic.
• Full Customization: Use a context-based KeyGenerator for complete control over how secret names are converted into configuration keys.
• Duplicate Handling: Use ResolveDuplicateKeys to manage scenarios where multiple secrets might map to the same configuration key within a single provider call.

Secrets containing JSON objects are automatically flattened into configuration key/value pairs using : as the separator, rooted at the secret's name.

Example: Secret Name: myapp/database
Value: {"Host":"db.example.com","Port":"5432"}

Resulting Keys:

• myapp/database:Host = db.example.com
• myapp/database:Port = 5432

In 2.0.0, the default key generation behavior changed. By default, the SecretNamePathSeparator (which defaults to /) is replaced by the .NET configuration delimiter (:), and leading/trailing delimiters are trimmed.

For example, a secret named /my-app/production/database now produces my-app:production:database instead of /my-app/production/database.

To restore the previous behavior where secret names are used verbatim, set options.KeyMapping.SecretNamePathSeparator = null in your configuration lambda.

builder.AddSecretsManagerKnownSecret(
    "my-app/production",
    options =>
    {
        options.KeyMapping.SecretNamePathSeparator = null;
    });

The direct overloads for AWSCredentials and RegionEndpoint have been removed. To provide custom credentials or region settings, you should either pass an AWSOptions object or provide a pre-built IAmazonSecretsManager client.

// Option 1: Using AWSOptions
var awsOptions = builder.Configuration.GetAWSOptions();
builder.AddSecretsManagerDiscovery(awsOptions, options => { ... });

// Option 2: Using a pre-built client
var config = new AmazonSecretsManagerConfig { ServiceURL = "http://localhost:4566" };
var client = new AmazonSecretsManagerClient(credentials, config);
builder.AddSecretsManagerDiscovery(client, options => { ... });

Install the AWS Secrets Manager configuration provider for Microsoft.Extensions.Configuration using the dotnet CLI.

dotnet add package Kralizek.Extensions.Configuration.AWSSecretsManager

You can control how the AWS SDK is initialized when using the library. You can either configure global AWS options or provide your own pre-configured client instance.

• Configure AWS Options: Use AWSOptions to set the region, profile, or other SDK-specific settings.
• Custom Client: Pass a caller-created IAmazonSecretsManager instance directly to the extension methods (e.g., AddSecretsManager*(client, ...)).

To use LocalStack, configure a custom IAmazonSecretsManager client with the LocalStack ServiceURL and pass it to the registration method. For local development, it is recommended to use KnownSecret or KnownSecrets with stable names rather than ARNs, as Discovery mode relies on ARNs that LocalStack may regenerate.

var client = new AmazonSecretsManagerClient(new AmazonSecretsManagerConfig
{
    ServiceURL = "http://localhost:4566",
    AuthenticationRegion = "us-east-1"
});

builder.Configuration.AddSecretsManagerKnownSecrets(
    secretIds: new[] { "my-secret" },
    secretsManager: client);

To use IAM roles for service accounts (IRSA) in EKS, you must include the AWSSDK.SecurityToken package to allow the provider to authenticate via the pod's IAM role.

dotnet add package AWSSDK.SecurityToken

The library supports common production requirements:

• Bootstrap Logging: Configure the library to enable logging while the configuration is still being built (useful for debugging startup issues).
• Reloading Secrets: In ASP.NET Core applications, you can configure secrets to reload periodically, allowing the application to pick up updated values from AWS Secrets Manager without a restart.