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.

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 the CLI with the following command:

./bin/kuzzle encryptSecrets 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:

./bin/kuzzle decryptSecrets config/secrets.enc.json --vault-key strongpassword
[ℹ] Decrypting secrets...
[✔] Secrets successfully encrypted: config/secrets.json

Load encrypted secrets at startup #

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

• in the command line: ./bin/kuzzle start --secrets-file /var/secrets.enc.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 command line: ./bin/kuzzle start --vault-key verystrongpassword
• in an environment variable export KUZZLE_VAULT_KEY=verystrongpassword

Accessing secrets in 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.