> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flipt.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Secrets

> Secrets integration with file-based and external secret providers

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:

<CardGroup cols={2}>
  <Card title="File Provider" icon="folder" href="#file-provider">
    Store secrets in local files - ideal for development and simple deployments
  </Card>

  <Card title="HashiCorp Vault" icon="vault" href="#hashicorp-vault-provider">
    Enterprise-grade secret management with advanced authentication and access
    controls
  </Card>

  <Card title="AWS Secrets Manager" icon="aws" href="#aws-secrets-manager-provider">
    Retrieve secrets from AWS Secrets Manager using standard AWS credentials
  </Card>

  <Card title="GCP Secret Manager" icon="google" href="#gcp-secret-manager-provider">
    Retrieve secrets from Google Cloud Secret Manager with Application Default
    Credentials or service account keys
  </Card>

  <Card title="Azure Key Vault" icon="microsoft" href="#azure-key-vault-provider">
    Retrieve secrets from Azure Key Vault using Azure identity credentials
  </Card>
</CardGroup>

## Configuration Overview

Enable secrets management by configuring providers in your Flipt configuration:

```yaml theme={null}
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

```yaml theme={null}
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:

```bash theme={null}
# 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
```

<Note>
  Each secret is stored as a separate file. The filename becomes the secret key,
  and the file contents become the secret value.
</Note>

## 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

```yaml theme={null}
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:

```yaml theme={null}
vault:
  enabled: true
  address: "https://vault.company.com"
  auth_method: "token"
  token: "hvs.your_vault_token"
```

#### Kubernetes Authentication

Ideal for Kubernetes deployments:

```yaml theme={null}
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:

```yaml theme={null}
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:

```bash theme={null}
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](https://aws.amazon.com/secrets-manager/). It uses the AWS SDK for Go v2, which automatically resolves credentials from the standard AWS credential chain.

### Configuration

```yaml theme={null}
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](https://localstack.cloud/) testing) |

### Authentication

The AWS provider relies on the [default AWS credential chain](https://docs.aws.amazon.com/sdkref/latest/guide/standardized-credentials.html). 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

```bash theme={null}
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:

```bash theme={null}
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:

```yaml theme={null}
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](https://cloud.google.com/secret-manager). It supports both global and regional secrets.

### Configuration

```yaml theme={null}
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](https://cloud.google.com/secret-manager/docs/create-secret-regional) |
| `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.

```yaml theme={null}
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](https://cloud.google.com/secret-manager/docs/create-secret-regional), specify the `location` field:

```yaml theme={null}
secrets:
  providers:
    gcp:
      enabled: true
      project: "my-gcp-project"
      location: "us-central1"
```

### Environment Variables

```bash theme={null}
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](https://azure.microsoft.com/en-us/products/key-vault). It uses the Azure SDK for Go with `DefaultAzureCredential`, which supports multiple authentication methods.

### Configuration

```yaml theme={null}
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`](https://learn.microsoft.com/en-us/azure/developer/go/azure-sdk-authentication), 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

```bash theme={null}
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:

```bash theme={null}
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

```yaml theme={null}
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

```yaml theme={null}
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.

```yaml theme={null}
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:

```yaml theme={null}
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:

```yaml theme={null}
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
```