Auto-unseal using Azure Key Vault
When a Vault server is started, it starts in a sealed state and it does not know how to decrypt data. Before any operation can be performed on the Vault, it must be unsealed. Unsealing is the process of constructing the master key necessary to decrypt the data encryption key.

Challenge
Vault unseal operation requires a quorum of existing unseal keys split by Shamir's Secret sharing algorithm. This is done so that the "keys to the kingdom" won't fall into one person's hand. However, this process is manual and can become painful when you have many Vault clusters as there are now many different key holders with many different keys.
Solution
Vault supports opt-in automatic unsealing via cloud technologies: AliCloud KMS, AWS KMS, Azure Key Vault, Google Cloud KMS, and OCI KMS. This feature enables operators to delegate the unsealing process to trusted cloud providers to ease operations in the event of partial failure and to aid in the creation of new or ephemeral clusters.

This tutorial demonstrates an example of using Azure Key Vault to auto-unseal a Vault server.
Prerequisites
This tutorial assumes the following:
- Terraform installed and configured
- You have a Microsoft Azure account
- Tenant ID
- Client ID
- Client Secret
- Subscription ID
Azure permissions
This tutorial uses Terraform to provision a Vault environment to demonstrate the auto-unseal. The following Azure resources will be created:
- Azure Key Vault
- Virtual network with CIDR of
10.0.0.0/16
- Subnet with CIDR,
10.0.1.0/24
- Subnet with CIDR,
- Public IP
- Security group
- A virtual machine to host a Vault server and accessible via public IP
Therefore, the service principal you use to perform the steps in this tutorial must have enough permission to provision all these resources.
Production
To perform auto-unseal, it only requires the Azure built-in Key Vault
Secrets User
and Key Vault Crypto User
roles.
Create an Azure service principal
To delegate the credential generation task to Vault, you need to give Vault privileged Azure credentials to perform the task. The following demonstrates the creation of a service principal.
If you already know your Azure tenant ID, client ID, client secret, and subscription ID, skip to the Download demo assets section and proceed.
Note
Refer to Terraform Azure provider documentation to create a service principal via the Azure CLI.
Launch the Microsoft Azure Portal and sign in.
Select Azure Active Directory and select Properties.
Copy the Tenant ID.
In a terminal, set the variable
TENANT_ID
to the Tenant ID.From the side navigation, select App registrations.
Select New registrations.
Enter
education
in the Name field.Click Register.
Copy the Application (client) ID.
In a terminal, set the variable
CLIENT_ID
to the Application (client) ID.From the side navigation, select Certificate & secrets.
Under the Client secrets, click New client secret.
Enter a description in the Description field.
Click Add.
Copy the client secret value.
In a terminal, set the variable
CLIENT_SECRET
to the client secret value.From the side navigation, click API permissions.
Under Configured permissions, click Add a permission.
Under Supported legacy APIs, click Azure Active Directory Graph.
Click Delegated permissions.
Expand User, select the check-box for User.Read.
Click Application permissions.
Expand Application, select the check-box for Application.ReadWrite.All.
Expand Directory, select the check-box for Directory.ReadWrite.All.
Click API permissions.
Click Grant admin consent for azure to grant the permissions.
Navigate to the Subscriptions blade.
Copy the Subscription ID.
In a terminal, set the variable
SUBSCRIPTION_ID
to the Subscription ID.Click the name of the subscription.
From the side navigation, click Access control (IAM).
Click Add to expand the menu.
Click Add a role assignment.
Choose
Owner
from the Role select field.Choose
User, group, or service principal
from the Assign Access To select field.Enter the application name or application id in the Select field.
Click the application when it is displayed.
Click Save.
The application is created with the correct permissions and you have these identifiers and credentials:
- Tenant ID
- Client ID
- Client Secret
- Subscription ID
Display the created credentials.
Download demo assets
Retrieve the additional configuration by cloning the hashicorp/vault-guides repository from GitHub.
This repository contains supporting content for all of the Vault learn guides. The content specific to this tutorial can be found within a sub-directory.
Go into the
vault-guides/operations/azure-keyvault-unseal
directory.
Working directory
This tutorial assumes that the remainder of commands are executed within this directory.
Step 1: Provision the Cloud Resources
The terraform files reads the credentials from the terraform.tfvars
and
generates the resources defined in the main.tf
.
Modify terraform.tfvars.example
with a public SSH key, public_key
, and Azure
credentials: tenant_id
; client_id
; client_secret
and subscription_id
.
Save the file and create a copy of the file named terraform.tfvars
.
The main.tf
file generates a new resource group with:
- Virtual machine with Vault already installed
- Azure Vault Key (
Test-vault-xxxx
) - A key (
generated-key
)
Initialize the Azure provider plugins.
Create an execution plan.
Apply the changes.
Step 2: Test the Auto-unseal Feature
Create a variable named AZURE_VAULT_IP
to store the IP address of the virtual
machine.
SSH into the virtual machine with the azureuser
user.
Within this SSH session, check the status of the Vault server.
The output displays that the Vault server is not initialized (Initialized is
false
).
Initialize the Vault server.
Check the status of the Vault server.
The output displays that the Vault server is unsealed (Sealed is false
).
Vault started as a service. The service writes its output to a log.
Display the Vault server log.
The logs displays that the Azure Vault key is being fetched to unseal the Vault server. The Vault server automatically unseals every time Vault is started.
Restart the Vault server.
Check the status of the Vault server.
The output displays that the Vault server is automatically unsealed.
Display the Vault service configuration file.
Review the Vault server configuration file.
Notice the Vault configuration file defines the azurekeyvault
stanza
with all parameter values properly populated: client ID, client secret, tenant
ID, vault name (generated by Terraform), and Azure Key Vault key name.
Permissions
The client you define in the azurekeyvault
stanza must
have the Key Vault Secrets User
and Key Vault Crypto User
roles.
Warning
Although the listener stanza disables TLS (tls_disable = "true"
) for this
tutorial, Vault should always be used with
TLS
in production to provide secure communication between clients and the Vault
server. It requires a certificate file and key file on each Vault host.
Key rotation
With auto-unseal enabled, set up Azure Key Vault with key rotation using the Azure Automation Account and Vault will recognize newly rotated keys since the key metadata is stored with the encrypted data to ensure the correct key is used during decryption operations.
Step 3: Clean Up
When you are done experimenting this demo follow these steps to clean up.
Destroy the resources that created by Terraform.
Remove the Terraform state files.