Using Config Sesame

See Installing Config Sesame for instructions on how to install and configure the tool.

Performing Password Lookups

The following examples ilustrate the process of augmenting secrets references with their resolution from Vault; see Details of Configuration Parsing for more.

  • my: database: password_secret: vault:db/password

    gets resolved to

    my: database: password: the_actual_password

  • The configuration…

      auth_secret: "vault:db/credentials"


        user: jane
        password: test123

A Practical Example

To see how everything works in reality, the project repository comes with test data that can be used in combination with the Vault setup described in the previous chapter.

First, let’s populate the test server with some secrets:

$ invoke populate
vault write "secret/sesame/db/credentials" pwd="SECRET" user="kermit"
Success! Data written to: secret/sesame/db/credentials
vault write "secret/sesame/db2/password" value="ALSO_SECRET"
Success! Data written to: secret/sesame/db2/password
vault write "secret/sesame/resource/password" value="MORE_SECRETS"
Success! Data written to: secret/sesame/resource/password

Since this delegates the work to the vault command, you have to set both the VAULT_ADDR and VAULT_TOKEN environment variables beforehand.

Now we can use the sample data in src/tests/data to perform a lookup on these keys:

$ config-sesame open src/tests/data/*yml -o- -b secret/apps -b secret/sesame
    pwd: SECRET
    user: kermit
    password: ALSO_SECRET
    password: MORE_SECRETS

Note that the source of each resolved secret is also added to the result, for diagnostic and auditing purposes. In case one of the secret references cannot be resolved, we get an error:

$ config-sesame open src/tests/data/*yml -b foo -b bar
Usage: config-sesame open [OPTIONS] CFGFILE [...]

Error: Cannot find key "db/credentials" in any of these bases: foo, bar.

Details of Configuration Parsing

To support reading multiple input files, a simple merging strategy is used:

  • Objects (dicts, hashes) are merged recursively.
  • Scalar values and lists are simply replaced (i.e. the last file has priority).

For the purpose of finding references to secrets and writing their resolution to a new file, this always fits the bill.

The rules for handling secrets references:

  • Secrets references are stored like any other configuration key, and take the form vault:«vault-path».
  • The «vault-path» part is resolved relative to a base path, e.g. “apps/«app name»/«brand»/«environment»”.
  • The Vault base path is part of the tool’s configuration.
  • Resolved secrets are added to secrets.yml as «key» for a reference named «key»_secret.
  • If «vault-path» references a single scalar value, it is added as such.
  • If «vault-path» references a collection of values, they are added as an object (a/k/a dict or hash).
  • The URL where the secret was retrieved from is added as «key»_secret_url.