Skip to content

Commit 74c10f9

Browse files
Aschenscottinet
authored andcommitted
Add guide about secrets management with the Vault (#321)
## What does this PR do? Document the secrets Vault. Also add a page for the new `context.secrets` object exposed in plugin context kuzzleio/kuzzle#1315 ### How should this be manually tested? <!-- Please describe the tests that you ran to verify your changes. Provide instructions so we can reproduce. Please also list any relevant details for your test configuration --> - Step 1 : - Step 2 : - Step 3 : ... ### Other changes <!-- Please describe here all changes not directly linked to the main issue, but made because of it. For instance: issues spotted during this PR and fixed on-the-fly, dependencies update, and so on --> ### Boyscout <!-- Describe here minor improvements in the code base and not directly linked to the main changes: typos fixes, better/new comments, small code simplification, new debug messages, and so on. -->
1 parent 4fea2ed commit 74c10f9

File tree

2 files changed

+129
-0
lines changed
  • src/core/1

2 files changed

+129
-0
lines changed
Lines changed: 96 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,96 @@
1+
---
2+
code: false
3+
type: page
4+
title: Secrets Vault
5+
order: 700
6+
---
7+
8+
# Secrets Vault
9+
10+
<SinceBadge version="1.8.0" />
11+
12+
When you develop an application with Kuzzle, you may need to use secrets such as API keys or authentication information.
13+
14+
Of course, it is unacceptable to version these secrets in cleartext with the rest of your source code.
15+
16+
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.
17+
18+
Kuzzle offers a secure storage system for these secrets, the operation is as follows:
19+
- writing secrets to a JSON file,
20+
- manual encryption of this file with a password,
21+
- adding the encrypted file to the repository,
22+
- automatic decryption of the file when Kuzzle starts,
23+
- exposing the secrets in the context of plugins.
24+
25+
Thus, the only secret that it is necessary to communicate to the rest of a team is the encryption password for this file.
26+
27+
## Secrets file format
28+
29+
The secrets file is in JSON format. String values are encrypted but the key names remain the same.
30+
31+
```js
32+
/* config/secrets.json */
33+
{
34+
"aws": {
35+
"secretKeyId": "lfiduras"
36+
},
37+
"cloudinaryKey": "ho-chi-minh"
38+
}
39+
```
40+
41+
Once encrypted, the file looks like the following:
42+
43+
```js
44+
/* config/secrets.enc.json */
45+
{
46+
"aws": {
47+
"secretKeyId": "536553f3181ada6f700cac98100f1266.3181ada66536553f"
48+
},
49+
"cloudinaryKey": "f700cac98100f1266536553f3181ada6.6536553f3181ada"
50+
}
51+
```
52+
53+
## Encrypt and decrypt with the CLI
54+
55+
The encryption of a secret file is done using the CLI with the following command:
56+
57+
```bash
58+
./bin/kuzzle encryptSecrets config/secrets.json --vault-key strongpassword
59+
[ℹ] Encrypting secrets...
60+
[✔] Secrets successfully encrypted: config/secrets.enc.json
61+
```
62+
63+
The file `config/secrets.enc.json` can be added safely to the project repository.
64+
65+
To decrypt a previously encrypted file, use the following command:
66+
67+
```bash
68+
./bin/kuzzle decryptSecrets config/secrets.enc.json --vault-key strongpassword
69+
[ℹ] Decrypting secrets...
70+
[✔] Secrets successfully encrypted: config/secrets.json
71+
```
72+
73+
::: info
74+
You can also specify the vault key in the `KUZZLE_VAULT_KEY` environment variable.
75+
:::
76+
77+
## Load encrypted secrets at startup
78+
79+
Kuzzle will try to decrypt the provided file using the following locations, in that order of priority:
80+
- in the command line: `./bin/kuzzle start --secrets-file /var/secrets.enc.json`
81+
- in an environment variable `export KUZZLE_SECRETS_FILE=/var/secrets.enc.json`
82+
- the default one present at the location `<kuzzle dir>/config/secrets.enc.json`
83+
84+
The decryption key must be provided in one of the following ways, in order of priority as well:
85+
- in the command line: `./bin/kuzzle start --vault-key verystrongpassword`
86+
- in an environment variable `export KUZZLE_VAULT_KEY=verystrongpassword`
87+
88+
Kuzzle start sequence ends in failure if:
89+
- a decryption key is provided and Kuzzle cannot find a file
90+
- Kuzzle finds a file and no decryption key is provided
91+
92+
## Accessing secrets in plugin
93+
94+
Once Kuzzle has successfully loaded the file containing the secrets, it exposes its decrypted content to all plugins.
95+
96+
Secrets are accessible in the [secrets](/core/1/plugins/plugin-context/secrets) property of the plugin context.
Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
---
2+
code: true
3+
type: page
4+
title: secrets
5+
---
6+
7+
# secrets
8+
9+
<SinceBadge version="1.8.0" />
10+
11+
Secrets contained in the [Vault](/core/1/guides/essentials/secrets-vault) and loaded at Kuzzle startup.
12+
13+
They have the same format as in the JSON file:
14+
15+
```js
16+
/* config/secrets.enc.json */
17+
{
18+
"aws": {
19+
"keyId": "a47de7426fbcb8904290e376f147bc73.8e4b35be62ecbc53"
20+
}
21+
}
22+
```
23+
24+
```js
25+
init (config, context) {
26+
console.log(context.secrets);
27+
// {
28+
// aws: {
29+
// keyId: 'decrypted aws key id'
30+
// }
31+
// }
32+
}
33+
```

0 commit comments

Comments
 (0)