PSA/docs/security/config/DOCKER_SECRET_PROVIDER_CONFIG.md

Docker Secret Provider Configuration

This document explains the secret provider configuration for Docker and Docker Compose deployments.

Overview

The application now uses a composite secret provider system that allows for flexible secret management across different deployment environments. The system supports:

• Environment Variables (env provider)
• Filesystem Secrets (filesystem provider)
• HashiCorp Vault (vault provider)

Configuration Variables

SECRET_READ_CHAIN

Comma-separated list of providers to try for reading secrets, in order.

Examples:

• env,filesystem - Try environment variables first, then filesystem
• env,filesystem,vault - Try env vars, then filesystem, then Vault
• filesystem - Only use filesystem secrets

SECRET_WRITE_PROVIDER

Single provider to use for writing/updating secrets.

Examples:

• filesystem - Write secrets to filesystem
• vault - Write secrets to Vault

Default Configurations by Environment

Development (docker-compose.yaml)

SECRET_READ_CHAIN: env,filesystem
SECRET_WRITE_PROVIDER: filesystem

This allows developers to override secrets via environment variables while falling back to filesystem secrets.

Production (docker-compose.prod.yaml)

SECRET_READ_CHAIN: env,filesystem,vault
SECRET_WRITE_PROVIDER: filesystem

Production environments can use all three providers, with Vault as the final fallback for reads.

Community Edition (docker-compose.ce.yaml)

SECRET_READ_CHAIN: env,filesystem
SECRET_WRITE_PROVIDER: filesystem

CE edition focuses on simple deployment with environment variables and filesystem secrets.

Enterprise Edition (docker-compose.ee.yaml)

SECRET_READ_CHAIN: env,filesystem,vault
SECRET_WRITE_PROVIDER: filesystem

EE edition includes Vault support for enterprise secret management.

Overriding Configuration

You can override the secret provider configuration in several ways:

1. Environment Variables

Set SECRET_READ_CHAIN and SECRET_WRITE_PROVIDER environment variables before running docker-compose:

export SECRET_READ_CHAIN="env,vault"
export SECRET_WRITE_PROVIDER="vault"
docker-compose up

2. .env File

Add to your .env file:

SECRET_READ_CHAIN=env,filesystem,vault
SECRET_WRITE_PROVIDER=vault

3. docker-compose.override.yaml

Create a docker-compose.override.yaml file:

version: '3.8'
services:
  server:
    environment:
      SECRET_READ_CHAIN: env,vault
      SECRET_WRITE_PROVIDER: vault

Vault Configuration

When using the vault provider, ensure these environment variables are set:

• VAULT_ADDR - Vault server URL (e.g., https://vault.example.com)
• VAULT_TOKEN - Authentication token for Vault
• VAULT_APP_SECRET_PATH - Path for application secrets (default: kv/data/app/secrets)
• VAULT_TENANT_SECRET_PATH_TEMPLATE - Path template for tenant secrets (default: kv/data/tenants/{tenantId}/secrets)

Migration from Legacy Configuration

The legacy SECRET_PROVIDER_TYPE environment variable is still supported for backward compatibility:

• SECRET_PROVIDER_TYPE=filesystem → SECRET_READ_CHAIN=filesystem SECRET_WRITE_PROVIDER=filesystem
• SECRET_PROVIDER_TYPE=vault → SECRET_READ_CHAIN=vault SECRET_WRITE_PROVIDER=vault

However, the new composite system is recommended for new deployments.

Examples

Local Development with Environment Overrides

# Override database password via environment variable
export DB_PASSWORD_SERVER="my-local-password"
docker-compose up

Production with Vault Integration

# docker-compose.prod.override.yaml
version: '3.8'
services:
  server:
    environment:
      SECRET_READ_CHAIN: env,filesystem,vault
      SECRET_WRITE_PROVIDER: vault
      VAULT_ADDR: https://vault.company.com
      VAULT_TOKEN: ${VAULT_TOKEN}

Kubernetes with ConfigMap Overrides

apiVersion: v1
kind: ConfigMap
metadata:
  name: secret-provider-config
data:
  SECRET_READ_CHAIN: "env,filesystem,vault"
  SECRET_WRITE_PROVIDER: "vault"
  VAULT_ADDR: "https://vault.company.com"

Troubleshooting

Check Current Configuration

The application logs will show the secret provider configuration at startup:

INFO: Building composite secret provider. Read chain: [env, filesystem], Write provider: filesystem

Common Issues

1. Vault connection errors - Check VAULT_ADDR and VAULT_TOKEN
2. Missing filesystem secrets - Ensure secret files exist in /run/secrets/
3. Permission errors - Check file permissions on secret files (should be 600)

Validation Errors

The system validates configuration at startup and will show descriptive error messages:

Error: Invalid provider types in SECRET_READ_CHAIN: invalid. Supported types: env, filesystem, vault
Error: VAULT_ADDR environment variable is required when using vault provider