ADR-003: Azure Key Vault for Secrets Management

Status: Accepted Date: 2026-03 Deciders: Platform team (platform-0043, T556)

Context

The Arbitex Platform manages several categories of sensitive configuration: JWT signing keys, database credentials, HMAC keys for audit log integrity, and provider API key encryption keys. These must be protected at rest and in transit, with access controlled, auditable, and rotatable without application downtime.

The original approach sourced all secrets from environment variables (SECRETS_BACKEND=env, the default). This is functional for development and small deployments, but presents operational challenges at enterprise scale:

Secrets embedded in container manifests, CI pipelines, or .env files are difficult to audit and rotate.
There is no native access control or audit trail on who read a secret.
Rotation requires redeploying the application to pick up new environment values.
Compliance frameworks (SOC 2 CC6, PCI-DSS 3.4, HIPAA) increasingly require hardware-backed secret storage with access logging.

A pluggable secrets backend architecture was designed to allow the application to source secrets from multiple providers without changing application code.

Decision

Azure Key Vault is the supported production secrets backend for cloud-hosted Arbitex Platform deployments. The backend is selected via SECRETS_BACKEND=vault (or azure_keyvault).

Authentication uses DefaultAzureCredential — this supports Azure Managed Identity (recommended for AKS workloads), service principal credentials, and Azure CLI for local development. No additional authentication configuration is required when running in Azure with Managed Identity enabled.

Secret names are translated from Python-style underscore names to Azure Key Vault hyphenated names automatically (e.g. jwt_secret_key → jwt-secret-key).

On startup, the backend performs a connectivity probe. If the vault is unreachable the application fails fast and refuses to start.

Consequences

Positive:

Secrets are stored in hardware-backed HSM (Azure Key Vault Premium tier) with customer-managed keys available.
Full access audit log via Azure Monitor — every secret read is recorded.
Rotation without application restart: update the secret in Azure Key Vault; the platform picks it up on next startup or cache refresh.
Access policy at the vault level (Azure RBAC) — principle of least privilege without application changes.
Eliminates secrets from container environment variables, Kubernetes Secrets, and CI/CD pipeline logs.
Pluggable architecture means other backends (HashiCorp Vault, file) can be used where Azure is not the cloud provider.

Negative / trade-offs:

Adds a startup dependency: the vault must be reachable when the platform starts. Network partitions or Key Vault downtime prevent cold-starts.
Azure-specific. Customers on AWS or GCP cannot use this backend natively (HashiCorp Vault backend or file backend are alternatives).
The file backend (JSON file) is provided for local development but must never be used in production.
Key Vault name length and character restrictions may require adjusting secret names from very long Python-style names.

Non-goals: This decision covers the platform application secrets backend only. Outpost secrets (provider API keys, cert paths, HMAC keys) are managed separately via the outpost environment and policy bundle encryption.