Azure Key Vault RBAC vs Access Policies: Migrate and Assign Roles

To switch an Azure Key Vault from access policies to Azure RBAC, first record the existing policies, assign equivalent built-in roles such as Key Vault Secrets User or Key Vault Crypto Officer to each identity at the vault scope, then change the vault's permission model to Azure role-based access control. The switch invalidates every access policy at once, so the order matters.

Who this is for and what you will have at the end

This guide is for cloud and security administrators who inherit vaults that use access policies, or who build new ones and want least-privilege access for people, apps and managed identities.

At the end you will have:

• A clear comparison of the two permission models.
• A table mapping access policy templates to built-in roles.
• An ordered migration procedure with CLI and PowerShell commands.
• Least-privilege role choices for common cases and a troubleshooting list.

Why Azure RBAC

Key Vault has two access control models for the data plane: Azure RBAC and the legacy access policy model. Microsoft calls Azure RBAC the default and recommended model, and starting with API version 2026-02-01 it is the default for new vaults. Check the "Prepare for Key Vault API version 2026-02-01 and later" page if you create vaults through templates or scripts, because their behavior can change.

Control plane versus data plane

Access to a vault goes through two independent planes.

• The control plane manages the vault itself: create and delete vaults, read properties, set tags, and set access policies. It uses Azure RBAC.
• The data plane works with the keys, secrets and certificates inside the vault. It uses an access policy (legacy) or Azure RBAC for data plane operations.

Because the planes work independently, granting someone Reader on the vault does not let them read secrets, and a data plane role does not let them delete the vault.

Important security note from Microsoft: on a vault that uses access policies, a user with Contributor rights on the control plane can grant themselves data plane access by setting an access policy. Tightly control who has Contributor on vaults.

Prerequisites

To change the permission model you need:

• Microsoft.Authorization/roleAssignments/write, included in Owner and User Access Administrator.
• Microsoft.KeyVault/vaults/write, included in Key Vault Contributor, if you are using User Access Administrator.

Classic subscription administrator roles (Service Administrator and Co-Administrator) and the restricted Key Vault Data Access Administrator can't change the permission model. To manage role assignments in general you need roleAssignments/write and roleAssignments/delete, which Key Vault Data Access Administrator (restricted to Key Vault roles), User Access Administrator and Owner provide.

You also need an inventory of every app, service and person that uses the vault. Missing one identity is the usual cause of migration outages.

Built-in roles for the data plane

These data plane roles work only on vaults that use the Azure RBAC permission model. Key Vault Contributor is a different role: it is for control plane operations only and gives no access to keys, secrets or certificates. Key Vault Data Access Administrator manages role assignments for a defined set of Key Vault roles and includes an ABAC condition that constrains what it can assign.

Map access policies to roles

Use this mapping from Microsoft's migration guide:

Policies with individually selected permissions rather than a template need a manual comparison. A community-maintained PowerShell tool exists (the KeyVault-AccessPolicyToRBAC-CompareTool on GitHub) to check that assigned roles cover existing policies. Microsoft states it is provided as-is with no formal support, so use it as a sanity check only.

Step-by-step migration

Step 1: Inventory the current policies

az keyvault show --name <vault-name> --resource-group <resource-group> --query properties.accessPolicies

$vault = Get-AzKeyVault -VaultName "<vault-name>" -ResourceGroupName "<resource-group>"
$vault.AccessPolicies

Record each identity (user, group, service principal, managed identity) and its key, secret and certificate permissions. In the portal, open the vault and select Access policies under Settings.

Step 2: Create equivalent role assignments

Assign roles at the vault scope. Prefer the role's unique ID in scripts, because roles can be renamed and an ID keeps scripts working.

az role assignment create \
  --role "Key Vault Secrets User" \
  --assignee "<object-id-of-managed-identity>" \
  --scope "/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.KeyVault/vaults/<vault-name>"

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

In the portal, open the vault, select Access control (IAM), then Add > Add role assignment, choose the role, choose the member, and select Review + assign.

Step 3: Enable Azure RBAC

Setting the Azure RBAC permission model invalidates all access policy permissions, and it can cause outages when equivalent roles aren't assigned. Complete step 2 for every identity first.

az keyvault update --name <vault-name> --resource-group <resource-group> --enable-rbac-authorization true

Update-AzKeyVault -VaultName "<vault-name>" -ResourceGroupName "<resource-group>" -EnableRbacAuthorization $true

In the portal, open the vault, select Properties under Settings, change Permission model to Azure role-based access control and select Save. The same setting is offered when you create a new vault.

Step 4: Validate

az keyvault secret list --vault-name <vault-name>
az keyvault secret show --vault-name <vault-name> --name <secret-name>

Test as the real identities (the app's managed identity, a CI pipeline, an operator), not only as yourself. Role assignments can take several minutes to propagate, so build retry logic into applications, and allow time before declaring a failure. Browsers cache, so refresh the portal after changing roles.

Step 5: Monitor

Send the AuditEvent log category to a Log Analytics workspace so you can spot access denied errors after migration:

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

Govern the rest with Azure Policy

A built-in definition named "[Preview]: Azure Key Vault should use Azure RBAC" can audit or deny vaults still on access policies. Assign it at a subscription or resource group scope and choose the effect (Audit, Deny or Disabled). The compliance scan can take up to 24 hours.

Least-privilege assignments

Microsoft's recommendation is one vault per application per environment (development, pre-production, production), with roles at the vault scope. Assigning roles on individual secrets, keys or certificates isn't recommended, apart from cases such as a user reading their own SSH private key for Azure Bastion, or one application sharing a secret with another. Object-level assignments aren't a way to isolate application teams within a shared vault, because administrative operations like network access control, monitoring and object management need vault-level permissions that expose the vault to operators across teams.

For managed identities in practice, see /blog/azure-openai-keyless-managed-identity-private-endpoint and /blog/workload-identity-federation-github-actions-azure.

Troubleshooting

Checklist

• Inventory every identity and its permissions.
• Assign equivalent roles and prefer role IDs in scripts.
• Create custom roles for Storage encryption, Backup and BYOK cases.
• Switch the permission model after role assignments exist.
• Test with the real identities and allow for propagation delay.
• Turn on AuditEvent logging.
• Assign the Azure Policy definition so new vaults use Azure RBAC.
• Restrict who holds Owner, User Access Administrator and Contributor on vaults.

References

• Migrate to Azure role-based access control: https://learn.microsoft.com/en-us/azure/key-vault/general/rbac-migration
• Grant permission to applications to access a key vault using Azure RBAC: https://learn.microsoft.com/en-us/azure/key-vault/general/rbac-guide
• Azure built-in roles: https://learn.microsoft.com/en-us/azure/role-based-access-control/built-in-roles