Azure Key Vault

Overview

The Guardian Platform uses Azure Key Vault for managing cryptographic keys for DID (Decentralized Identifier) signing operations.

Required components:

• Key Vault – Stores and manages signing keys for decentralized identities
• Service Principal – Authenticated identity for platform access to the key vault

Platform behavior:

• Automatically creates and manages keys as needed
• Stores key IDs in the database
• Creates software-protected EC keys on the secp256k1 curve (P-256K), limited to sign and verify operations

This guide covers:

• Creating an Azure Key Vault (Azure CLI or Portal)
• Setting up a service principal with key vault permissions
• Configuring the Helm chart for Azure Key Vault

Prerequisites

• Azure subscription with permissions to create key vaults and app registrations
• Azure CLI installed and configured (for CLI method)
• Resource group created (or permission to create one)

Helm Configuration

Add the following to the values.yaml and secrets.yaml files. Placeholders will be filled in throughout the steps below.

values.yaml:

auth-service:
  config:
    keyManagement:
      provider: "azure_key_vault"
      azure_key_vault:
        vaultUrl: "<vault-url>" # Filled in after step 2
        tenantId: "<tenant-id>" # Filled in after step 3

secrets.yaml:

global:
  secrets:
    create: true
    keyManagement:
      provider: "azure_key_vault"
      azure_key_vault:
        secretName: "platform-azure-key-vault"
        values:
          clientId: "<client-id>" # Filled in after step 3
          clientSecret: "<client-secret>" # Filled in after step 3
          tenantId: "<tenant-id>" # Filled in after step 3
          vaultUrl: "<vault-url>" # Filled in after step 2

Quick Start (CLI Method - Recommended)

Set the following variables — they will be used throughout this guide. Replace the values with ones for the deployment:

RESOURCE_GROUP="governance-rg"
KEY_VAULT_NAME="governance-keyvault"  # Must be globally unique, 3-24 chars
LOCATION="eastus"
APP_NAME="guardian-platform-kv"

1. Create Resource Group (if needed)

az group create \
  --name $RESOURCE_GROUP \
  --location $LOCATION

2. Create Key Vault

az keyvault create \
  --name $KEY_VAULT_NAME \
  --resource-group $RESOURCE_GROUP \
  --location $LOCATION \
  --sku standard \
  --enable-rbac-authorization true \
  --enabled-for-deployment false \
  --enabled-for-disk-encryption false \
  --enabled-for-template-deployment false

Retrieve the vault URL:

az keyvault show \
  --name $KEY_VAULT_NAME \
  --resource-group $RESOURCE_GROUP \
  --query properties.vaultUri \
  --output tsv

Store the URL in a variable for use in subsequent commands:

VAULT_URL="<vault-url-from-output>"

Update values.yaml with the vault URL.

values.yaml -> auth-service.config.keyManagement.azure_key_vault:

vaultUrl: "<vault-url>"

3. Create Service Principal (App Registration)

Create the service principal with the “Key Vault Crypto Officer” role on the vault. Auth Service creates, reads, signs with, and deletes keys; “Key Vault Crypto User” can’t create or delete them. Assigning a role requires Owner or User Access Administrator on the vault:

az ad sp create-for-rbac \
  --name $APP_NAME \
  --role "Key Vault Crypto Officer" \
  --scopes /subscriptions/$(az account show --query id -o tsv)/resourceGroups/$RESOURCE_GROUP/providers/Microsoft.KeyVault/vaults/$KEY_VAULT_NAME

The output will look like:

{
  "appId": "11111111-1111-1111-1111-111111111111",
  "displayName": "guardian-platform-kv",
  "password": "abc123~exampleSecret",
  "tenant": "22222222-2222-2222-2222-222222222222"
}

Save the password (client secret) — it cannot be retrieved later. Role assignments can take a few minutes to take effect.

Update values.yaml with the tenant ID.

values.yaml -> auth-service.config.keyManagement.azure_key_vault:

tenantId: "<tenant-from-output>"

Update secrets.yaml with the credentials.

secrets.yaml -> global.secrets.keyManagement.azure_key_vault.values:

clientId: "<app-id-from-output>"
clientSecret: "<password-from-output>"
tenantId: "<tenant-from-output>"
vaultUrl: "<vault-url-from-step-2>"

Alternative: Web UI Setup

vaultUrl: "<vault-url>"

tenantId: "<tenant-id>"

clientId: "<application-client-id>"
clientSecret: "<client-secret-value>"
tenantId: "<directory-tenant-id>"
vaultUrl: "<vault-url-from-step-1>"

Verification

Log in as the service principal (replace with values from step 3):

az login --service-principal \
  --username "<client-id>" \
  --password "<client-secret>" \
  --tenant "<tenant-id>"

Auth Service creates the shared platform key, organization-key, at startup. After installing, show it (should succeed and list sign and verify key operations):

az keyvault key show --vault-name $KEY_VAULT_NAME --name organization-key

Log out and return to the normal account:

az logout
az login

If the key is missing, check the Auth Service logs for Key Vault Forbidden errors.

Security Best Practices

• Rotate Secrets: Regularly rotate client secrets and update Kubernetes secrets
• Least Privilege: Only grant the minimum required key permissions
• Enable Logging: Enable Azure Key Vault diagnostic logging for audit trails
• Soft Delete: Enable soft delete and purge protection on the key vault to prevent accidental deletion

Official Documentation

• Azure Key Vault CLI Reference
• Azure Key Vault Overview
• Key Vault Best Practices
• Service Principal Authentication
• Helm Chart Examples

Related

• Key Management — how Azure Key Vault compares with the other key providers
• Key Configuration — what Auth Service signs with these keys and how to plan rotation
• Backup and Restore — soft-delete and purge protection for non-exportable keys
• Microsoft Entra ID — the Azure identity provider and its app registrations
• Azure Storage Account — the Azure object storage the platform needs
• Chart Values — the full values and secrets files these settings go into