Secrets - Flipt

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:

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

AWS Secrets Manager

Retrieve secrets from AWS Secrets Manager using standard AWS credentials

GCP Secret Manager

Retrieve secrets from Google Cloud Secret Manager with Application Default Credentials or service account keys

Azure Key Vault

Retrieve secrets from Azure Key Vault using Azure identity credentials

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"
    aws:
      enabled: true
    gcp:
      enabled: true
      project: "my-gcp-project"
    azure:
      enabled: true
      vault_url: "https://my-vault.vault.azure.net/"

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"

AWS Secrets Manager Provider

The AWS Secrets Manager provider retrieves secrets stored in AWS Secrets Manager. It uses the AWS SDK for Go v2, which automatically resolves credentials from the standard AWS credential chain.

Configuration

secrets:
  providers:
    aws:
      enabled: true

Field	Type	Required	Default	Description
`enabled`	bool	No	`false`	Enables the AWS Secrets Manager provider
`endpoint_url`	string	No	(empty)	Custom endpoint URL (useful for LocalStack testing)

Authentication

The AWS provider relies on the default AWS credential chain. You can authenticate using any of the following methods:

Environment variables (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, and optionally AWS_SESSION_TOKEN for temporary credentials)
Shared credentials file (~/.aws/credentials)
IAM roles for Amazon EC2 or ECS
IAM Roles Anywhere
SSO credentials

Set the AWS region using the AWS_DEFAULT_REGION or AWS_REGION environment variable.

Environment Variables

export AWS_DEFAULT_REGION="us-east-1"
export AWS_ACCESS_KEY_ID="your_access_key"
export AWS_SECRET_ACCESS_KEY="your_secret_key"
export AWS_SESSION_TOKEN="your_session_token" # Only needed for temporary credentials (STS, assumed roles)

You can also configure the provider itself through environment variables:

export FLIPT_SECRETS_PROVIDERS_AWS_ENABLED=true
export FLIPT_SECRETS_PROVIDERS_AWS_ENDPOINT_URL="http://localhost:4566"

Custom Endpoint

For local development with LocalStack or other AWS-compatible services, specify a custom endpoint:

secrets:
  providers:
    aws:
      enabled: true
      endpoint_url: "http://localhost:4566"

GCP Secret Manager Provider

The GCP Secret Manager provider retrieves secrets stored in Google Cloud Secret Manager. It supports both global and regional secrets.

Configuration

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

Field	Type	Required	Default	Description
`enabled`	bool	No	`false`	Enables the GCP Secret Manager provider
`project`	string	Yes (when enabled)	(none)	GCP project ID
`location`	string	No	(empty)	GCP region for regional secrets
`credentials`	string	No	(empty)	Path to a service account credentials JSON file

Authentication

The GCP provider supports two authentication methods:

Application Default Credentials (ADC): Automatically used when no credentials path is specified. This works with GCE metadata, GKE workload identity, and gcloud auth application-default login.
Service account key file: Specify an explicit path to a service account JSON credentials file.

secrets:
  providers:
    gcp:
      enabled: true
      project: "my-gcp-project"
      credentials: "/path/to/service-account.json"

Regional Secrets

By default, the provider accesses global secrets. To use regional secrets, specify the location field:

secrets:
  providers:
    gcp:
      enabled: true
      project: "my-gcp-project"
      location: "us-central1"

Environment Variables

export FLIPT_SECRETS_PROVIDERS_GCP_ENABLED=true
export FLIPT_SECRETS_PROVIDERS_GCP_PROJECT="my-gcp-project"
export FLIPT_SECRETS_PROVIDERS_GCP_LOCATION="us-central1"
export FLIPT_SECRETS_PROVIDERS_GCP_CREDENTIALS="/path/to/credentials.json"

Azure Key Vault Provider

The Azure Key Vault provider retrieves secrets stored in Azure Key Vault. It uses the Azure SDK for Go with DefaultAzureCredential, which supports multiple authentication methods.

Configuration

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

Field	Type	Required	Default	Description
`enabled`	bool	No	`false`	Enables the Azure Key Vault provider
`vault_url`	string	Yes (when enabled)	(none)	Azure Key Vault URL (for example, `https://my-vault.vault.azure.net/`)

Authentication

The Azure provider uses DefaultAzureCredential, which tries multiple authentication methods in order:

Environment variables (AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_CLIENT_SECRET)
Workload identity (for Kubernetes)
Managed identity (for Azure VMs, App Service, and other Azure services)
Azure CLI credentials

Environment Variables

export AZURE_CLIENT_ID="your_client_id"
export AZURE_TENANT_ID="your_tenant_id"
export AZURE_CLIENT_SECRET="your_client_secret"

You can also configure the provider itself through environment variables:

export FLIPT_SECRETS_PROVIDERS_AZURE_ENABLED=true
export FLIPT_SECRETS_PROVIDERS_AZURE_VAULT_URL="https://my-vault.vault.azure.net/"

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, aws, gcp, azure)
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:
  required: true
  session:
    csrf:
      key: "${secret:file:csrf-key}" # References /etc/flipt/secrets/csrf-key
  methods:
    token:
      enabled: true
      storage:
        tokens:
          "ci_token":
            credential: "${secret:file:ci-token}" # References /etc/flipt/secrets/ci-token

Vault Provider Examples

authentication:
  required: true
  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}"
    token:
      enabled: true
      storage:
        tokens:
          "ci_token":
            credential: "${secret:vault:flipt/tokens:ci-token}"

Cloud Provider Examples

For cloud providers (AWS, GCP, Azure), the key in the secret reference corresponds to the exact secret name as stored in the provider. Path separators and version specifiers are not supported in the key — use the secret’s name directly.

storage:
  default:
    git:
      authentication:
        token: "${secret:gcp:git-token}" # GCP Secret Manager
        password: "${secret:aws:git-password}" # AWS Secrets Manager

authentication:
  methods:
    oidc:
      providers:
        azure_ad:
          client_id: "${secret:azure:oidc-client-id}" # Azure Key Vault
          client_secret: "${secret:azure:oidc-client-secret}" # Azure Key Vault

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

​Why Use External Secrets?

​Supported Providers

File Provider

HashiCorp Vault

AWS Secrets Manager

GCP Secret Manager

Azure Key Vault

​Configuration Overview

​File Provider

​Configuration

​Usage

​HashiCorp Vault Provider

​Basic Configuration

​Authentication Methods

​Token Authentication

​Kubernetes Authentication

​AppRole Authentication

​Environment Variables

​AWS Secrets Manager Provider

​Configuration

​Authentication

​Environment Variables

​Custom Endpoint

​GCP Secret Manager Provider

​Configuration

​Authentication

​Regional Secrets

​Environment Variables

​Azure Key Vault Provider

​Configuration

​Authentication

​Environment Variables

​Using Secrets in Configuration

​Secret Reference Syntax

​File Provider Examples

​Vault Provider Examples

​Cloud Provider Examples

​Combined with Environment Variables

​Structured Secret References

Why Use External Secrets?

Supported Providers

Configuration Overview

File Provider

Configuration

Usage

HashiCorp Vault Provider

Basic Configuration

Authentication Methods

Token Authentication

Kubernetes Authentication

AppRole Authentication

Environment Variables

AWS Secrets Manager Provider

Configuration

Authentication

Environment Variables

Custom Endpoint

GCP Secret Manager Provider

Configuration

Authentication

Regional Secrets

Environment Variables

Azure Key Vault Provider

Configuration

Authentication

Environment Variables

Using Secrets in Configuration

Secret Reference Syntax

File Provider Examples

Vault Provider Examples

Cloud Provider Examples

Combined with Environment Variables

Structured Secret References