---
title: "Azure Key Vault"
description: "Configure Azure Key Vault for deployment"
source: "Guardian Platform"
---
## 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](https://learn.microsoft.com/en-us/cli/azure/install-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`:

```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`:

```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:

```bash
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)

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

### 2. Create Key Vault

```bash
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:

```bash
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:

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

Update `values.yaml` with the vault URL.

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

```yaml
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:

```bash
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:

```json
{
  "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:

```yaml
tenantId: "<tenant-from-output>"
```

Update `secrets.yaml` with the credentials.

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

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

## Alternative: Web UI Setup

<details>
<summary>Click to expand Azure Portal instructions</summary>

### Using the Azure Portal

#### 1. Create Key Vault

- Follow [Quickstart: Create a key vault using the Azure portal](https://learn.microsoft.com/en-us/azure/key-vault/general/quick-create-portal#create-a-vault)
- Under "Access configuration", set the permission model to "Azure role-based access control"
- 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:

```yaml
vaultUrl: "<vault-url>"
```

#### 2. Register Application

- Navigate to [App registrations](https://entra.microsoft.com/#view/Microsoft_AAD_RegisteredApps/ApplicationsListBlade)
- Follow [Register an application in Microsoft Entra ID](https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app)
- 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:

```yaml
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:

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

#### 4. Assign Key Vault Role

- In the Key Vault, navigate to "Access control (IAM)"
- Click "Add" > "Add role assignment"
- Select the "Key Vault Crypto Officer" role
- Select the registered application as the member
- Review and assign the role

</details>

## Verification

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

```bash
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):

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

Log out and return to the normal account:

```bash
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](https://learn.microsoft.com/en-us/cli/azure/keyvault)
- [Azure Key Vault Overview](https://learn.microsoft.com/en-us/azure/key-vault/general/overview)
- [Key Vault Best Practices](https://learn.microsoft.com/en-us/azure/key-vault/general/best-practices)
- [Service Principal Authentication](https://learn.microsoft.com/en-us/azure/key-vault/general/authentication)
- [Helm Chart Examples](https://github.com/eqtylab/deployment/tree/main/charts/guardian-platform/examples)

## Related

- [Key Management](./key-management.mdx) — how Azure Key Vault compares with the other key providers
- [Key Configuration](../auth-service/key-configuration.mdx) — what Auth Service signs with these keys and how to plan rotation
- [Backup and Restore](./backup-and-restore.mdx#key-management) — soft-delete and purge protection for non-exportable keys
- [Microsoft Entra ID](./microsoft-entra-id.mdx) — the Azure identity provider and its app registrations
- [Azure Storage Account](./azure-storage-account.mdx) — the Azure object storage the platform needs
- [Chart Values](./chart-values.mdx) — the full values and secrets files these settings go into