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

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.

Vault access policy to Azure RBAC migration steps

There are many differences between Azure RBAC and vault access policy permission model. In order, to avoid outages during migration, below steps are recommended.

1. Identify and assign roles: identify built-in roles based on mapping table above and create custom roles when needed. Assign roles at scopes, based on scopes mapping guidance. For more information on how to assign roles to key vault, see Provide access to Key Vault with an Azure role-based access control
2. Validate roles assignment: role assignments in Azure RBAC can take several minutes to propagate. For guide how to check role assignments, see List roles assignments at scope
3. Configure monitoring and alerting on key vault: it's important to enable logging and setup alerting for access denied exceptions. For more information, see Monitoring and alerting for Azure Key Vault
4. Set Azure role-based access control permission model on Key Vault: enabling Azure RBAC permission model will invalidate all existing access policies. If an error, permission model can be switched back with all existing access policies remaining untouched.

Prerequisites

Changing a key vault's permission model requires two permissions:

• The 'Microsoft.Authorization/roleAssignments/write' permission, which is included in the Owner role and User Access Administrator role.
• The 'Microsoft.KeyVault/vaults/write' permission, which is included in the Key Vault Contributor role.

Classic subscription administrator roles like 'Service Administrator' and 'Co-Administrator' are not supported.

Migration governance

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

1. Navigate to Policy resource
2. Select Assignments under Authoring on the left side of the Azure Policy page.
3. Select Assign policy at the top of the page. This button opens to the Policy assignment page.
4. Enter the following information:
   • Define the scope of the policy by choosing the subscription and resource group over which the policy will be enforced. Select by clicking the three-dot button at on Scope field.
   • Select the name of the policy definition: "[Preview]: Azure Key Vault should use RBAC permission model"
   • Go to the Parameters tab at the top of the page and define the desired effect of the policy (Audit, Deny, or Disabled).
5. Fill out any additional fields. Navigate the tabs clicking on Previous and Next buttons at the bottom of the page.
6. Select Review + create
7. Select Create

Once the built-in policy is assigned, it can take up to 24 hours to complete the scan. After the scan is completed, you can see compliance results like below.

For more information, see

• Integrate Azure Key Vault with Azure Policy

Access Policy to Azure RBAC Comparison Tool

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

• Role assignment not working after several minutes - there are situations when role assignments can take longer. It's important to write retry logic in code to cover those cases.
• Role assignments disappeared when Key Vault was deleted (soft-delete) and recovered - it's currently a limitation of soft-delete feature across all Azure services. It's required to recreate all role assignments after recovery.

Learn more

• Azure RBAC Overview
• Custom Roles Tutorial
• Privileged Identity Management