Configure Vault for Storing Secrets
HashiCorp’s Vault is a popular solution for storing secrets. While F5 NGINX Management Suite provides encryption-at-rest for secrets stored on disk, if you have an existing Vault installation, you may prefer to store all secrets in one place. NGINX Management Suite provides a driver you can use to connect to existing Vault installations and store secrets.
Before You Begin
To complete the steps in this guide, you need the following:
- A working understanding of Vault and its operations
- A running version of Vault 1.8.8 or later
Create Periodic Service Tokens
Access to a vault requires a renewable token.
Note:
If you attempt to use the vault’s Root Token, NGINX Management Suite will not be able to start the secrets driver, as that token is not renewable.
To create a periodic service token for NGINX Management Suite, take the following steps:
-
Use the Vault user interface to create a new policy.
The “default” policy has no access to store or retrieve secrets, and the root policy is too broad. We recommend creating a policy called
nms_secrets
with these capabilities:path "secret/*" { capabilities = ["create", "read", "update", "delete", "list"] }
-
Create an initial service token that will last so long as it’s renewed on time until it’s manually revoked. We recommend a period of 24 hours, which is used in the following example. NGINX Management Suite will always attempt to renew tokens before expiring, so shorter times also work.
To create a token, take the following step, substituting your vault’s Root Token for
$VAULT_ROOT_TOKEN
and your vault’s address for$VAULT_ADDR
:curl -X POST --header "X-Vault-Token: $VAULT_ROOT_TOKEN" \ --data '{"policies": "nms_secrets", "period": "24h"}' \ $VAULT_ADDR/v1/auth/token/create | jq -r ".auth.client_token" > periodic_token.txt
-
Verify your token works:
curl --header "X-Vault-Token: $(cat periodic_token.txt)" \ $VAULT_ADDR/v1/auth/token/lookup-self | jq .data
-
If everything looks good, stop the
nms-core
service and configure NGINX Management Suite to use your token:sudo systemctl stop nms-core sudo NMS_VAULT_TOKEN=$(cat periodic_token.txt) nms-core secret vault-token sudo systemctl restart nms-core
Start Using Vault to Store Secrets
-
To use the new token on the NGINX Management Suite server, open the
/etc/nms/nms.conf
file for editing. -
Update the
secrets
section indented undercore
to tell NGINX Management Suite how to handle secrets.For example, an internal development installation of Vault might use:
secrets: # change driver to "local" if you want to stop using vault driver: vault config: # local file path for stored secrets when using the local driver path: /var/lib/nms/secrets # key_file is required for local driver key_file: /var/lib/nms/secrets/key # vault address for when using the vault driver address: http://127.0.0.1:8200/v1 # isolation is used to store secrets in a specific namespace and prefix to better restrict access rights # on the local file system or shared vault server. isolation: namespace: secret prefix: secureString
-
Save the changes and close the file.
-
Restart the NGINX Management Suite services to start using Vault to store secrets:
sudo systemctl restart nms
Switching between Vault and Local Encryption
After you’ve set up Vault to store your secrets, you can easily switch between local encryption and Vault as desired.
Switch to Local Encryption
To switch from using Vault to local disk encryption, take the following steps:
-
Stop NGINX Management Suite to ensure exclusive access to the secrets:
sudo systemctl stop nms
-
Run the following command to migrate secrets from Vault to your local disk:
sudo nms-core secret migrate-secrets-to-local
-
Update the
core/secrets/driver
line from/etc/nms/nms.conf
, which you added in the previous section, to saydriver: local
. -
Restart NGINX Management Suite:
sudo systemctl start nms
Switch to Vault
To switch from using local encryption back to Vault, take the following steps:
-
Stop NGINX Management Suite to ensure exclusive access to the secrets:
sudo systemctl stop nms
-
Run the following command to migrate secrets from your local disk to Vault:
sudo nms-core secret migrate-secrets-to-vault
-
Update the
core/secrets/driver
line from/etc/nms/nms.conf
, which you added in the previous section, to saydriver: vault
. -
Restart NGINX Management Suite:
sudo systemctl start nms
Troubleshooting
Token has expired
If the vault service token is manually revoked or expires before renewal – possibly because NGINX Management Suite was shut down and was unavailable to renew the token, all access to stored secrets will fail.
To resolve this problem, you need is to supply a new service token using nms-core secret vault-token
. See the Create Periodic Service Tokens section above for details on generating and supplying a new token.
Certs are missing after switching to/from Vault
When configuring Vault for storing secrets, NGINX Management Suite assumes that no secrets have been stored previously and won’t migrate any existing stored secrets. All existing certs must be uploaded again.
Stored secrets are not deleted: secrets remain in the encrypted disk storage or vault. We can’t guarantee that the secrets will remain accessible forever. If you want to recover the missing secrets, you can switch back to the other method for storing secrets following the instructions above. Then restart NGINX Management Suite to see the old secrets again.