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

> Compare Key Vault access policies with Azure RBAC, map policy templates to built-in roles, switch a vault to the RBAC permission model safely, and assign least-privilege roles.

Source: https://www.epifive.com/blog/azure-key-vault-rbac-vs-access-policies · Published 2026-10-25 · EpiFive

## Key takeaways

- Azure RBAC is the recommended Key Vault permission model, and from API version 2026-02-01 it is the default for newly created vaults.
- Switching a vault to Azure RBAC invalidates every access policy, so assign and test equivalent roles before you change the permission model.
- Key Vault Secrets User reads secrets, Secrets Officer manages them, Administrator does all data plane operations, and none of these roles can manage role assignments.
- Key Vault Contributor is a control plane role with no access to secrets, keys or certificates, but a Contributor can grant themselves data access on a vault that uses access policies.
- Assign roles at vault scope with one vault per application per environment, and use secret-level assignments only for the documented exceptions.

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.

| Area | Access policies | Azure RBAC |
|---|---|---|
| Scope | Key Vault resource only | Management group, subscription, resource group, vault, or an individual key, secret or certificate |
| Managing many vaults | A policy to maintain on each vault | One assignment at a higher scope covers new vaults created under it |
| Role set | Per-operation permission lists and templates | Built-in and custom roles |
| Administrator access | Permanent policy entries | Microsoft recommends Privileged Identity Management just-in-time access over permanent access for administrators at higher scopes |

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

| Role | What it allows |
|---|---|
| Key Vault Administrator | All data plane operations on the vault and all its objects. Cannot manage vault resources or role assignments. |
| Key Vault Reader | Read metadata of the vault and its certificates, keys and secrets. Cannot read secret contents or key material. |
| Key Vault Secrets Officer | Any action on secrets, except managing permissions. |
| Key Vault Secrets User | Read secret contents, including the secret portion of a certificate with its private key. |
| Key Vault Crypto Officer | Any action on keys, except managing permissions. |
| Key Vault Crypto User | Perform cryptographic operations using keys. |
| Key Vault Crypto Service Encryption User | Read key metadata and perform wrap and unwrap operations. |
| Key Vault Certificates Officer | Any action on certificates, except managing permissions. |
| Key Vault Certificate User | Read entire certificate contents, including the secret and key portion. |
| Key Vault Purge Operator | Permanently delete soft-deleted vaults. |
| Key Vault Crypto Service Release User | Release keys for Azure Confidential Computing and equivalent environments. |

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:

| Access policy template | Azure role |
|---|---|
| Key, Secret, Certificate Management | Key Vault Administrator |
| Key & Secret Management | Key Vault Crypto Officer and Key Vault Secrets Officer |
| Secret & Certificate Management | Key Vault Certificates Officer and Key Vault Secrets Officer |
| Key Management | Key Vault Crypto Officer |
| Secret Management | Key Vault Secrets Officer |
| Certificate Management | Key Vault Certificates Officer |
| SQL Server Connector (keys: get, list, wrap, unwrap) | Key Vault Crypto Service Encryption User |
| Exchange Online Customer Key (keys: get, list, wrap, unwrap) | Key Vault Crypto Service Encryption User |
| Azure Data Lake Storage or Azure Storage (keys: get, list, unwrap) | No built-in role; custom role required |
| Azure Backup (keys and secrets: get, list, backup) | No built-in role; custom role required |
| Azure Information BYOK (keys: get, decrypt, sign) | No built-in role; custom role required |

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

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

```powershell
$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.

```bash
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>"
```

```powershell
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.

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

```powershell
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

```bash
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:

```bash
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

| Who or what | Role | Scope |
|---|---|---|
| App that reads connection strings | Key Vault Secrets User | The application's vault |
| App that encrypts with a key (wrap, unwrap) | Key Vault Crypto Service Encryption User or Key Vault Crypto User | The vault, or the key |
| Secret rotation job that writes secrets | Key Vault Secrets Officer | The vault |
| TLS certificate renewal automation | Key Vault Certificates Officer | The vault |
| Security team auditing inventory | Key Vault Reader | Subscription or resource group |
| Administrator who occasionally manages secrets, keys and certificates | Key Vault Administrator, via PIM just-in-time | The vault |
| Platform team creating vaults | Key Vault Contributor (control plane only) | Resource group |

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

| Symptom | Cause and fix |
|---|---|
| Forbidden errors on every call right after the switch | Access policies stopped counting. Assign matching roles and wait several minutes for propagation. |
| Access denied although a role exists | Check the role is at the right scope, the assignment is for the right object ID, and network rules aren't blocking the connection. |
| Can't change the permission model | You lack unrestricted `roleAssignments/write`. Use Owner or User Access Administrator plus `vaults/write`. Classic admin roles don't work. |
| Role assignments gone after recovering a soft-deleted vault | Role assignments aren't preserved on recovery. Recreate them. |
| Scripts still call `az keyvault set-policy` | Update scripts to create role assignments instead. |
| Storage encryption or Backup stopped working | Their policy templates have no built-in role. Create a custom role with the needed data actions. |
| A secret exists but the portal shows an error on the Secrets tab | The user lacks a role that lists or reads secrets, and Key Vault Reader alone shows metadata only. |

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

## Frequently asked questions

### What is the difference between Key Vault access policies and Azure RBAC?

Access policies are a legacy per-vault permission list that you can set only at the vault level. Azure RBAC uses role assignments that can be made at management group, subscription, resource group, vault, or even individual secret, key and certificate scope, with one place to manage permissions across all vaults. Azure RBAC is the recommended model and the default for new vaults from API version 2026-02-01.

### What happens to my access policies when I enable Azure RBAC?

Setting the Azure RBAC permission model invalidates all access policy permissions. Anything that relied on a policy loses data plane access unless an equivalent role is assigned, which can cause an outage. Create and verify the role assignments first, then switch the model.

### Which role gives an app read-only access to secrets?

Key Vault Secrets User lets an identity read secret contents, including the secret portion of a certificate with its private key. It cannot create or change secrets. Assign it to the app's managed identity at the vault scope, or at a single secret when the app needs only one value.

### Who can change a Key Vault's permission model to Azure RBAC?

You need unrestricted Microsoft.Authorization/roleAssignments/write permission, which Owner and User Access Administrator include. With User Access Administrator you also need Microsoft.KeyVault/vaults/write, which Key Vault Contributor includes. Classic administrator roles and the restricted Key Vault Data Access Administrator cannot change it.