Moving an Azure Key Vault to another subscription

Overview

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:

• 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

• About Azure Key Vault
• What is Microsoft Entra ID
• How to find tenant ID

Limitations

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

• Contributor level access or higher to the current subscription where your key vault exists. You can assign role using the Azure portal, Azure CLI, or PowerShell.
• Contributor level access or higher to the subscription where you want to move your key vault. You can assign role using the Azure portal, Azure CLI, or PowerShell.
• A resource group in the new subscription. You can create one using the Azure portal, PowerShell, or Azure CLI.

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 -Environment AzureChinaCloud                                                          #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

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:

• Assign an access policy using Portal
• Assign an access policy using Azure CLI
• Assign an access policy using PowerShell

For adding role assignments, see:

• Assign Azure roles using the Azure portal
• Assign Azure roles using Azure CLI
• Assign Azure roles using PowerShell

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.

• Updating MSI
• Transfer Subscription to New Directory

Next steps

• Learn more about keys, secrets, and certificates
• For conceptual information, including how to interpret Key Vault logs, see Key Vault logging
• Key Vault Developer's Guide
• Azure Key Vault security features
• Configure Azure Key Vault firewalls and virtual networks