Proposed Pull Request Change

📄 Document Links

View on GitHub View on Microsoft Learn

--- title: Restore Key Vault key & secret for encrypted Azure VM description: Learn how to restore Key Vault key and secret for encrypted VMs via Azure PowerShell using Azure Backup. ms.topic: how-to ms.custom: devx-track-azurepowershell ms.date: 08/20/2025 author: AbhishekMallick-MS ms.author: v-mallicka # Customer intent: As a system administrator managing encrypted virtual machines, I want to restore keys and secrets to Azure Key Vault, so that I can successfully recover and create encrypted VMs from backup without losing data integrity and security. --- # Restore Key Vault key and secret for encrypted VMs using Azure Backup This article describes how to use Azure VM Backup to restore encrypted Azure Virtual Machines (VMs) when the original key and secret aren't available in the Key Vault. It's also applicable for scenarios where you want to maintain a separate copy of the key (Key Encryption Key) and secret (BitLocker Encryption Key) for the restored VM. [!INCLUDE [updated-for-az](~/reusable-content/ce-skilling/azure/includes/updated-for-az.md)] ## Prerequisites Before you begin restoring an encrypted VM, ensure the following prerequisites are met: * **Backup encrypted VMs** - Encrypted Azure VMs are backed up using Azure Backup. Refer to the article [Manage backup and restore of Azure VMs using PowerShell](backup-azure-vms-automation.md) for details about how to back up encrypted Azure VMs. * **Configure Azure Key Vault** – Ensure that key vault to which keys and secrets need to be restored is already present. Refer to the article [Get Started with Azure Key Vault](/azure/key-vault/general/overview) for details about key vault management. * **Restore disk** - Ensure that you trigger the restore job for restoring disks for encrypted VM using [PowerShell steps](backup-azure-vms-automation.md#restore-an-azure-vm) so that this job generates a JSON file in your storage account containing keys and secrets for the encrypted VM to be restored. ## Get key and secret from Azure Backup > [!NOTE] > Once disk is restored for the encrypted VM, ensure that: > > * $details are populated with restore disk job details, as mentioned in [PowerShell steps in Restore the Disks section](backup-azure-vms-automation.md#restore-an-azure-vm) > * VM should be created from restored disks only **after key and secret is restored to key vault**. Query the restored disk properties for the job details. ```powershell $properties = $details.properties $storageAccountName = $properties["Target Storage Account Name"] $containerName = $properties["Config Blob Container Name"] $encryptedBlobName = $properties["Encryption Info Blob Name"] ``` Set the Azure storage context and restore JSON configuration file containing key and secret details for encrypted VM. ```powershell Set-AzCurrentStorageAccount -Name $storageaccountname -ResourceGroupName '<rg-name>' $destination_path = 'C:\vmencryption_config.json' Get-AzStorageBlobContent -Blob $encryptedBlobName -Container $containerName -Destination $destination_path $encryptionObject = Get-Content -Path $destination_path | ConvertFrom-Json ``` ## Restore key Once the JSON file is generated in the mentioned destination path, generate key blob file from the JSON and feed it to restore key cmdlet to put the key (KEK) back in the key vault. ```powershell $keyDestination = 'C:\keyDetails.blob' [io.file]::WriteAllBytes($keyDestination, [System.Convert]::FromBase64String($encryptionObject.OsDiskKeyAndSecretDetails.KeyBackupData)) Restore-AzKeyVaultKey -VaultName '<target_key_vault_name>' -InputFile $keyDestination ``` ## Restore secret Use the generated JSON file to get secret name and value and feed it to set secret cmdlet to put the secret - BitLocker Encryption Key (BEK) back in the key vault. Use these cmdlets if your **VM is encrypted using BEK and KEK**. **Use these cmdlets if your Windows VM is encrypted using BEK and KEK.** ```powershell $secretdata = $encryptionObject.OsDiskKeyAndSecretDetails.SecretData $Secret = ConvertTo-SecureString -String $secretdata -AsPlainText -Force $secretname = 'B3284AAA-DAAA-4AAA-B393-60CAA848AAAA' $Tags = @{'DiskEncryptionKeyEncryptionAlgorithm' = 'RSA-OAEP';'DiskEncryptionKeyFileName' = 'B3284AAA-DAAA-4AAA-B393-60CAA848AAAA.BEK';'DiskEncryptionKeyEncryptionKeyURL' = $encryptionObject.OsDiskKeyAndSecretDetails.KeyUrl;'MachineName' = 'vm-name'} Set-AzKeyVaultSecret -VaultName '<target_key_vault_name>' -Name $secretname -SecretValue $Secret -ContentType 'Wrapped BEK' -Tags $Tags ``` **Use these cmdlets if your Linux VM is encrypted using BEK and KEK.** ```powershell $secretdata = $encryptionObject.OsDiskKeyAndSecretDetails.SecretData $Secret = ConvertTo-SecureString -String $secretdata -AsPlainText -Force $secretname = 'B3284AAA-DAAA-4AAA-B393-60CAA848AAAA' $Tags = @{'DiskEncryptionKeyEncryptionAlgorithm' = 'RSA-OAEP';'DiskEncryptionKeyFileName' = 'LinuxPassPhraseFileName';'DiskEncryptionKeyEncryptionKeyURL' = <Key_url_of_newly_restored_key>;'MachineName' = 'vm-name'} Set-AzKeyVaultSecret -VaultName '<target_key_vault_name>' -Name $secretname -SecretValue $Secret -ContentType 'Wrapped BEK' -Tags $Tags ``` Use the generated JSON file to get secret name and value and feed it to set secret cmdlet to put the secret (BEK) back in the key vault. Use these cmdlets if your **VM is encrypted using BEK** only. ```powershell $secretDestination = 'C:\secret.blob' [io.file]::WriteAllBytes($secretDestination, [System.Convert]::FromBase64String($encryptionObject.OsDiskKeyAndSecretDetails.KeyVaultSecretBackupData)) Restore-AzKeyVaultSecret -VaultName '<target_key_vault_name>' -InputFile $secretDestination -Verbose ``` > [!NOTE] > > * The value for $secretname can be obtained by referring to the output of $encryptionObject.OsDiskKeyAndSecretDetails.SecretUrl and using text after secrets/ For example, the output secret URL is `https://keyvaultname.vault.azure.net/secrets/B3284AAA-DAAA-4AAA-B393-60CAA848AAAA/xx000000xx0849999f3xx30000003163` and secret name is B3284AAA-DAAA-4AAA-B393-60CAA848AAAA > * The value of the tag DiskEncryptionKeyFileName is the same as the secret name. > > ## Create virtual machine from restored disk If you back up encrypted VM using Azure VM Backup, the preceding PowerShell cmdlets help you restore key and secret back to the key vault. After restoring them, refer to the article [Manage backup and restore of Azure VMs using PowerShell](backup-azure-vms-automation.md#create-a-vm-from-restored-disks) to create encrypted VMs from restored disk, key, and secret. ## Legacy approach The preceding approach works for all the recovery points. However, the older approach of getting key and secret information from recovery point, would be valid for recovery points older than July 11, 2017 for VMs encrypted using BEK and KEK. Once restore disk job is complete for encrypted VM using [PowerShell steps](backup-azure-vms-automation.md#restore-an-azure-vm), ensure that $rp is populated with a valid value. ### Restore key (legacy approach) Use the following cmdlets to get key (KEK) information from recovery point and feed it to restore key cmdlet to put it back in the key vault. ```powershell $rp1 = Get-AzRecoveryServicesBackupRecoveryPoint -RecoveryPointId $rp[0].RecoveryPointId -Item $backupItem -KeyFileDownloadLocation 'C:\Users\downloads' Restore-AzureKeyVaultKey -VaultName '<target_key_vault_name>' -InputFile 'C:\Users\downloads' ``` ### Restore secret (legacy approach) Use the following cmdlets to get secret (BEK) information from recovery point and feed it to set secret cmdlet to put it back in the key vault. ```powershell $secretname = 'B3284AAA-DAAA-4AAA-B393-60CAA848AAAA' $secretdata = $rp1.KeyAndSecretDetails.SecretData $Secret = ConvertTo-SecureString -String $secretdata -AsPlainText -Force $Tags = @{'DiskEncryptionKeyEncryptionAlgorithm' = 'RSA-OAEP';'DiskEncryptionKeyFileName' = 'B3284AAA-DAAA-4AAA-B393-60CAA848AAAA.BEK';'DiskEncryptionKeyEncryptionKeyURL' = 'https://mykeyvault.vault.azure.net:443/keys/KeyName/84daaac999949999030bf99aaa5a9f9';'MachineName' = 'vm-name'} Set-AzKeyVaultSecret -VaultName '<target_key_vault_name>' -Name $secretname -SecretValue $secret -Tags $Tags -SecretValue $Secret -ContentType 'Wrapped BEK' ``` > [!NOTE] > > * Value for $secretname can be obtained by referring to the output of $rp1.KeyAndSecretDetails.SecretUrl and using text after secrets/ For example, the output secret URL is `https://keyvaultname.vault.azure.net/secrets/B3284AAA-DAAA-4AAA-B393-60CAA848AAAA/xx000000xx0849999f3xx30000003163` and secret name is B3284AAA-DAAA-4AAA-B393-60CAA848AAAA > * Value of the tag DiskEncryptionKeyFileName is same as secret name. > * Value for DiskEncryptionKeyEncryptionKeyURL can be obtained from key vault after restoring the keys back and using [Get-AzKeyVaultKey](/powershell/module/az.keyvault/get-azkeyvaultkey) cmdlet > > ## Next steps After restoring key and secret back to key vault, refer to the article [Manage backup and restore of Azure VMs using PowerShell](backup-azure-vms-automation.md#create-a-vm-from-restored-disks) to create encrypted VMs from restored disk, key, and secret.