Overview#

Flipt's secrets management framework enables secure, flexible, and centralized handling of sensitive configuration values. It supports a multi-provider architecture, allowing secrets to be sourced from file-based stores or external systems like HashiCorp Vault, AWS Secrets Manager, Google Cloud Secret Manager, and Azure Key Vault. The framework introduces a unified reference syntax for secrets and environment variables, improving clarity and security in configuration files.

Multi-Provider Architecture#

Flipt supports multiple secret providers, including file-based, Vault, AWS Secrets Manager, GCP Secret Manager, and Azure Key Vault providers. This architecture allows you to reference secrets from different backends within a single configuration file, enabling advanced use cases such as separating operational secrets from application secrets or integrating with enterprise-grade secret stores. Providers are configured under the secrets.providers section in your Flipt configuration.

Secret Reference Syntax#

Flipt uses a new, explicit syntax for referencing secrets and environment variables in configuration files:

• Secret Reference:
  ${secret:provider:path:key}
  This syntax retrieves a secret named key from the specified provider at the given path. For simple cases, you can use ${secret:key} to reference a secret from the default provider.

• Environment Variable Reference:
  ${env:VAR}
  This syntax injects the value of the environment variable VAR into the configuration.

Examples:

db:
  password: ${secret:db-provider:credentials:password}
api:
  key: ${env:API_KEY}

Source

Configuration Options#

File-Based Provider#

The file-based provider reads secrets from a local YAML or JSON file. Example configuration:

secrets:
  providers:
    file:
      enabled: true
      base_path: /etc/flipt/secrets.yml

Example secrets file (/etc/flipt/secrets.yml):

credentials:
  password: supersecret
  api_key: abc123

Vault Provider#

The Vault provider integrates with HashiCorp Vault to retrieve secrets at runtime. Example configuration:

secrets:
  providers:
    vault:
      enabled: true
      address: http://vault:8200
      auth_method: token
      token: ${env:VAULT_TOKEN}
      mount: secret

You can also configure the Vault provider using environment variables:

FLIPT_SECRETS_PROVIDERS_VAULT_ENABLED=true
FLIPT_SECRETS_PROVIDERS_VAULT_ADDRESS=http://vault:8200
FLIPT_SECRETS_PROVIDERS_VAULT_AUTH_METHOD=token
FLIPT_SECRETS_PROVIDERS_VAULT_TOKEN=your-vault-token
FLIPT_SECRETS_PROVIDERS_VAULT_MOUNT=secret

Source

GCP Secret Manager Provider#

The GCP Secret Manager provider integrates with Google Cloud Secret Manager to retrieve secrets at runtime. Example configuration:

secrets:
  providers:
    gcp:
      enabled: true
      project: my-gcp-project
      credentials: /path/to/service-account.json # optional, defaults to ADC

The provider supports two authentication methods:

• Application Default Credentials (ADC): If credentials is not specified, the provider uses ADC to authenticate with GCP.
• Service Account JSON: Provide a path to a service account JSON file using the credentials field.

You can also configure the GCP provider using environment variables:

FLIPT_SECRETS_PROVIDERS_GCP_ENABLED=true
FLIPT_SECRETS_PROVIDERS_GCP_PROJECT=my-gcp-project
FLIPT_SECRETS_PROVIDERS_GCP_CREDENTIALS=/path/to/service-account.json

AWS Secrets Manager Provider#

The AWS Secrets Manager provider integrates with AWS Secrets Manager to retrieve secrets at runtime. Example configuration:

secrets:
  providers:
    aws:
      enabled: true
      region: us-east-1
      endpoint_url: "" # optional, for testing with LocalStack

The provider uses AWS SDK v2 and requires appropriate AWS credentials, which can be provided through:

• IAM role (recommended for EC2/ECS/Lambda deployments)
• AWS environment variables (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_DEFAULT_REGION)
• AWS credentials file (~/.aws/credentials)

The region field is required and specifies which AWS region to retrieve secrets from. The endpoint_url field is optional and primarily used for testing with LocalStack or other AWS-compatible services.

You can also configure the AWS provider using environment variables:

FLIPT_SECRETS_PROVIDERS_AWS_ENABLED=true
FLIPT_SECRETS_PROVIDERS_AWS_REGION=us-east-1
FLIPT_SECRETS_PROVIDERS_AWS_ENDPOINT_URL=http://localhost:4566

Secret references use the format ${secret:aws:secret-name}, where secret-name is the name of the secret in AWS Secrets Manager.

Azure Key Vault Provider#

The Azure Key Vault provider integrates with Azure Key Vault to retrieve secrets at runtime. It uses the Azure SDK for Go (azidentity + azsecrets) with DefaultAzureCredential for flexible authentication. Example configuration:

secrets:
  providers:
    azure:
      enabled: true
      vault_url: "https://your-vault-name.vault.azure.net"

The provider uses DefaultAzureCredential for authentication, which supports multiple authentication methods:

• Managed Identity: Recommended for Azure VM, App Service, Container Instances, and other Azure compute services
• Environment Variables: AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_CLIENT_SECRET
• Azure CLI: Uses credentials from az login
• Other credential sources: Service principal, workload identity, etc.

The vault_url field is required and specifies the URL of your Azure Key Vault (format: https://<vault-name>.vault.azure.net).

You can also configure the Azure provider using environment variables:

FLIPT_SECRETS_PROVIDERS_AZURE_ENABLED=true
FLIPT_SECRETS_PROVIDERS_AZURE_VAULT_URL=https://your-vault-name.vault.azure.net

You can reference the Vault URL from an environment variable:

secrets:
  providers:
    azure:
      enabled: true
      vault_url: ${env:AZURE_KEYVAULT_VAULT_URL}

Secret references use the format ${secret:azure:secret-name}, where secret-name is the name of the secret in Azure Key Vault.

Emulator Support:
For integration testing, you can use the AZURE_KEYVAULT_EMULATOR environment variable to connect to emulator services like Lowkey Vault. When this variable is set, the provider skips TLS verification and uses a fake credential for authentication.

Provider Setup#

To enable a provider, set its enabled flag to true and provide the necessary configuration options. For the file provider, specify the base_path to your secrets file. For the Vault provider, specify the Vault server address, authentication method, token, and mount path. For the AWS provider, specify the AWS region and optionally a custom endpoint URL for testing. For the GCP provider, specify the GCP project ID and optionally a service account credentials file. For the Azure provider, specify the Azure Key Vault URL. You can use environment variables for sensitive values by referencing them with ${env:VAR}.

Secret Retrieval and Configuration Integration#

When Flipt loads its configuration, it resolves all secret and environment variable references at runtime. This means you can safely commit configuration files with secret references, keeping sensitive values out of version control. For example, you can configure commit signing keys, API keys, or database credentials to be retrieved from Vault, AWS Secrets Manager, GCP Secret Manager, Azure Key Vault, or a local secrets file.

Secret references are also supported in OIDC provider configuration, allowing you to securely provide sensitive values such as client_id and client_secret using the ${secret:...} syntax.

Example: OIDC Provider with Secret References

auth:
  oidc:
    providers:
      - name: example
        client_id: ${secret:oidc-client-id}
        client_secret: ${secret:oidc-client-secret}
        issuer: https://accounts.example.com

Example: Commit Signing with Vault

storage:
  git:
    signing:
      enabled: true
      private_key: ${secret:vault:flipt/signing-key:private_key}

Source
Source

Migration Notes#

Old Syntax#

Previously, Flipt supported referencing environment variables directly in configuration files using ${ENV_VAR}. This approach did not distinguish between environment variables and secrets, and all references were resolved from the environment.

New Syntax#

The new syntax introduces explicit references:

• Use ${env:VAR} for environment variables.
• Use ${secret:key} or ${secret:provider:path:key} for secrets.

Migration Path:

• Update all ${ENV_VAR} references to ${env:ENV_VAR}.
• Move secrets to a provider (file, Vault, AWS, GCP, or Azure) and reference them using the ${secret:...} syntax.
• Flipt provides deprecation warnings for the legacy ${ENV_VAR} syntax and maintains backward compatibility during the transition period.
  Source

Comparison Table:

Common Use Cases#

1. Database Credentials from File Provider#

secrets:
  providers:
    file:
      enabled: true
      base_path: /etc/flipt/secrets.yml

db:
  url: postgres://postgres:${secret:file:credentials:password}@localhost:5432/flipt

2. API Key from Environment Variable#

api:
  key: ${env:API_KEY}

3. Commit Signing Key from Vault#

secrets:
  providers:
    vault:
      enabled: true
      address: http://vault:8200
      auth_method: token
      token: ${env:VAULT_TOKEN}
      mount: secret

storage:
  git:
    signing:
      enabled: true
      private_key: ${secret:vault:flipt/signing-key:private_key}

4. Commit Signing Key from AWS Secrets Manager#

secrets:
  providers:
    aws:
      enabled: true
      region: us-east-1

storage:
  git:
    signing:
      enabled: true
      private_key: ${secret:aws:flipt-signing-key:value}

5. Commit Signing Key from GCP Secret Manager#

secrets:
  providers:
    gcp:
      enabled: true
      project: my-gcp-project

storage:
  git:
    signing:
      enabled: true
      private_key: ${secret:gcp:flipt-signing-key:value}

6. Commit Signing Key from Azure Key Vault#

secrets:
  providers:
    azure:
      enabled: true
      vault_url: "https://my-vault.vault.azure.net"

storage:
  git:
    signing:
      enabled: true
      private_key: ${secret:azure:flipt-signing-key:value}

7. Multiple Providers#

secrets:
  providers:
    file:
      enabled: true
      base_path: /etc/flipt/secrets.yml
    vault:
      enabled: true
      address: http://vault:8200
      auth_method: token
      token: ${env:VAULT_TOKEN}
      mount: secret
    aws:
      enabled: true
      region: us-east-1
    gcp:
      enabled: true
      project: my-gcp-project
    azure:
      enabled: true
      vault_url: "https://my-vault.vault.azure.net"

db:
  url: postgres://postgres:${secret:file:credentials:password}@localhost:5432/flipt
api:
  key: ${secret:vault:api/keys:service_key}
signing:
  private_key: ${secret:aws:signing-key:value}
monitoring:
  token: ${secret:gcp:monitoring-token:value}
analytics:
  api_key: ${secret:azure:analytics-key:value}

Source

Best Practices#

• Store secrets in providers, not directly in configuration files.
• Use environment variables for provider configuration and tokens.
• Reference secrets using the explicit ${secret:...} syntax to avoid leaking sensitive data.
• Use the Vault, AWS, GCP, or Azure provider for production and the file provider for local development or testing.
• Monitor deprecation warnings and update legacy ${ENV_VAR} syntax to the new format.

References#

• Flipt PR: V2 secrets
• Flipt Issue: Config secret references and migration
• Flipt PR: Add GCP Secret Manager provider
• Flipt PR: Add AWS Secrets Manager provider
• Flipt PR: Add Azure Key Vault provider