Guides v1.x

You are currently looking at the documentation of a previous version of Kuzzle. We strongly recommend that you use the latest version. You can also use the version selector in the top menu.

Secrets Vault #

Available since 1.8.0

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.

Copied to clipboard!
/* config/secrets.json */
  "aws": {
    "secretKeyId": "lfiduras"
  "cloudinaryKey": "ho-chi-minh"

Once encrypted, the file looks like the following:

Copied to clipboard!
/* 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:

Copied to clipboard!
./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:

Copied to clipboard!
./bin/kuzzle decryptSecrets config/secrets.enc.json --vault-key strongpassword
[] Decrypting secrets...
[] Secrets successfully encrypted: config/secrets.json

You can also specify the vault key in the KUZZLE_VAULT_KEY environment variable.

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

Kuzzle start sequence ends in failure if:

  • a decryption key is provided and Kuzzle cannot find a file
  • Kuzzle finds a file and no decryption key is provided

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.