Provide access to Key Vault keys, certificates, and secrets with an Azure role-based access control

Note

Key Vault resource provider supports two resource types: vaults and managed HSMs. Access control described in this article only applies to vaults. To learn more about access control for managed HSM, see Managed HSM access control.

Note

Azure App Service certificate configuration through Azure Portal does not support Key Vault RBAC permission model. You can use Azure PowerShell, Azure CLI, ARM template deployments with Key Vault Secrets User and Key Vault Reader role assignemnts for 'Microsoft Azure App Service' global indentity.

Azure role-based access control (Azure RBAC) is an authorization system built on Azure Resource Manager that provides fine-grained access management of Azure resources.

Azure RBAC allows users to manage Key, Secrets, and Certificates permissions. It provides one place to manage all permissions across all key vaults.

The Azure RBAC model allows uses to set permissions on different scope levels: management group, subscription, resource group, or individual resources. Azure RBAC for key vault also allows users to have separate permissions on individual keys, secrets, and certificates

For more information, see Azure role-based access control (Azure RBAC).

Best Practices for individual keys, secrets, and certificates role assignments

Our recommendation is to use a vault per application per environment (Development, Pre-Production, and Production).

Individual keys, secrets, and certificates permissions should be used only for specific scenarios:

• Sharing individual secrets between multiple applications, for example, one application needs to access data from the other application

More about Azure Key Vault management guidelines, see:

• Azure Key Vault best practices
• Azure Key Vault service limits

Azure built-in roles for Key Vault data plane operations

Note

The Key Vault Contributor role is for management plane operations to manage key vaults. It does not allow access to keys, secrets and certificates.

Built-in role	Description	ID
Key Vault Administrator	Perform all data plane operations on a key vault and all objects in it, including certificates, keys, and secrets. Cannot manage key vault resources or manage role assignments. Only works for key vaults that use the 'Azure role-based access control' permission model.	00482a5a-887f-4fb3-b363-3b7fe8e74483
Key Vault Certificates Officer	Perform any action on the certificates of a key vault, except manage permissions. Only works for key vaults that use the 'Azure role-based access control' permission model.	a4417e6f-fecd-4de8-b567-7b0420556985
Key Vault Crypto Officer	Perform any action on the keys of a key vault, except manage permissions. Only works for key vaults that use the 'Azure role-based access control' permission model.	14b46e9e-c2b7-41b4-b07b-48a6ebf60603
Key Vault Crypto Service Encryption User	Read metadata of keys and perform wrap/unwrap operations. Only works for key vaults that use the 'Azure role-based access control' permission model.	e147488a-f6f5-4113-8e2d-b22465e65bf6
Key Vault Crypto User	Perform cryptographic operations using keys. Only works for key vaults that use the 'Azure role-based access control' permission model.	12338af0-0e69-4776-bea7-57ae8d297424
Key Vault Reader	Read metadata of key vaults and its certificates, keys, and secrets. Cannot read sensitive values such as secret contents or key material. Only works for key vaults that use the 'Azure role-based access control' permission model.	21090545-7ca7-4776-b22c-e363652d74d2
Key Vault Secrets Officer	Perform any action on the secrets of a key vault, except manage permissions. Only works for key vaults that use the 'Azure role-based access control' permission model.	b86a8fe4-44ce-4948-aee5-eccb2c155cd7
Key Vault Secrets User	Read secret contents including secret portion of a certificate with private key. Only works for key vaults that use the 'Azure role-based access control' permission model.	4633458b-17de-408a-b874-0445c86b69e6

Note

There is no Key Vault Certificate User because applications require secrets portion of certificate with private key. The Key Vault Secrets User role should be used for applications to retrieve certificate.

For more information about Azure built-in roles definitions, see Azure built-in roles.

Using Azure RBAC secret, key, and certificate permissions with Key Vault

The new Azure RBAC permission model for key vault provides alternative to the vault access policy permissions model.

Prerequisites

You must have an Azure subscription. If you don't, you can create a free account before you begin.

To add role assignments, you must have Microsoft.Authorization/roleAssignments/write and Microsoft.Authorization/roleAssignments/delete permissions, such as User Access Administrator or Owner.

Enable Azure RBAC permissions on Key Vault

Note

Changing permission model requires 'Microsoft.Authorization/roleAssignments/write' permission, which is part of Owner and User Access Administrator roles. Classic subscription administrator roles like 'Service Administrator' and 'Co-Administrator' are not supported.

1. Enable Azure RBAC permissions on new key vault:

   

2. Enable Azure RBAC permissions on existing key vault:

   

Important

Setting Azure RBAC permission model invalidates all access policies permissions. It can cause outages when equivalent Azure roles aren't assigned.

Assign role

Note

It's recommended to use the unique role ID instead of the role name in scripts. Therefore, if a role is renamed, your scripts would continue to work. In this document role name is used only for readability.

Run the following command to create a role assignment:

Azure CLI

az role assignment create --role <role_name_or_id> --assignee <assignee> --scope <scope>

For full details, see Assign Azure roles using Azure CLI.

Azure PowerShell

#Assign by User Principal Name
New-AzRoleAssignment -RoleDefinitionName <role_name> -SignInName <assignee_upn> -Scope <scope>

#Assign by Service Principal ApplicationId
New-AzRoleAssignment -RoleDefinitionName Reader -ApplicationId <applicationId> -Scope <scope>

For full details, see Assign Azure roles using Azure PowerShell.

To assign roles using the Azure portal, see Assign Azure roles using the Azure portal. In the Azure portal, the Azure role assignments screen is available for all resources on the Access control (IAM) tab.

Resource group scope role assignment

1. Go to the Resource Group that contains your key vault.

   

2. Select Access control (IAM).

3. Select Add > Add role assignment to open the Add role assignment page.

4. Assign the following role. For detailed steps, see Assign Azure roles using the Azure portal.

   Setting	Value
   Role	"Key Vault Reader"
   Assign access to	Current user
   Members	Search by email address

   

Azure CLI

az role assignment create --role "Key Vault Reader" --assignee {i.e user@microsoft.com} --scope /subscriptions/{subscriptionid}/resourcegroups/{resource-group-name}

For full details, see Assign Azure roles using Azure CLI.

Azure PowerShell

#Assign by User Principal Name
New-AzRoleAssignment -RoleDefinitionName 'Key Vault Reader' -SignInName {i.e user@microsoft.com} -Scope /subscriptions/{subscriptionid}/resourcegroups/{resource-group-name}

#Assign by Service Principal ApplicationId
New-AzRoleAssignment -RoleDefinitionName 'Key Vault Reader' -ApplicationId {i.e 8ee5237a-816b-4a72-b605-446970e5f156} -Scope /subscriptions/{subscriptionid}/resourcegroups/{resource-group-name}

For full details, see Assign Azure roles using Azure PowerShell.

Above role assignment provides ability to list key vault objects in key vault.

Key Vault scope role assignment

1. Go to Key Vault > Access control (IAM) tab

2. Select Add > Add role assignment to open the Add role assignment page.

3. Assign the following role. For detailed steps, see Assign Azure roles using the Azure portal.

   Setting	Value
   Role	"Key Vault Secrets Officer"
   Assign access to	Current user
   Members	Search by email address

   

Azure CLI

az role assignment create --role "Key Vault Secrets Officer" --assignee {i.e jalichwa@microsoft.com} --scope /subscriptions/{subscriptionid}/resourcegroups/{resource-group-name}/providers/Microsoft.KeyVault/vaults/{key-vault-name}

For full details, see Assign Azure roles using Azure CLI.

Azure PowerShell

#Assign by User Principal Name
New-AzRoleAssignment -RoleDefinitionName 'Key Vault Secrets Officer' -SignInName {i.e user@microsoft.com} -Scope /subscriptions/{subscriptionid}/resourcegroups/{resource-group-name}/providers/Microsoft.KeyVault/vaults/{key-vault-name}

#Assign by Service Principal ApplicationId
New-AzRoleAssignment -RoleDefinitionName 'Key Vault Secrets Officer' -ApplicationId {i.e 8ee5237a-816b-4a72-b605-446970e5f156} -Scope /subscriptions/{subscriptionid}/resourcegroups/{resource-group-name}/providers/Microsoft.KeyVault/vaults/{key-vault-name}

For full details, see Assign Azure roles using Azure PowerShell.

Secret scope role assignment

Note

Key vault secret, certificate, key scope role assignments should only be used for limited scenarios described here to comply with security best practices.

1. Open a previously created secret.

2. Click the Access control(IAM) tab

   

3. Select Add > Add role assignment to open the Add role assignment page.

4. Assign the following role. For detailed steps, see Assign Azure roles using the Azure portal.

   Setting	Value
   Role	"Key Vault Secrets Officer"
   Assign access to	Current user
   Members	Search by email address

   

Azure CLI

az role assignment create --role "Key Vault Secrets Officer" --assignee {i.e user@microsoft.com} --scope /subscriptions/{subscriptionid}/resourcegroups/{resource-group-name}/providers/Microsoft.KeyVault/vaults/{key-vault-name}/secrets/RBACSecret

For full details, see Assign Azure roles using Azure CLI.

Azure PowerShell

#Assign by User Principal Name
New-AzRoleAssignment -RoleDefinitionName 'Key Vault Secrets Officer' -SignInName {i.e user@microsoft.com} -Scope /subscriptions/{subscriptionid}/resourcegroups/{resource-group-name}/providers/Microsoft.KeyVault/vaults/{key-vault-name}/secrets/RBACSecret

#Assign by Service Principal ApplicationId
New-AzRoleAssignment -RoleDefinitionName 'Key Vault Secrets Officer' -ApplicationId {i.e 8ee5237a-816b-4a72-b605-446970e5f156} -Scope /subscriptions/{subscriptionid}/resourcegroups/{resource-group-name}/providers/Microsoft.KeyVault/vaults/{key-vault-name}/secrets/RBACSecret

For full details, see Assign Azure roles using Azure PowerShell.

Test and verify

Note

Browsers use caching and page refresh is required after removing role assignments.
Allow several minutes for role assignments to refresh

1. Validate adding new secret without "Key Vault Secrets Officer" role on key vault level.

   1. Go to key vault Access control (IAM) tab and remove "Key Vault Secrets Officer" role assignment for this resource.

      

   2. Navigate to previously created secret. You can see all secret properties.

      

   3. Create new secret ( Secrets > +Generate/Import) should show this error:

      

2. Validate secret editing without "Key Vault Secret Officer" role on secret level.

   1. Go to previously created secret Access Control (IAM) tab and remove "Key Vault Secrets Officer" role assignment for this resource.

   2. Navigate to previously created secret. You can see secret properties.

      

3. Validate secrets read without reader role on key vault level.

   1. Go to key vault resource group Access control (IAM) tab and remove "Key Vault Reader" role assignment.

   2. Navigating to key vault's Secrets tab should show this error:

      

Creating custom roles

az role definition create command

Azure CLI

az role definition create --role-definition '{ \
   "Name": "Backup Keys Operator", \
   "Description": "Perform key backup/restore operations", \
    "Actions": [ 
    ], \
    "DataActions": [ \
        "Microsoft.KeyVault/vaults/keys/read ", \
        "Microsoft.KeyVault/vaults/keys/backup/action", \
         "Microsoft.KeyVault/vaults/keys/restore/action" \
    ], \
    "NotDataActions": [ 
   ], \
    "AssignableScopes": ["/subscriptions/{subscriptionId}"] \
}'

Azure PowerShell

$roleDefinition = @"
{ 
   "Name": "Backup Keys Operator", 
   "Description": "Perform key backup/restore operations", 
    "Actions": [ 
    ], 
    "DataActions": [ 
        "Microsoft.KeyVault/vaults/keys/read ", 
        "Microsoft.KeyVault/vaults/keys/backup/action", 
         "Microsoft.KeyVault/vaults/keys/restore/action" 
    ], 
    "NotDataActions": [ 
   ], 
    "AssignableScopes": ["/subscriptions/{subscriptionId}"] 
}
"@

$roleDefinition | Out-File role.json

New-AzRoleDefinition -InputFile role.json

For more Information about how to create custom roles, see:

Azure custom roles

Known limits and performance

• Key Vault data plane RBAC is not supported in multi tenant scenarios like with Azure Lighthouse
• 4000 Azure role assignments per subscription
• Role assignments latency: at current expected performance, it will take up to 10 minutes (600 seconds) after role assignments is changed for role to be applied

Frequently Asked Questions:

Can I use Key Vault role-based access control (RBAC) permission model object-scope assignments to provide isolation for application teams within Key Vault?

No. RBAC permission model allows you to assign access to individual objects in Key Vault to user or application, but any administrative operations like network access control, monitoring, and objects management require vault level permissions, which will then expose secure information to operators across application teams.

Learn more

• Azure RBAC Overview
• Assign Azure roles using the Azure portal
• Custom Roles Tutorial
• Azure Key Vault best practices