Connect HashiCorp Vault

NocoDB reads secrets from one KV version 2 mount of your HashiCorp Vault. It authenticates with an AppRole (a role ID and a secret ID), or with a token you supply. Vault Community, Vault Enterprise and HCP Vault all work.

Before you begin

• The Enterprise Vaults add-on, on the NocoDB Enterprise plan or a Self-hosted Enterprise license. No plan includes it. See Turning on Enterprise Vaults.
• Workspace Owner for a workspace vault, or Org Admin for an organization vault. See Permissions.
• The vault CLI, signed in with permission to write policies, enable auth methods and write secrets.
• A Vault address NocoDB can reach. NocoDB Cloud needs a public https:// address. See Network.

1. Write a policy

NocoDB needs read on the secrets it will resolve, and nothing else. For secrets under prod/ on a KV v2 mount called secret:

# nocodb.hcl
path "secret/data/prod/*" {
  capabilities = ["read"]
}

KV v2 stores data under <mount>/data/<path>, so the policy names secret/data/… even though you will reference the secret as prod/….

vault policy write nocodb nocodb.hcl

The connection test calls auth/token/lookup-self, which Vault's default policy allows. Keep the default policy on the token; the AppRole below attaches it unless you set token_no_default_policy.

2. Create an AppRole

vault auth enable approle
vault write auth/approle/role/nocodb \
    token_policies="nocodb" \
    token_ttl=1h \
    token_max_ttl=4h \
    secret_id_ttl=0 \
    secret_id_num_uses=0

vault read -field=role_id auth/approle/role/nocodb/role-id
vault write -f -field=secret_id auth/approle/role/nocodb/secret-id

Copy the role ID and the secret ID. Vault shows the secret ID once.

NocoDB logs in with the pair and caches the resulting token for its lease, up to 10 minutes, sharing one login across all connections that use the vault. When Vault answers 403 to a token older than a minute, NocoDB logs in again once before reporting the error, so a short token_ttl is fine. A token with a use limit (token_num_uses on the role) is never cached or shared, so every read logs in again; leave it at 0 unless you need it.

3. Store a secret

vault kv put secret/prod/db username=app password=s3cret

A KV v2 secret is a JSON document, so a reference must name the field inside it: username or password here. A secret with a single value still needs a field name, for example value.

4. Connect the vault in NocoDB

Click Connect a vault on the banner at the top of the workspace Integrations page, or open Vaults in the Admin Panel for an organization-scoped vault. Choose HashiCorp Vault, click Next, and fill in:

Click Next and run the test on the Verify step. With AppRole, NocoDB makes a fresh login and then looks up the token; with a token, it looks up the token. It then checks the mount path: a KV version 1 engine, or no engine at that path, fails the test. A green result means the address, the namespace and the credentials are right. The mount check needs Vault to answer, so a policy narrow enough to hide the mount lets the test pass, and the test does not read a secret: a policy that does not cover your secrets shows only when a reference is first read. Then save.

Reference a secret

Reference a field of the KV v2 secret from a credential field as:

secrets.hcProd["prod/db"].password

The part in brackets is the secret's path under the mount. It is not the <namespace>/<mount>/data/… path the HCP UI shows. The last part is the field inside the secret, and it is required. NocoDB reads the latest version. See Use a vault reference.

Network

• NocoDB Cloud reaches your Vault over the public internet, so the address must be https:// and must resolve to a public address. A private or link-local address is refused with a message saying so. Allow NocoDB Cloud through your firewall.
• Self-hosted NocoDB may use http:// and private addresses. A private address is still refused until you set NC_ALLOW_LOCAL_VAULTS=true on the NocoDB server, which is the same guard the other outbound features use.
• A Vault behind a private CA needs that CA added with NODE_EXTRA_CA_CERTS on the NocoDB server. On Cloud, use a certificate from a public CA.
• Point the address at Vault's API directly. NocoDB refuses a proxy that redirects, rather than following it.
• A performance standby that cannot serve the request, or a node in another cluster, is reported as such. Point the address at the primary cluster, or at a load balancer in front of it.

Rotate the credentials

To rotate an AppRole secret ID:

1. In Vault, generate a new secret ID: vault write -f -field=secret_id auth/approle/role/nocodb/secret-id.
2. In NocoDB, open Edit vault and re-enter every field: the vault address, the KV v2 mount, the namespace if you use one, the role ID and the new secret ID. Click Verify, then Save.
3. Destroy the old secret ID in Vault.

To rotate a token, create the new token, enter it with the other fields in Edit vault, save, and then revoke the old token. See Rotating a vault's credentials.

Common errors

For errors shared by every provider, see Vaults troubleshooting.

Related

• Enterprise Vaults overview
• Use a vault reference
• Vaults troubleshooting