Moving an Azure Key Vault to another subscription

Note

We recommend that you use the Azure Az PowerShell module to interact with Azure. To get started, see Install Azure PowerShell. To learn how to migrate to the Az PowerShell module, see Migrate Azure PowerShell from AzureRM to Az.

Overview

Important

Moving a key vault to another subscription will cause a breaking change to your environment. Make sure you understand the impact of this change and follow the guidance in this article carefully before deciding to move key vault to a new subscription. If you are using Managed Service Identities (MSI) please read the post-move instructions at the end of the document.

Azure Key Vault is automatically tied to the default Microsoft Entra ID tenant ID for the subscription in which it is created. You can find tenant ID associated with your subscription by following this guide. All access policy entries and roles assignments are also tied to this tenant ID. If you move your Azure subscription from tenant A to tenant B, your existing key vaults will be inaccessible by the service principals (users and applications) in tenant B. To fix this issue, you need to:

Note

If Key Vault is created through Azure Lighthouse, it is tied to managing tenant id instead. Azure Lighthouse is only supported by vault access policy permission model. For more information about tenants in Azure Lighthouse, see Tenants, users, and roles in Azure Lighthouse.

  • Change the tenant ID associated with all existing key vaults in the subscription to tenant B.
  • Remove all existing access policy entries.
  • Add new access policy entries associated with tenant B.

For more information about Azure Key Vault and Microsoft Entra ID, see

Limitations

Important

Key Vaults used for disk encryption cannot be moved If you are using key vault with disk encryption for a VM, the key vault cannot be moved to a different resource group or a subscription while disk encryption is enabled. You must disable disk encryption prior to moving the key vault to a new resource group or subscription.

Some service principals (users and applications) are bound to a specific tenant. If you move your key vault to a subscription in another tenant, there's a chance that you won't be able to restore access to a specific service principal. Check to make sure that all essential service principals exist in the tenant where you are moving your key vault.

Prerequisites

You can check existing roles using the Azure portal, PowerShell, Azure CLI, or REST API.

Moving a key vault to a new subscription

  1. Sign in to the Azure portal.
  2. Navigate to your key vault
  3. Select on the "Overview" tab
  4. Select the "Move" button
  5. Select "Move to another subscription" from the dropdown options
  6. Select the resource group where you want to move your key vault
  7. Acknowledge the warning regarding moving resources
  8. Select "OK"

Additional steps when subscription is in a new tenant

If you moved your subscription containing the key vault to a new tenant, you need to manually update the tenant ID and remove old access policies and role assignments. Here are tutorials for these steps in PowerShell and Azure CLI. If you are using PowerShell, you may need to run the Clear-AzContext command to allow you to see resources outside your current selected scope.

Update tenant ID in a key vault

Select-AzSubscription -SubscriptionId <your-subscriptionId>                # Select your Azure Subscription
$vaultResourceId = (Get-AzKeyVault -VaultName myvault).ResourceId          # Get your key vault's Resource ID 
$vault = Get-AzResource -ResourceId $vaultResourceId -ExpandProperties     # Get the properties for your key vault
$vault.Properties.TenantId = (Get-AzContext).Tenant.TenantId               # Change the Tenant that your key vault resides in
$vault.Properties.AccessPolicies = @()                                     # Access policies can be updated with real
                                                                           # applications/users/rights so that it does not need to be                             # done after this whole activity. Here we are not setting 
                                                                           # any access policies. 
Set-AzResource -ResourceId $vaultResourceId -Properties $vault.Properties  # Modifies the key vault's properties.

Clear-AzContext                                                            #Clear the context from PowerShell
Connect-AzAccount                                                          #Log in again to confirm you have the correct tenant id
az account set -s <your-subscriptionId>                                    # Select your Azure Subscription
tenantId=$(az account show --query tenantId)                               # Get your tenantId
az keyvault update -n myvault --remove Properties.accessPolicies           # Remove the access policies
az keyvault update -n myvault --set Properties.tenantId=$tenantId          # Update the key vault tenantId

Update access policies and role assignments

Note

If Key Vault is using Azure RBAC permission model. You need to also remove key vault role assignments. You can remove role assignments using the Azure portal, Azure CLI, or PowerShell.

Now that your vault is associated with the correct tenant ID and old access policy entries or role assignments are removed, set new access policy entries or role assignments.

For assigning policies, see:

For adding role assignments, see:

Update managed identities

If you are transferring entire subscription and using a managed identity for Azure resources, you will need to update it to the new Microsoft Entra tenant as well. For more information on managed identities, Managed identity overview.

If you are using managed identity, you'll also have to update the identity because the old identity will no longer be in the correct Microsoft Entra tenant. See the following documents to help resolve this issue.

Next steps