Retrieve secrets from Azure Key Vault
Learn how to use Azure Key Vault to store your Retool resource secrets.
Configuring Resources in Retool can require handling sensitive values, such as 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 Azure Key Vault for customers running self-hosted Retool.
Requirements
To use Azure Key Vault with Retool, you need:
- A self-hosted Retool instance on the Enterprise plan.
- Admin permissions for your Retool organization.
- An Azure Key Vault that already stores your secrets.
1. Grant Retool access to Key Vault
In Azure, grant the identity Retool uses list and get access to secrets in your vault. That identity is the managed identity or workload identity on the Retool host, or the app registration if you use service principal authentication. The Key Vault Secrets User role is one way to grant this access.
2. Authenticate to Azure Key Vault
Retool supports two authentication modes. Select Authentication mode when you configure Azure Key Vault in Settings > Secrets Manager.
Credential chain
This mode uses the default Azure credential chain. The Retool backend discovers credentials from the host. You do not enter a client secret in Retool.
Service principal
This mode uses a Microsoft Entra app registration. Retool authenticates with the app's tenant ID, client ID, and client secret. Use this mode when the Retool host cannot use a managed identity or the default credential chain.
To create credentials:
- Create an app registration in Microsoft Entra ID.
- Create a client secret for the app.
- Grant the app list and get access to secrets, as described in Grant Retool access to Key Vault.
In Retool, enter the app's Tenant ID, Client ID, and Client secret. All three fields are required for this mode.
3. Configure Secrets Manager in Retool
Secrets management must be configured for the primary organization, and for any spaces within an organization that need to use secrets.
For multiple deployment instances of Retool, make the same changes to your organization (and spaces within the organization) for each instance in which you want to use secrets.
For each Retool Space, go to Settings > Secrets Manager, select Azure Key Vault, and enter the following settings.
| Setting | Description | Example |
|---|---|---|
| Authentication mode | How Retool authenticates to Azure. Credential chain uses host credentials. Service principal uses an app registration. | |
| Vault URL | The vault URI from the Azure portal Overview page. The URL must use https://. | https://example.vault.azure.net |
| Tenant ID | The Microsoft Entra directory ID. | 00000000-0000-0000-0000-000000000000 |
| Client ID | The application (client) ID of the app registration or managed identity. | 00000000-0000-0000-0000-000000000000 |
| Client secret | The client secret from the Microsoft Entra app registration. | |
| Retool Namespace | Prefix prepended to secret names. Use letters, numbers, and hyphens only. | retool- |
Click Test connection to confirm Retool can connect to Azure Key Vault, then click Save.
Namespace
The Retool Namespace field is a prefix that Retool adds when it looks up secrets, and strips when it lists them. For example, if your Retool-facing secrets in Azure Key Vault start with retool-, set the namespace to retool- as well.
If you have multiple Retool instances, use the namespace to resolve the same secret name in a resource configuration to different secrets in your vault. Setting the namespace is recommended if you use Protected Resources.
For example, if you have development and production instances, you might use the following naming convention for secrets in your vault:
retool-dev-db-user
retool-dev-db-password
retool-prod-db-user
retool-prod-db-password
On your Retool development instance, set the namespace to retool-dev-. On your production instance, set it to retool-prod-. You can then reference secrets for either instance using {{ secrets['db-user'] }} and {{ secrets['db-password'] }}, and Retool fetches the appropriate secret at runtime.
4. Use secrets in resources
After you save your Secrets Manager configuration in Retool, if you granted the identity list access, available secrets appear on Settings > Secrets Manager.
You can reference them in resource configurations using template syntax, such as {{ secrets.name }} or {{ secrets['name'] }}, either by copying values from the Reference column or with autocomplete on the resource configuration page.
If you have multiple Secrets Manager configurations, include the configuration name. The default name for Azure Key Vault is azure:
{{ secrets['azure']['db-password'] }}
You can access JSON keys with {{ secrets.name.key }} or {{ secrets['name']['key'] }}. You can access arbitrary levels of nested keys in your secrets. Keys do 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 Azure Key Vault, Retool automatically reads updated values from your secrets manager. You do not 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.
Scoped secrets
Retool does not support scoped secrets for Azure Key Vault.
Security considerations
Any user that can configure resources can use secrets in resources. This could lead to inappropriate uses of secrets. Grant the Retool identity only the Key Vault access it needs, and restrict which users can configure resources.