Moving an Azure Key Vault to another subscription
This article has been updated to use the Azure Az PowerShell module. The Az PowerShell module is the recommended PowerShell module for interacting with Azure. To get started with the Az PowerShell module, see Install Azure PowerShell. To learn how to migrate to the Az PowerShell module, see Migrate Azure PowerShell from AzureRM to Az.
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 Azure Active Directory 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:
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 Azure Active Directory, see
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 is a chance that you will not 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.
- Contributor level access or higher to the current subscription where your key vault exists. You can assign role using 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 Azure portal, Azure CLI, or PowerShell.
- A resource group in the new subscription. You can create one using Azure portal, PowerShell, or Azure CLI.
Moving a key vault to a new subscription
- Sign in to the Azure portal at https://portal.azure.com.
- Navigate to your key vault
- Click on the "Overview" tab
- Select the "Move" button
- Select "Move to another subscription" from the dropdown options
- Select the resource group where you want to move your key vault
- Acknowledge the warning regarding moving resources
- Select "OK"
Additional steps when subscription is in a new tenant
If you moved your key vault to a subscription in 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 documented below 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
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 Azure Active Directory 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 Azure Active Directory tenant. See the following documents to help resolve this issue.
- 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