Skip to main content

Retrieve secrets from AWS Secrets Manager

Learn how to use AWS Secrets Manager to store your Retool resource secrets.

Configuring Resources in Retool can require handling sensitive values, e.g. database passwords or API keys. Retool is SOC 2 Type 2 compliant, and most customers store these values with Retool. However, depending on your security posture, you may want to store secret values externally, rather than encrypted in Retool’s database.

To support this, Retool supports retrieving secrets from AWS Secrets Manager for customers running self-hosted Retool.

Requirements​

To use the AWS Secrets Manager with Retool, you need:

  • A self-hosted Retool deployment.
  • Have admin permissions for your Retool organization.
  • Already have AWS Secrets Manager configured to store your secrets.

1. Create IAM policy for Retool​

In AWS, create an IAM policy to grant Retool access to your secrets. Retool recommends you store secrets under a retool/ namespace for easier access control. The following is an example policy you might use.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "secretsmanager:GetSecretValue",
        "secretsmanager:DescribeSecret"
      ],
      "Resource": ["arn:aws:secretsmanager:Region:AccountId:secret:retool/*"]
    },
    {
      "Effect": "Allow",
      "Action": ["secretsmanager:ListSecrets"],
      "Resource": "*"
    }
  ]
}

2. Attach IAM policy to your principal​

Next, attach the policy to the principal associated with your Retool workload. For example, if you deploy Retool on EC2, attach this policy to the instance profile for the EC2 instance.

3. Configure Secrets Manager in Retool​

For each instance, visit Settings > Secrets Manager and enter the Region associated with your AWS Secrets Manager instance and an optional Namespace (details below). Click Test connection to confirm Retool can connect to your AWS Secrets Manager, then click Save.

Namespace​

The Namespace field is a value that will be prepended to any secret names Retool looks up. For example, if all your Retool-facing secrets in AWS Secrets Manager start with retool/, you might set the namespace to be retool/ as well. If you have multiple Retool instances, you can use this to resolve the same secret name in a Resource configuration to different secrets in your AWS account. For this reason, setting the namespace is recommended if you use Protected Resources.

For example, if you have a "dev" instance and a "prod" instance, you might use the following naming convention for secrets in your AWS account:

// Secrets for your dev instance
retool/dev/db_user
retool/dev/db_password

// Secrets for your prod instance
retool/prod/db_user
retool/prod/db_password

On your Retool development instance, you would then set the namespace to retool/dev, and on your production instance to retool/prod. You can then reference secrets on both instances using {{ secrets.db_user }} and {{ secrets.db_password }}, and Retool will fetch the appropriate secret for the instance at runtime.

4. Use secrets in resources​

After you save your Secrets Manager configuration in Retool, if you granted Retool the ListSecrets permission, available secrets appear on Settings > Secrets Manager.

You can reference them in Resource configurations using template syntax, e.g. {{ secrets.name }} or {{ secrets['name'] }}, either by copying values from the Reference column, or with autocomplete on the Resource configuration page.

You can access JSON keys with {{ secrets.name.key }} or {{ secrets['name']['key'] }}. You can access arbitrary levels of nested keys in your secrets. Note that keys will not autocomplete.

If your secret values are not quoted, you may need to wrap the template string in quotes in resource configurations.

For example, given an unquoted secret (secret-value) for the key key_name, you'd use "{{ secrets.key_name.key }}". Given a quoted secret ("secret-value"), you'd use {{ secrets.key_name.key }}.

When you rotate secrets in AWS, Retool automatically reads updated values from your secrets manager. This means you don't need to restart your Retool instance or update any configuration when rotating secrets.

Time to live (TTL) setting​

Retool caches secrets it fetches with a configurable time to live. This reduces API calls to your secrets manager, which keeps queries fast and reduces costs. However, this means secrets may become temporarily "stale" when they are rotated. You can update Cache TTL (ms) in Settings > Secrets Manager to minimize failed queries in the event that a secret is rotated.

Security considerations​

Any user that can configure resources can use secrets in resources. This could lead to inappropriate uses of secrets. You can restrict the ListSecrets permissions in AWS to mitigate the risk.