How To Use It (Details)

IDs

As a reminder, to specify a value for (for example) Secrets:Ids:0 as an environment variable, it must be spelled Secrets__Ids__0.

Valid JSON

A key advantage of using Secrets Manager over something like an SSM Parameter Store SecureString parameter is that the design of Secrets Manager expects that the values stored therein will be compound values. SSM Parameter Store allows paths to be queried recursively in order to provide the same functionality, though this was more awkward in practice. The default AWS console UI shows a set of keys and values, which Secrets Manager will store internally as a JSON string.

Once JSON is expected, a host of functionality opens up. For example, CloudFormation dynamic references can select a single value from the compound document for use with the resources that support it. This allows decreased configuration complexity and increased synergy between native AWS features and libraries such as this one.

Alternative Key Delimiter

One of the members of the Microsoft.Extensions.Configuration ecosystem is Microsoft.Extensions.Configuration.EnvironmentVariables. This represents configuration as environment variables (natch), which are limited in their format. They must be key/value pairs of a string to a string. This would make it impossible to specify deep configuration values using the library, except that Microsoft.Extensions.Configuration allows configuration to be specified in a flattened-key format. For example, the following JSON document:

{
  "Secrets": {
    "Ids": ["an-application", "a-value"]
  }
}

…is equivalent to this one:

{
  "Secrets:BaseId:0": "an-application",
  "Secrets:BaseId:1": "a-value"
}

(Perhaps you've noticed that this document has used that format above, or that User Secrets creates flattened JSON documents using this format by default.)

But this form, too, is problematic. UNIX-style environment variable names aren't allowed to include the character :. An alternative key delimiter was introduced for just this reason. The same configuration as above can be specified on the command-line like this:

Secrets__Ids__0='an-application' dotnet run

Similarly, there are situations for which AWS Secrets Manager keys cannot contain colons. For example, CloudFormation dynamic references can only select a key in a JSON-bodied value if that key does not contain a colon – colon is used as the separator for segments of the reference definition. For that reason, Tiger.Secrets also accepts the alternative key delimiter. A secret with the following value:

{
  "Deep__Key": "value"
}

…is equivalent to this one:

{
  "Deep:Key": "value"
}

…and this one:

{
  "Deep": {
    "Key": "value"
  }
}

Though either of the first two forms is probably simpler to administrate.