Vault

The Vault is a centralized system for storing sensitive information (secrets) such as API keys, passwords, certificates, and tokens. Secrets are never stored in plain text, but encrypted for heightened security. Access to the Vault is controlled via a role-based access system, ensuring that only authorized users can retrieve or modify secrets. Key management, encryption, and access control are handled separately within the system.

Vault architecture

The Vault secures secrets through a layered encryption model based on a public/private key pair. The public key encrypts the main AES (advanced encryption standard) key, while the private key decrypts it.

The public key and private key should be stored securely and be kept outside the Neptune DXP - Open Edition installation directory to prevent unauthorized access.

Pre-configuration considerations

Before the Vault can be used, it must be enabled in the .env file of your instance of Neptune DXP - Open Edition. You must also generate private and public keys for the Vault in the terminal to reference in the .env file.

Enable the Vault in the .env file

Enable the Vault and reference the private and public keys in the .env file. The .env file must be in the same folder where you run the Neptune DXP - Open Edition binary from. An example configuration entry in the .env file might be:

VAULT_ENABLED=true
VAULT_PRIVATE_KEY=/Users/<MyUser>/<MyPath>/.keys/vault
VAULT_PUBLIC_KEY=/Users/<MyUser>/<MyPath>/.keys/vault.pem

If you disable the Vault at any time, existing passwords or API tokens continue to reference it. To fully disconnect, remove these references by re-entering the associated credentials in the respective places to which the Vault had access.

Generate public and private keys for the Vault in the terminal

The public/private key pair can be generated from the terminal using standard CLI commands. An example command might be:

ssh-keygen -t rsa -b 4096 -m PEM -f vault
ssh-keygen -f vault.pub -e -m PEM > vault.pem

Paths and file names may vary depending on system setup, but generally the Vault requires a secure public/private key pair referenced in the configuration, with the private key stored safely outside the main Neptune DXP - Open Edition installation directory.

When the Vault is enabled and no AES key is found, it automatically generates a random 256-bit AES key, encrypts it with the public key, and stores the encrypted value in the configuration. All encryption and decryption occur internally, and role-based access control defines who can view or modify secrets while keys remain protected.

Role-based access control

Grant users access to the Vault in the Role tool according to the following permission levels:

None: The user cannot access the Vault in the Cockpit.
Display: The user can view the Vault, preview secrets, and preview generated logs for the Vault in the System Logs tool.
Edit: The user can create, edit, and delete secrets in the Vault and preview generated logs for the Vault in the System Logs tool.

Only admin and global admin users can decrypt secrets, if required.

Protect secrets with value help

If a value for an input field uses a password or legacy encryption, Neptune DXP - Open Edition automatically identifies that the input field is not protected by the Vault. Select the Vault icon in the input field, and, if available, select a secret from the Vault to apply to the input field. Secrets in input fields already protected by the Vault display available secrets for the input field when selecting the Vault icon in the input field.