External secret vaults
MintPress stores secrets in its bundled secret vault. To keep some secrets in a vault of your own, a superuser registers that vault with MintPress once, and projects, environments, assets, templates and template versions then use it by setting vault.code to the vault's code. The vault's address and service credentials are kept with the registration, so they are entered once and never appear in settings.
After following this guide you should know how to:
- register, edit and delete an external secret vault
- assign an external secret vault to a project, environment, asset or template
- decide who can use an external secret vault's service credentials
- give the changes under a project, environment or asset their own runner credential
The bundled secret vault cannot be turned off. It is always the global secret vault, so every level that does not set vault.code uses it.
Register an external secret vault
Superusers manage external secret vaults in the Vault settings section of the system configuration page, with the MintPress CLI's mintpress admin external-vaults commands, or through the /api/admin/external_vaults API (see the admin operations API). Each vault has:
| Field | Description |
|---|---|
code | How settings refer to the vault. Lowercase letters, numbers and underscores, up to 50 characters. It cannot be changed once the vault is created, and bundled is reserved for the bundled secret vault. |
name | The name users see when they choose a vault and in error messages. |
address | The vault's address, including the port, for example https://vault.example.com:8200. It cannot be the bundled secret vault's address. Each address and namespace can be registered once. |
auth_method | How MintPress signs in to the vault: token, userpass or ldap. |
token | The service token, for token authentication. |
username | The service username, for userpass or ldap authentication. |
password | The service password, for userpass or ldap authentication. |
client_options | A JSON object of vault client options, such as namespace, ssl_verify, ssl_ca_cert or ssl_timeout. The keys address, token, username, password, auth_method and any key starting with proxy_ are dropped when the vault is saved. Set ssl_verify here to turn off certificate verification for this vault. |
The service credentials must be the values themselves, not secret-vault:// references. They are stored encrypted and are never returned: the GUI and the API show only whether each one is configured. When editing a vault, leave a credential blank to keep the stored one.
MintPress signs in to the vault with the credentials before saving. If the vault cannot be reached or refuses the credentials, the error says so and nothing is saved.
A vault cannot be deleted while a settings level or an unfinished change uses it, or while a runner credential for it is tagged on a node. Deleting a vault also deletes the credentials users registered for it and its untagged runner credentials.
Assign a vault to a project, environment, asset or template
Set vault.code in the settings of the project, environment, asset, template or template version. Every level below it inherits the vault, unless it sets its own vault.code. Set vault.code to bundled to switch a level back to the bundled secret vault under a parent that uses an external one.
Set vault.mount_path and vault.use_mint_encryption with it. Otherwise the level inherits the bundled secret vault's mount path and encryption setting, which are unlikely to match your vault. For example:
{
"vault": {
"code": "team_vault",
"mount_path": "team-a/data",
"use_mint_encryption": false
}
}
Many environments can share one external vault, each with its own mount_path. Users register one credential for the vault, and it applies to all of them. See secret vault credentials.
A code that is not registered is rejected when the settings are saved. Every signed-in user can see every registered vault's code and name. Its address is shown only to superusers.
Who can use a vault's service credentials
Any user who can edit a level's settings can assign any registered vault to it, along with any mount path. Unless a runner credential is tagged on them, changes on that level then read and write the vault with its service credentials. A vault's service credentials are therefore shared across every level assigned to it: a user who can edit project A's settings can point project A at the vault and mount path project B uses, and project A's changes can then read project B's secrets.
If projects must not share secrets, tag every project that uses the vault with a runner credential that reaches only its own mounts. Project A's changes then sign in with project A's credential, and pointing project A at project B's mount gets an access error from the vault rather than project B's secrets. A project left untagged still uses the default credential, which for the bundled vault reaches every mount any level assigns, so it can read the other projects' secrets.
Runner credentials
A runner credential is the credential runners use to sign in to one secret vault. Superusers tag it on the projects, environments and assets whose changes should use it. They manage runner credentials in the Vault settings section of the system configuration page, with the MintPress CLI's mintpress admin runner-credentials commands, or through the /api/admin/vault_runner_credentials API (see the admin operations API).
There are two kinds:
- Managed, for the bundled secret vault only. You choose the mount paths it reaches, and MintPress writes a vault policy for them and creates, renews and replaces the token itself. You never see or enter the token.
- Supplied, for any vault. You enter a token, or a username and password, issued by the vault's administrator, and the vault's own policies decide what it reaches. MintPress signs in with it before saving, and saves nothing if the vault refuses it.
The credentials are stored encrypted and never returned. A credential's code is unique within its vault, and its code, vault and kind cannot be changed later.
How runners choose a credential
For each change, MintPress looks at the vault the change's settings assign and the tags on the change's node and every node above it:
- If a credential for that vault is tagged on the node or above it, the change uses the deepest one. A credential for another vault tagged deeper does not hide it.
- If any runner credential, for any vault, is tagged on the node or above it, but none of them is for the change's vault, the change is rejected when it is created or retried, with a message naming the vault and the node, and refreshing an asset's template actions there fails. Tag a credential for that vault to fix it.
- Otherwise the change uses the default: the bundled secret vault's runner account, or an external vault's service credentials.
Each node can carry one runner credential for each vault. Secret references that the system configuration supplies keep using the default, whatever is tagged.
MintPress warns about any node under a credential's tags whose vault has no credential tagged on it or above it, because the changes there would be rejected. The GUI shows the warning on the credential, and the API returns it with the credential. It reflects the current settings and the active template version of each asset.
Retrying a change uses the credentials tagged when the retry starts.