Migrate from vault access policy to an Azure role-based access control permission model

Article
2025-04-23

Azure Key Vault offers two authorization systems: Azure role-based access control (Azure RBAC), and an access policy model. Azure RBAC is the default and recommended authorization system for Azure Key Vault. For a comparison of the two methods of authorization, see Azure role-based access control (Azure RBAC) vs. access policies.

This article provides the information necessary to migrate a key vault from an access policy model to an Azure RBAC model.

Access policies to Azure roles mapping

Azure RBAC has several Azure built-in roles that you can assign to users, groups, service principals, and managed identities. If the built-in roles don't meet the specific needs of your organization, you can create your own Azure custom roles.

Key Vault built-in roles for keys, certificates, and secrets access management:

Key Vault Administrator
Key Vault Reader
Key Vault Purge Operator
Key Vault Certificates Officer
Key Vault Certificate User
Key Vault Crypto Officer
Key Vault Crypto User
Key Vault Crypto Service Encryption User
Key Vault Crypto Service Release User
Key Vault Secrets Officer
Key Vault Secrets User

For more information about existing built-in roles, see Azure built-in roles

Vault access policies can be assigned with individually selected permissions or with predefined permission templates.

Access policy predefined permission templates:

Key, Secret, Certificate Management
Key & Secret Management
Secret & Certificate Management
Key Management
Secret Management
Certificate Management
SQL Server Connector
Azure Data Lake Storage or Azure Storage
Azure Backup
Exchange Online Customer Key
SharePoint Online Customer Key
Azure Information BYOK

Access policy templates to Azure roles mapping

Access policy template	Operations	Azure role
Key, Secret, Certificate Management	Keys: all operations Certificates: all operations Secrets: all operations	Key Vault Administrator
Key & Secret Management	Keys: all operations Secrets: all operations	Key Vault Crypto Officer Key Vault Secrets Officer
Secret & Certificate Management	Certificates: all operations Secrets: all operations	Key Vault Certificates Officer Key Vault Secrets Officer
Key Management	Keys: all operations	Key Vault Crypto Officer
Secret Management	Secrets: all operations	Key Vault Secrets Officer
Certificate Management	Certificates: all operations	Key Vault Certificates Officer
SQL Server Connector	Keys: get, list, wrap key, unwrap key	Key Vault Crypto Service Encryption User
Azure Data Lake Storage or Azure Storage	Keys: get, list, unwrap key	N/A Custom role required
Azure Backup	Keys: get, list, backup Secrets: get, list, backup	N/A Custom role required
Exchange Online Customer Key	Keys: get, list, wrap key, unwrap key	Key Vault Crypto Service Encryption User
Exchange Online Customer Key	Keys: get, list, wrap key, unwrap key	Key Vault Crypto Service Encryption User
Azure Information BYOK	Keys: get, decrypt, sign	N/A Custom role required

Assignment scopes mapping

Azure RBAC for Key Vault allows roles assignment at following scopes:

Management group
Subscription
Resource group
Key Vault resource
Individual key, secret, and certificate

The vault access policy permission model is limited to assigning policies only at Key Vault resource level.

In general, it's best practice to have one key vault per application and manage access at key vault level. There are scenarios when managing access at other scopes can simplify access management.

Infrastructure, security administrators and operators: managing group of key vaults at management group, subscription or resource group level with vault access policies requires maintaining policies for each key vault. Azure RBAC allows creating one role assignment at management group, subscription, or resource group. That assignment will apply to any new key vaults created under the same scope. In this scenario, it's recommended to use Privileged Identity Management with just-in time access over providing permanent access.
Applications: there are scenarios when application would need to share secret with other application. Using vault access polices separate key vault had to be created to avoid giving access to all secrets. Azure RBAC allows assign role with scope for individual secret instead using single key vault.

How to migrate

Follow these steps to migrate your key vault to RBAC from access policies:

Prepare: Ensure you have proper permissions, and an inventory of your applications.
Inventory: Document all existing access policies and permissions.
Create RBAC roles: Assign appropriate RBAC roles to each security principal.
Enable RBAC: Switch the key vault to use the RBAC permission model.
Validate: Test access to ensure all applications and users retain appropriate access.
Monitor: Set up monitoring and alerting for access issues.

Prerequisites

Before starting the migration, ensure you have:

Required permissions: You must have the following permissions on the key vault:
- Microsoft.Authorization/roleAssignments/write permission, included in Owner and User Access Administrator roles
- Microsoft.KeyVault/vaults/write permission, included in the Key Vault Contributor role
Note

Classic subscription administrator roles (Service Administrator and Co-Administrator) are not supported.
Inventory of applications and identities: List all applications, services, and users that access the key vault, and document all current access policies and the permissions they grant.

Inventory current access policies

Document all existing access policies, noting the security principals (users, groups, service principals) and their permissions.

Use the Azure CLI az keyvault show command to retrieve the access policies:

# List all current access policies
az keyvault show --name <vault-name> --resource-group <resource-group-name> --query properties.accessPolicies

Use the Get-AzKeyVault cmdlet to retrieve the access policies:

# List all current access policies
$vault = Get-AzKeyVault -VaultName "<vault-name>" -ResourceGroupName "<resource-group-name>"
$vault.AccessPolicies

Create equivalent RBAC role assignments

For each security principal with an access policy, create one or more RBAC role assignments based on the mapping table above.

Use the az role assignment create command to grant appropriate roles:

# Example for Key Vault Administrator role:
az role assignment create --role "Key Vault Administrator" --assignee "<object-id-or-email>" --scope "/subscriptions/<subscription-id>/resourceGroups/<resource-group-name>/providers/Microsoft.KeyVault/vaults/<vault-name>"

# Example for Key Vault Secrets Officer:
az role assignment create --role "Key Vault Secrets Officer" --assignee "<object-id-or-email>" --scope "/subscriptions/<subscription-id>/resourceGroups/<resource-group-name>/providers/Microsoft.KeyVault/vaults/<vault-name>"

# Example for Key Vault Crypto Officer:
az role assignment create --role "Key Vault Crypto Officer" --assignee "<object-id-or-email>" --scope "/subscriptions/<subscription-id>/resourceGroups/<resource-group-name>/providers/Microsoft.KeyVault/vaults/<vault-name>"

# Example for Key Vault Certificates Officer:
az role assignment create --role "Key Vault Certificates Officer" --assignee "<object-id-or-email>" --scope "/subscriptions/<subscription-id>/resourceGroups/<resource-group-name>/providers/Microsoft.KeyVault/vaults/<vault-name>"

Use the New-AzRoleAssignment cmdlet to grant appropriate roles:

# Example for Key Vault Administrator role:
New-AzRoleAssignment -RoleDefinitionName "Key Vault Administrator" -ObjectId "<object-id>" -Scope "/subscriptions/<subscription-id>/resourceGroups/<resource-group-name>/providers/Microsoft.KeyVault/vaults/<vault-name>"

# Example for Key Vault Secrets Officer:
New-AzRoleAssignment -RoleDefinitionName "Key Vault Secrets Officer" -ObjectId "<object-id>" -Scope "/subscriptions/<subscription-id>/resourceGroups/<resource-group-name>/providers/Microsoft.KeyVault/vaults/<vault-name>"

# Example for Key Vault Crypto Officer:
New-AzRoleAssignment -RoleDefinitionName "Key Vault Crypto Officer" -ObjectId "<object-id>" -Scope "/subscriptions/<subscription-id>/resourceGroups/<resource-group-name>/providers/Microsoft.KeyVault/vaults/<vault-name>"

# Example for Key Vault Certificates Officer:
New-AzRoleAssignment -RoleDefinitionName "Key Vault Certificates Officer" -ObjectId "<object-id>" -Scope "/subscriptions/<subscription-id>/resourceGroups/<resource-group-name>/providers/Microsoft.KeyVault/vaults/<vault-name>"

Enable RBAC permission model

After creating all necessary role assignments, switch the vault to use the RBAC permission model.

Use the az keyvault update command to enable RBAC:

# Switch the vault to RBAC permission model
az keyvault update --name <vault-name> --resource-group <resource-group-name> --enable-rbac-authorization true

Use the Update-AzKeyVault cmdlet to enable RBAC:

# Switch the vault to RBAC permission model
$vault = Get-AzKeyVault -VaultName "<vault-name>" -ResourceGroupName "<resource-group-name>"
Update-AzKeyVault -VaultName $vault.VaultName -ResourceGroupName $vault.ResourceGroupName -EnableRbacAuthorization $true

Validate access

Test access to the vault to ensure all applications and users can still perform required operations.

Test your access with these commands:

# Try to list secrets to verify access
az keyvault secret list --vault-name <vault-name>

# Try to get a secret to verify access
az keyvault secret show --vault-name <vault-name> --name <secret-name>

Test your access with these cmdlets:

# Try to list secrets to verify access
Get-AzKeyVaultSecret -VaultName "<vault-name>"

# Try to get a secret to verify access
Get-AzKeyVaultSecret -VaultName "<vault-name>" -Name "<secret-name>"

Set up monitoring and alerting

After migration, set up proper monitoring to detect any access issues:

Use the az monitor diagnostic-settings create command:

# Enable diagnostics logging for Key Vault
az monitor diagnostic-settings create --resource <vault-id> --name KeyVaultLogs --logs "[{\"category\":\"AuditEvent\",\"enabled\":true}]" --workspace <log-analytics-workspace-id>

Use the Set-AzDiagnosticSetting cmdlet:

# Get the vault resource ID
$vaultResourceId = (Get-AzKeyVault -VaultName "<vault-name>" -ResourceGroupName "<resource-group-name>").ResourceId

# Enable diagnostics logging for Key Vault
$logs = @()
$logs += New-AzDiagnosticSettingLogSettingsObject -Category "AuditEvent" -Enabled $true
Set-AzDiagnosticSetting -ResourceId $vaultResourceId -Name "KeyVaultLogs" -WorkspaceId "<log-analytics-workspace-id>" -Log $logs

Migration governance with Azure Policy

Using the Azure Policy service, you can govern RBAC permission model migration across your vaults. You can create a custom policy definition to audit existing key vaults and enforce all new key vaults to use the Azure RBAC permission model.

Create and assign policy definition for Key Vault Azure RBAC permission model

Navigate to Policy resource
Select Assignments under Authoring on the left side of the Azure Policy page
Select Assign policy at the top of the page
Enter the following information:
- Define the scope of the policy by choosing the subscription and resource group
- Select the policy definition: "[Preview]: Azure Key Vault should use RBAC permission model"
- Define the desired effect of the policy (Audit, Deny, or Disabled)
Complete the assignment by reviewing and creating it

Once the policy is assigned, it can take up to 24 hours to complete the scan. After the scan is completed, you can see compliance results in the Azure Policy dashboard.

Access Policy to Azure RBAC Comparison Tool

Important

This tool is build and maintained by Microsoft Community members and without formal Customer Support Services support. The tool is provided AS IS without warranty of any kind.

PowerShell tool to compare Key Vault access policies to assigned RBAC roles to help with Access Policy to RBAC Permission Model migration. The tool intent is to provide sanity check when migrating existing Key Vault to RBAC permission model to ensure that assigned roles with underlying data actions cover existing Access Policies.

Troubleshooting common issues

Role assignment delay: Role assignments can take several minutes to propagate. Implement retry logic in your applications.
Lost role assignments after recovery: Role assignments are not preserved when a vault is recovered after soft-delete. You must recreate all role assignments after recovery.
Access denied errors: Check that:
- The correct roles are assigned at the right scope
- The service principal or managed identity has the exact permissions needed
- Network access rules are not blocking your connection
Scripts fail after migration: Update any scripts that used access policies to use role assignments instead.

Share via