Azure Key Vault

Overview

The EQTY Governance 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
• Uses appropriate key policies for signing 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 3

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="governance-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 \
  --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)

az ad sp create-for-rbac \
  --name $APP_NAME \
  --role "Key Vault Crypto User" \
  --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": "governance-platform-kv",
  "password": "abc123~exampleSecret",
  "tenant": "22222222-2222-2222-2222-222222222222"
}

Save the password (client secret) — it cannot be retrieved later.

Store the client ID in a variable (needed for step 4):

CLIENT_ID="<app-id-from-output>"

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>"

4. Configure Key Vault Access Policy

az keyvault set-policy \
  --name $KEY_VAULT_NAME \
  --resource-group $RESOURCE_GROUP \
  --object-id $(az ad sp show --id $CLIENT_ID --query id -o tsv) \
  --key-permissions get list create update verify sign

Alternative: Web UI Setup

Click to expand Azure Portal instructions

Using the Azure Portal

1. Create Key Vault

• Follow Quickstart: Create a key vault using the Azure portal
• Note the vault URL (e.g. https://governance-keyvault.vault.azure.net/)

Update values.yaml with the vault URL.

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

vaultUrl: "<vault-url>"

2. Register Application

• Navigate to App registrations
• Follow Register an application in Microsoft Entra ID
• Note the Application (client) ID and Directory (tenant) ID

Update values.yaml with the tenant ID.

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

tenantId: "<tenant-id>"

3. Create Client Secret

• In the app registration, navigate to “Certificates & secrets”
• Create a new client secret
• Save the secret value immediately — it cannot be retrieved later

Update secrets.yaml with the credentials.

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

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

4. Configure Access Policy

• In the Key Vault, navigate to “Access policies”
• Click “Create”
• Select key permissions: Get, List, Create, Update, Verify, Sign
• Select the registered application as the “Principal”
• Review and create the access policy

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>"

List keys in the vault (should succeed, even if empty):

az keyvault key list --vault-name $KEY_VAULT_NAME

Log out and return to the normal account:

az logout
az login

If the commands succeed without errors, the configuration is correct.

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