Key Vault

Soundcheck uses Azure Key Vault to securely store and manage sensitive configuration values. This provides centralized secret management with audit trails and secure access through managed identities.

Overview

The infrastructure stores sensitive environment variables in Azure Key Vault instead of directly in App Service settings:

Benefits

Benefit	Description
Centralized Management	All secrets in one secure location
Managed Identity Access	No credentials stored in application
Audit Trails	Track all secret access and modifications
Secret Rotation	Rotate secrets without redeployment
Private Access	Key Vault accessible only via private endpoint

Secrets stored

Secret Name	Purpose	Used By
`next-public-api-password`	Frontend API authentication	Web App
`next-public-api-username`	Frontend API authentication	Web App
`clerk-secret-key`	Clerk authentication	Web App
`administrator-password`	Database admin password	Backend
`docker-registry-server-password`	Container registry	Backend
`postgres-database-url`	Database connection string	Backend
`sentry-dsn`	Error tracking	All services
`qb-client-id`	QuickBooks OAuth app client ID	Backend
`qb-client-secret`	QuickBooks OAuth app client secret	Backend
`credential-encryption-key`	AES key for QB OAuth token encryption	Backend
`google-maps-server-api-key`	Server-only Google Maps/Places key for place photo proxy (`GOOGLE_MAPS_SERVER_API_KEY` on api-events). Populate per env (dev/qa/prod); do not reuse the browser Maps key	Backend

Architecture

┌─────────────────────────────────────────────────────────────┐
│                      Azure Key Vault                        │
│                                                             │
│  ┌─────────────────┐  ┌─────────────────┐                  │
│  │ Frontend Secrets │  │ Backend Secrets │                  │
│  │                  │  │                  │                  │
│  │ • clerk-secret   │  │ • database-url   │                  │
│  │ • api-password   │  │ • admin-password │                  │
│  │ • api-username   │  │ • registry-pass  │                  │
│  └─────────────────┘  └─────────────────┘                  │
└─────────────────────────────────────────────────────────────┘
                            │
                   Private Endpoint
                            │
              ┌─────────────┴─────────────┐
              │                           │
    ┌─────────┴─────────┐       ┌────────┴────────┐
    │   Web App Service  │       │   API App Service│
    │                    │       │                  │
    │  Managed Identity  │       │  Managed Identity│
    │  (Key Vault Reader)│       │  (Key Vault Reader)│
    └────────────────────┘       └──────────────────┘

Configuration

App service Key Vault references

App Services use Key Vault references instead of direct values:

# Frontend app_settings
app_settings = {
  CLERK_SECRET_KEY = "@Microsoft.KeyVault(SecretUri=${var.clerk_secret_key_secret_uri})"
  NEXT_PUBLIC_API_PASSWORD = "@Microsoft.KeyVault(SecretUri=${var.api_password_secret_uri})"
}

# Backend app_settings
app_settings = {
  DATABASE_URL = "@Microsoft.KeyVault(SecretUri=${var.postgres_database_url_secret_uri})"
}

Terraform module structure

modules/security/
├── main.tf           # Key Vault and secrets
├── variables.tf      # Secret value inputs
└── outputs.tf        # Secret URI outputs

Network security

Private endpoint

Key Vault is only accessible through a private endpoint:

Subnet: Dedicated private endpoint subnet (10.0.2.0/24)
DNS Zone: privatelink.vaultcore.azure.net
NSG: HTTPS traffic only

Access control

Principal	Role	Scope
Managed Identity	Key Vault Secrets Officer	Key Vault
DevOps Pipeline	Key Vault Administrator	Key Vault

Adding new secrets

Add secret resource

In modules/security/main.tf:

resource "azurerm_key_vault_secret" "new_secret" {
  name         = "new-secret-name"
  value        = var.new_secret_value
  key_vault_id = azurerm_key_vault.main.id
}

Add variable

In modules/security/variables.tf:

variable "new_secret_value" {
  description = "Description of the secret"
  type        = string
  sensitive   = true
}

Add output

In modules/security/outputs.tf:

output "new_secret_uri" {
  value = azurerm_key_vault_secret.new_secret.id
}

Update consuming module

Pass the secret URI to the frontend or backend module.

Troubleshooting

Access Denied

Verify managed identity has proper RBAC permissions:

az role assignment list --assignee <managed-identity-principal-id>

DNS Resolution Failed

Check private DNS zone is linked to VNet:

nslookup <vault-name>.vault.azure.net

Secret Already Exists

Soft-delete the existing secret:

az keyvault secret delete \
  --vault-name <vault-name> \
  --name <secret-name>

App Service Can't Read Secret

Verify Key Vault reference syntax is correct
Check managed identity assignment on App Service
Verify private endpoint connectivity

Vault names by environment

Environment	Key Vault Name
Dev	`dev01-cus-core-kv`
QA	`qa01-cus-core-kv`
Prod	`prod-cus-core-kv`

Best practices

Never log secrets - Use Key Vault references, not direct values
Regular rotation - Implement secret rotation procedures
Minimal access - Apply principle of least privilege
Monitor access - Enable Key Vault logging and alerts
Backup - Ensure Key Vault has backup and recovery enabled

Overview

Backend

Backend integrations

API reference

Frontend

Mobile

Infrastructure

CI/CD

Development

Guides

Reference

Overview

Benefits

Secrets stored

Architecture

Configuration

App service Key Vault references

Terraform module structure

Network security

Private endpoint

Access control

Adding new secrets

Troubleshooting

Vault names by environment

Best practices

​Overview

​Benefits

​Secrets stored

​Architecture

​Configuration

​App service Key Vault references

​Terraform module structure

​Network security

​Private endpoint

​Access control

​Adding new secrets

​Troubleshooting

​Vault names by environment

​Best practices

Overview

Benefits

Secrets stored

Architecture

Configuration

App service Key Vault references

Terraform module structure

Network security

Private endpoint

Access control

Adding new secrets

Troubleshooting

Vault names by environment

Best practices