Skip to main content
Flipt v2 supports external secrets management, allowing you to store sensitive configuration data like API keys, tokens, and certificates outside of your main configuration files. This enhances security by centralizing secret management and reducing the risk of accidentally exposing sensitive data.

​
Why Use External Secrets?

Instead of storing sensitive values directly in Flipt configuration files, external secrets provide:
  • Enhanced Security: Sensitive data is stored in dedicated secret management systems with proper access controls
  • Centralized Management: All secrets managed in one place with audit trails and access policies
  • Environment Separation: Different secrets for development, staging, and production environments
  • Rotation Support: Easy secret rotation without updating configuration files (coming soon)
  • Access Control: Fine-grained permissions for who can access which secrets

​
Supported Providers

Flipt supports multiple secret providers to fit different deployment scenarios:
We’re working on adding support for more secret providers, including AWS Secrets Manager, Azure Key Vault, and Google Cloud Secret Manager.

File Provider

Store secrets in local files - ideal for development and simple deployments

HashiCorp Vault

Enterprise-grade secret management with advanced authentication and access controls

​
Configuration Overview

Enable secrets management by configuring providers in your Flipt configuration: 
secrets:
  providers:
    # Multiple providers can be configured
    file:
      enabled: true
      base_path: "/etc/flipt/secrets"
    vault:
      enabled: true
      address: "https://vault.company.com"
      auth_method: "token"

​
File Provider

The file provider is the simplest option, storing each secret as an individual file in the configured directory.

​
Configuration

secrets:
  providers:
    file:
      enabled: true
      base_path: "/etc/flipt/secrets" # Default: /etc/flipt/secrets

​
Usage

Create individual secret files in the configured directory. Each file becomes a secret where the filename is the key and the file contents are the value: 
# Create individual secret files
echo "sk-1234567890abcdef" > /etc/flipt/secrets/api-key
echo "your-csrf-secret-key" > /etc/flipt/secrets/csrf-key
echo "-----BEGIN CERTIFICATE-----..." > /etc/flipt/secrets/tls-cert
echo "-----BEGIN PRIVATE KEY-----..." > /etc/flipt/secrets/tls-key
Each secret is stored as a separate file. The filename becomes the secret key, and the file contents become the secret value.

​
HashiCorp Vault Provider

Vault provides enterprise-grade secret management with advanced features like dynamic secrets, encryption as a service, and detailed audit logs.

​
Basic Configuration

secrets:
  providers:
    vault:
      enabled: true
      address: "https://vault.company.com"
      auth_method: "token"
      token: "hvs.your_vault_token"
      mount: "secret" # Default: secret

​
Authentication Methods

​
Token Authentication

Best for development and testing: 
vault:
  enabled: true
  address: "https://vault.company.com"
  auth_method: "token"
  token: "hvs.your_vault_token"

​
Kubernetes Authentication

Ideal for Kubernetes deployments: 
vault:
  enabled: true
  address: "https://vault.company.com"
  auth_method: "kubernetes"
  role: "flipt-role"
  mount: "secret"

​
AppRole Authentication

Good for automated systems and CI/CD: 
vault:
  enabled: true
  address: "https://vault.company.com"
  auth_method: "approle"
  role: "flipt-role"
  mount: "secret"

​
Environment Variables

Avoid storing sensitive values in configuration files by using environment variables: 
export FLIPT_SECRETS_PROVIDERS_VAULT_TOKEN="hvs.your_vault_token"
export FLIPT_SECRETS_PROVIDERS_VAULT_ROLE_ID="your_role_id"
export FLIPT_SECRETS_PROVIDERS_VAULT_SECRET_ID="your_secret_id"

​
Using Secrets in Configuration

Secrets can be referenced throughout your Flipt v2 configuration using the secret reference syntax. Secret references must always include the provider specification.

​
Secret Reference Syntax

Secret references use the format ${secret:provider:key} where:
  • provider is the name of the configured secrets provider (e.g., file, vault)
  • key is the name of the secret to retrieve

​
File Provider Examples

server:
  cert_file: ${secret:file:tls-cert} # References /etc/flipt/secrets/tls-cert
  cert_key: ${secret:file:tls-key} # References /etc/flipt/secrets/tls-key

authentication:
  session:
    csrf:
      key: ${secret:file:csrf-key} # References /etc/flipt/secrets/csrf-key

​
Vault Provider Examples

authentication:
  methods:
    oidc:
      providers:
        google:
          client_id: ${secret:vault:auth/oidc:client_id}
          client_secret: ${secret:vault:auth/oidc:client_secret}
        github:
          client_id: ${secret:vault:auth/github:client_id}
          client_secret: ${secret:vault:auth/github:client_secret}

​
Combined with Environment Variables

You can combine secret references with environment variables in the same configuration: 
authentication:
  methods:
    oidc:
      providers:
        google:
          issuer_url: ${env:OIDC_ISSUER_URL} # Environment variable
          client_id: ${secret:vault:auth/oidc:client_id} # Secret reference
          client_secret: ${secret:vault:auth/oidc:client_secret} # Secret reference
          redirect_address: ${env:FLIPT_BASE_URL} # Environment variable

​
Structured Secret References

For more complex scenarios, you can also use the structured key_ref format in configuration sections that support it: 
storage:
  default:
    signature:
      enabled: true
      key_ref:
        provider: "vault" # Secrets provider name
        path: "flipt/signing-key" # Path to secret in provider
        key: "private_key" # Key name within the secret