compose-env-azure

Azure Key Vault source adapter for compose-env.

Installation

npm install compose-env-azure @azure/keyvault-secrets @azure/identity

compose-env must also be installed in your project.

Usage

import { defineConfig, source } from 'compose-env'
import { azureKeyVaultSource } from 'compose-env-azure'

const config = await defineConfig(
  {
    DATABASE_URL: { type: 'url',    required: true, secret: true },
    API_KEY:      { type: 'string', required: true, secret: true },
    PORT:         { type: 'port',   default: 3000 },
  },
  {
    sources: [
      azureKeyVaultSource('https://my-vault.vault.azure.net'),
      source.env(),
    ],
  },
)

By default, all enabled secrets in the vault are loaded. Azure secret names use hyphens (e.g. my-db-url), which are converted to underscores and uppercased (MY_DB_URL) to match env var conventions.

Load Specific Secrets Only

To avoid loading every secret in the vault, pass an explicit list:

azureKeyVaultSource('https://my-vault.vault.azure.net', {
  secrets: ['database-url', 'api-key'],
})

Key Normalization

Azure Key Vault secret names are normalized automatically:

| Vault secret name | Resolved key | |-------------------|-----------------| | database-url | DATABASE_URL | | api-key | API_KEY | | redis-ttl | REDIS_TTL |

Options

| Option | Type | Default | Description | |-----------|------------|---------|--------------------------------------------------------------------------------------| | secrets | string[] | — | List of secret names to load. If omitted, all enabled secrets in the vault are loaded. |

Authentication

Authentication is handled by DefaultAzureCredential, which tries the following in order:

1. Environment variables — AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_CLIENT_SECRET
2. Workload Identity — For AKS pods with federated credentials
3. Managed Identity — For Azure VMs, App Service, Container Apps, etc.
4. Azure CLI — az login for local development

No additional configuration is needed when running in an Azure-managed environment.

Required Access Policies

The identity must have the Get and List secret permissions on the Key Vault:

# Azure CLI
az keyvault set-policy \
  --name my-vault \
  --object-id <principal-object-id> \
  --secret-permissions get list

Or assign the Key Vault Secrets User built-in role if using RBAC authorization.

Source Priority

Sources are resolved in order. Place azureKeyVaultSource before or after source.env() depending on which should take precedence:

// Key Vault overrides local .env files
sources: [source.env(), azureKeyVaultSource('https://my-vault.vault.azure.net')]

// Local .env files override Key Vault (useful for local development)
sources: [azureKeyVaultSource('https://my-vault.vault.azure.net'), source.env()]