Secrets Vault #

When you develop an application with Kuzzle, you may need to use secrets such as API keys or authentication information.

Of course, it is unacceptable to version these secrets in cleartext with the rest of your source code.

However, it is still practical to be able to share these secrets with the rest of your team, or to add them to the repository for automated production.

Kuzzle offers a secure storage system for these secrets, the operation is as follows:

• writing secrets to a JSON file,
• manual encryption of this file with a password,
• adding the encrypted file to the repository,
• automatic decryption of the file when Kuzzle starts,
• exposing the secrets in the context of plugins.

Thus, the only secret that it is necessary to communicate to the rest of a team is the encryption password for this file.

See this project on Github.

Secrets file format #

The secrets file is in JSON format. String values are encrypted but the key names remain the same.

/* config/secrets.json */
{
  "aws": {
    "secretKeyId": "lfiduras"
  },
  "cloudinaryKey": "ho-chi-minh"
}

Once encrypted, the file looks like the following:

/* config/secrets.enc.json */
{
  "aws": {
    "secretKeyId": "536553f3181ada6f700cac98100f1266.3181ada66536553f"
  },
  "cloudinaryKey": "f700cac98100f1266536553f3181ada6.6536553f3181ada"
}

Encrypt and decrypt with the CLI #

The encryption of a secret file is done using Kourou, the Kuzzle CLI with the following command:

kourou vault:encrypt config/secrets.json --vault-key strongpassword
[ℹ] Encrypting secrets...
[✔] Secrets successfully encrypted: config/secrets.enc.json

The file config/secrets.enc.json can be added safely to the project repository.

To decrypt a previously encrypted file, use the following command:

kourou vault:decrypt config/secrets.enc.json --vault-key strongpassword
[ℹ] Decrypting secrets...
[✔] Secrets successfully encrypted: config/secrets.json

You can see the complete list of Kuzzle Vault related commands in Kourou on Github.

Load encrypted secrets at startup #

Kuzzle will try to decrypt the provided file using the following locations, in that order of priority:

• in the app.vault.file property: app.vault.file = './secrets.env.json';
• in an environment variable export KUZZLE_SECRETS_FILE=/var/secrets.enc.json
• the default one present at the location <kuzzle dir>/config/secrets.enc.json

The decryption key must be provided in one of the following ways, in order of priority as well:

• in the app.vault.key property: app.vault.key = 'verystrongpassword';
• in an environment variable export KUZZLE_VAULT_KEY=verystrongpassword

Accessing secrets in your application #

Once Kuzzle has successfully loaded the file containing the secrets, it exposes its decrypted content to your application.

Secrets are accessible in the app.vault.secrets property.

Accessing secrets in your plugin #

Once Kuzzle has successfully loaded the file containing the secrets, it exposes its decrypted content to all plugins.

Secrets are accessible in the secrets property of the plugin context.