Connect AWS Secrets Manager

NocoDB reads secrets from AWS Secrets Manager with an IAM user access key pair (an access key ID and a secret access key) plus a region. This page takes you from an empty AWS account to a working vault: three screens in AWS, then one in NocoDB.

There is no role assumption and no identity provider involved, so nothing on the AWS side depends on where NocoDB runs. The same steps work on NocoDB Cloud and on a self-hosted deployment that AWS cannot reach.

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.
• In AWS, permission to create IAM policies, IAM users and Secrets Manager secrets.

1. Create the permissions policy

In the AWS console, go to IAM → Policies → Create policy and switch to the JSON tab. Paste the following, replacing <REGION> and <ACCOUNT_ID> with your own values.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "ReadVaultSecrets",
      "Effect": "Allow",
      "Action": "secretsmanager:GetSecretValue",
      "Resource": "arn:aws:secretsmanager:<REGION>:<ACCOUNT_ID>:secret:nocodb/*"
    },
    {
      "Sid": "ConnectionTestOnly",
      "Effect": "Allow",
      "Action": "secretsmanager:ListSecrets",
      "Resource": "*"
    }
  ]
}

Continue through the wizard and name the policy NocoDBVaultRead. NocoDB calls only these two actions.

Why there are two statements

NocoDB calls ListSecrets in two places:

• The connection test. No secret has been named yet, so there is nothing to scope the call to. Listing confirms that the credentials work and that the region name exists. A valid region that is the wrong one still passes. It shows only when a reference is read: "No such secret in this region…".
• Secret-name suggestions. When someone allowed to use the vault types a reference, the secret names the call returns are offered as suggestions, up to 500.

ListSecrets returns secret names and metadata only, never a secret's value. It exposes your inventory of secret names, not any credential. Because it cannot be scoped, the suggestions can include names outside the nocodb/ prefix. Reading values stays restricted to the nocodb/* prefix by the first statement, so a suggested name outside it cannot be read. Field names inside a secret are suggested by reading that secret, so they too come only from secrets the first statement allows.

Scope the read statement deliberately

The Resource on the first statement decides which secrets NocoDB can read. Using secret:* there would let NocoDB read every secret in the account. Keep it at a prefix such as nocodb/*, which is why step 3 names the secret that way.

If the secret is encrypted with a customer-managed KMS key, add a third statement allowing kms:Decrypt on that key's ARN. With the default aws/secretsmanager key, nothing extra is needed.

2. Create the IAM user and its access key

Go to IAM → Users → Create user.

1. User name: nocodb-vault-reader.
2. Leave Provide user access to the AWS Management Console cleared. This identity never signs in.
3. Click Next, choose Attach policies directly, select NocoDBVaultRead, and create the user.

Then open the user, go to the Security credentials tab and click Create access key.

1. Use case: Third-party service.
2. Select the confirmation, click Next, then Create access key.
3. Copy both values now. AWS shows the secret access key exactly once. If you lose it, create a new key; there is no way to recover it.

You end up with two values:

3. Store a secret

Go to Secrets Manager → Store a new secret, in the same region as the policy.

1. Secret type: Other type of secret.
2. On the Key/value tab, add the fields the connection needs, for example username with your database user and password with your database password.
3. Leave the encryption key as aws/secretsmanager.
4. Click Next and name the secret nocodb/prod/db/creds. The nocodb/ prefix is what the policy in step 1 allows.
5. Click through the remaining steps and Store.

A key/value secret holds several fields, so a reference to it must name one of them. A plain-text secret holds a single value and needs no field.

4. Connect the vault in NocoDB

Click Connect a vault on the banner at the top of the workspace Integrations page. To connect an organization-scoped vault instead, open Vaults in the Admin Panel and start from there.

The Connect a secrets provider wizard has three steps.

Provider. Choose AWS Secrets Manager.

Configure. Fill in:

Verify. Run the test. It makes a real ListSecrets call against AWS with the credentials you entered, so a green result means the credentials and the listing permission are correct. Read access to a secret is checked the first time a reference to it is resolved, for example by Test connection on a database connection. This step also repeats who can use the vault, with Change to go back and adjust it. The vault cannot be saved until the test passes. Then save.

Reference a secret

Reference a field of the AWS secret from a credential field as:

secrets.awsProd["nocodb/prod/db/creds"].password

The part in brackets is the secret's name, and the last part is the field inside it. Leave out the field for a plain-text secret. A secret in another AWS account is referenced by its full ARN. As you type, NocoDB suggests the vault's secret names and then the fields inside the chosen secret. See Use a vault reference.

Rotate the access key

Rotate the AWS key first, then update the vault:

1. In AWS, create a second access key for nocodb-vault-reader.
2. In NocoDB, open Edit vault and re-enter Region, Access key ID and Secret access key with the new key. Click Verify, then Save.
3. Once the test passes, deactivate and then delete the old key in AWS.

See Rotating a vault's credentials for what NocoDB does with the vault's status and cache.

Good to know

• One key, many connections. The number of standing credentials drops from one per integration to one per vault, and rotation of the database password itself lives in AWS rather than in NocoDB.
• Least privilege matters here. The access key is long-lived, so keep the read statement's Resource narrow and give this IAM user nothing else.
• Prefix your secrets consistently. The policy's prefix keeps NocoDB out of the rest of the account's secrets, and it only works if new secrets are named to match.
• Self-hosted NocoDB reaches AWS outbound only. There are no inbound rules to open.

Common errors

The connection test only lists secrets, so it can return the signature, credentials, listing and missing-field messages. The other messages appear when a reference is read.

For errors shared by every provider, see Vaults troubleshooting.

Related

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