HashiCorp Vault Secrets Management
There are many strategies for securely providing secrets to a Docker-based service. Some cloud providers or container orchestration services have built-in mechanisms to securely set environment variables with values fetched at runtime. However, in certain scenarios, such as on-premises deployments, these managed options may not be readily available.
If your organization uses HashiCorp Vault to manage secrets in the KV store version 2, you can fetch those secrets dynamically at runtime using Sombra.
HashiCorp Vault provides secure storage for Sombra's sensitive configuration values:
- Vault for Secret Storage: Vault is recommended for securely storing sensitive values like the
JWT_ECDSA_KEY, which is used for signing webhooks and (when using local KMS) deriving content encryption keys. - Independent from AWS KMS: Vault's secret storage is separate from AWS KMS integration. AWS KMS handles content encryption operations, while Vault securely stores configuration values.
- Security Best Practice: Using Vault for storing the
JWT_ECDSA_KEYand other sensitive values provides an additional layer of security compared to environment variables.
Our recommended approach for connecting to Vault is using a sidecar container with the vault-agent. This method allows the Sombra image to focus on core functionality while a separate container, created by HashiCorp, manages authentication to your Vault cluster.
To implement this approach, set the following environment variables:
| Env Var Name | Description | Type | Example |
|---|---|---|---|
ENABLE_VAULT_FETCHER | Set to true to enable Vault integration | boolean | true |
VAULT_AGENT_URI | The URI of the Vault agent (typically a local address when using a sidecar container) | string | http://127.0.0.1:8100 |
The following environment variables can be configured to fetch secrets from Vault:
| Secret Env Var Name | Vault Path Env Var | Vault Version Env Var | Vault Key Name Env Var | Description |
|---|---|---|---|---|
SOMBRA_JWT_ECDSA_KEY | VAULT_PATH_SOMBRA_JWT_ECDSA_KEY | VAULT_VERSION_SOMBRA_JWT_ECDSA_KEY | VAULT_KEY_SOMBRA_JWT_ECDSA_KEY | The JWT signing key used for webhook signatures and JWT operations. Also serves as entropy source for local KMS key derivation when not using AWS KMS |
SOMBRA_TLS_KEY_PASSPHRASE | VAULT_PATH_SOMBRA_TLS_KEY_PASSPHRASE | VAULT_VERSION_SOMBRA_TLS_KEY_PASSPHRASE | VAULT_KEY_SOMBRA_TLS_KEY_PASSPHRASE | An optional password for the TLS certificate |
SOMBRA_TLS_CERT | VAULT_PATH_SOMBRA_TLS_CERT | VAULT_VERSION_SOMBRA_TLS_CERT | VAULT_KEY_SOMBRA_TLS_CERT | The Sombra TLS certificate as a base64-encoded string |
SOMBRA_TLS_KEY | VAULT_PATH_SOMBRA_TLS_KEY | VAULT_VERSION_SOMBRA_TLS_KEY | VAULT_KEY_SOMBRA_TLS_KEY | The Sombra TLS key as a base64-encoded string |
TRUSTED_CLIENT_CA_CERT_ENCODED | VAULT_PATH_TRUSTED_CLIENT_CA_CERT_ENCODED | VAULT_VERSION_TRUSTED_CLIENT_CA_CERT_ENCODED | VAULT_KEY_TRUSTED_CLIENT_CA_CERT_ENCODED | The public CA certificate from a client connecting to the internal Sombra service over mutual TLS. When set, Sombra will enforce that all incoming requests to non-health routes include a client certificate |