Secure access to a key vault

Azure Key Vault is a cloud service that safeguards encryption keys and secrets like certificates, connection strings, and passwords. Because this data is sensitive and business critical, you need to secure access to your key vaults by allowing only authorized applications and users. This article provides an overview of the Key Vault access model. It explains authentication and authorization, and describes how to secure access to your key vaults.

Note

This article has been updated to use the new Azure PowerShell Az module. To learn more about the new Az module and AzureRM compatibility, see Introducing the new Azure PowerShell Az module. For installation instructions, see Install Azure PowerShell.

Access model overview

Access to a key vault is controlled through two interfaces: the management plane and the data plane. The management plane is where you manage Key Vault itself. Operations in this plane include creating and deleting key vaults, retrieving Key Vault properties, and updating access policies. The data plane is where you work with the data stored in a key vault. You can add, delete, and modify keys, secrets, and certificates.

To access a key vault in either plane, all callers (users or applications) must have proper authentication and authorization. Authentication establishes the identity of the caller. Authorization determines which operations the caller can execute.

Both planes use Azure Active Directory (Azure AD) for authentication. For authorization, the management plane uses role-based access control (RBAC) and the data plane uses a Key Vault access policy.

Active Directory authentication

When you create a key vault in an Azure subscription, it's automatically associated with the Azure AD tenant of the subscription. All callers in both planes must register in this tenant and authenticate to access the key vault. In both cases, applications can access Key Vault in two ways:

  • User plus application access: The application accesses Key Vault on behalf of a signed-in user. Examples of this type of access include Azure PowerShell and the Azure portal. User access is granted in two ways. Users can access Key Vault from any application, or they must use a specific application (referred to as compound identity).
  • Application-only access: The application runs as a daemon service or background job. The application identity is granted access to the key vault.

For both types of access, the application authenticates with Azure AD. The application uses any supported authentication method based on the application type. The application acquires a token for a resource in the plane to grant access. The resource is an endpoint in the management or data plane, based on the Azure environment. The application uses the token and sends a REST API request to Key Vault. To learn more, review the whole authentication flow.

The model of a single mechanism for authentication to both planes has several benefits:

  • Organizations can control access centrally to all key vaults in their organization.
  • If a user leaves, they instantly lose access to all key vaults in the organization.
  • Organizations can customize authentication by using the options in Azure AD, such as to enable multi-factor authentication for added security.

Resource endpoints

Applications access the planes through endpoints. The access controls for the two planes work independently. To grant an application access to use keys in a key vault, you grant data plane access by using a Key Vault access policy. To grant a user read access to Key Vault properties and tags, but not access to data (keys, secrets, or certificates), you grant management plane access with RBAC.

The following table shows the endpoints for the management and data planes.

Access plane Access endpoints Operations Access control mechanism
Management plane Global:
management.azure.com:443

Azure China 21Vianet:
management.chinacloudapi.cn:443

Azure US Government:
management.usgovcloudapi.net:443

Azure Germany:
management.microsoftazure.de:443
Create, read, update, and delete key vaults

Set Key Vault access policies

Set Key Vault tags
Azure Resource Manager RBAC
Data plane Global:
<vault-name>.vault.azure.net:443

Azure China 21Vianet:
<vault-name>.vault.azure.cn:443

Azure US Government:
<vault-name>.vault.usgovcloudapi.net:443

Azure Germany:
<vault-name>.vault.microsoftazure.de:443
Keys: decrypt, encrypt,
unwrap, wrap, verify, sign,
get, list, update, create,
import, delete, backup, restore

Secrets: get, list, set, delete
Key Vault access policy

Management plane and RBAC

In the management plane, you use RBAC(Role Based Access Control) to authorize the operations a caller can execute. In the RBAC model, each Azure subscription has an instance of Azure AD. You grant access to users, groups, and applications from this directory. Access is granted to manage resources in the Azure subscription that use the Azure Resource Manager deployment model. To grant access, use the Azure portal, the Azure CLI, Azure PowerShell, or the Azure Resource Manager REST APIs.

You create a key vault in a resource group and manage access by using Azure AD. You grant users or groups the ability to manage the key vaults in a resource group. You grant the access at a specific scope level by assigning appropriate RBAC roles. To grant access to a user to manage key vaults, you assign a predefined key vault Contributor role to the user at a specific scope. The following scopes levels can be assigned to an RBAC role:

  • Subscription: An RBAC role assigned at the subscription level applies to all resource groups and resources within that subscription.
  • Resource group: An RBAC role assigned at the resource group level applies to all resources in that resource group.
  • Specific resource: An RBAC role assigned for a specific resource applies to that resource. In this case, the resource is a specific key vault.

There are several predefined roles. If a predefined role doesn't fit your needs, you can define your own role. For more information, see RBAC: Built-in roles.

Important

If a user has Contributor permissions to a key vault management plane, the user can grant themselves access to the data plane by setting a Key Vault access policy. You should tightly control who has Contributor role access to your key vaults. Ensure that only authorized persons can access and manage your key vaults, keys, secrets, and certificates.

Data plane and access policies

You grant data plane access by setting Key Vault access policies for a key vault. To set these access policies, a user, group, or application must have Contributor permissions for the management plane for that key vault.

You grant a user, group, or application access to execute specific operations for keys or secrets in a key vault. Key Vault supports up to 1,024 access policy entries for a key vault. To grant data plane access to several users, create an Azure AD security group and add users to that group.

Key Vault access policies grant permissions separately to keys, secrets, and certificate. You can grant a user access only to keys and not to secrets. Access permissions for keys, secrets, and certificates are at the vault level. Key Vault access policies don't support granular, object-level permissions like a specific key, secret, or certificate. To set access policies for a key vault, use the Azure portal, the Azure CLI, Azure PowerShell, or the Key Vault Management REST APIs.

Important

Key Vault access policies apply at the vault level. When a user is granted permission to create and delete keys, they can perform those operations on all keys in that key vault.

You can restrict data plane access by using virtual network service endpoints for Azure Key Vault. You can configure firewalls and virtual network rules for an additional layer of security.

Example

In this example, we're developing an application that uses a certificate for SSL, Azure Storage to store data, and an RSA 2,048-bit key for sign operations. Our application runs in an Azure virtual machine (VM) (or a virtual machine scale set). We can use a key vault to store the application secrets. We can store the bootstrap certificate that's used by the application to authenticate with Azure AD.

We need access to the following stored keys and secrets:

  • SSL certificate: Used for SSL.
  • Storage key: Used to access the Storage account.
  • RSA 2,048-bit key: Used for sign operations.
  • Bootstrap certificate: Used to authenticate with Azure AD. After access is granted, we can fetch the storage key and use the RSA key for signing.

We need to define the following roles to specify who can manage, deploy, and audit our application:

  • Security team: IT staff from the office of the CSO (Chief Security Officer) or similar contributors. The security team is responsible for the proper safekeeping of secrets. The secrets can include SSL certificates, RSA keys for signing, connection strings, and storage account keys.
  • Developers and operators: The staff who develop the application and deploy it in Azure. The members of this team aren't part of the security staff. They shouldn't have access to sensitive data like SSL certificates and RSA keys. Only the application that they deploy should have access to sensitive data.
  • Auditors: This role is for contributors who aren't members of the development or general IT staff. They review the use and maintenance of certificates, keys, and secrets to ensure compliance with security standards.

There's another role that's outside the scope of our application: the subscription (or resource group) administrator. The subscription admin sets up initial access permissions for the security team. They grant access to the security team by using a resource group that has the resources required by the application.

We need to authorize the following operations for our roles:

Security team

  • Create key vaults.
  • Turn on Key Vault logging.
  • Add keys and secrets.
  • Create backups of keys for disaster recovery.
  • Set Key Vault access policies to grant permissions to users and applications for specific operations.
  • Roll the keys and secrets periodically.

Developers and operators

  • Get references from the security team for the bootstrap and SSL certificates (thumbprints), storage key (secret URI), and RSA key (key URI) for signing.
  • Develop and deploy the application to access keys and secrets programmatically.

Auditors

  • Review the Key Vault logs to confirm proper use of keys and secrets, and compliance with data security standards.

The following table summarizes the access permissions for our roles and application.

Role Management plane permissions Data plane permissions
Security team Key Vault Contributor Keys: back up, create, delete, get, import, list, restore
Secrets: all operations
Developers and operators Key Vault deploy permission

Note: This permission allows deployed VMs to fetch secrets from a key vault.
None
Auditors None Keys: list
Secrets: list

Note: This permission enables auditors to inspect attributes (tags, activation dates, expiration dates) for keys and secrets not emitted in the logs.
Application None Keys: sign
Secrets: get

The three team roles need access to other resources along with Key Vault permissions. To deploy VMs (or the Web Apps feature of Azure App Service), developers and operators need Contributor access to those resource types. Auditors need read access to the Storage account where the Key Vault logs are stored.

For more information about how to deploy certificates, access keys, and secrets programmatically, see these resources:

You can grant most of the access permissions by using the Azure portal. To grant granular permissions, you can use Azure PowerShell or the Azure CLI.

The PowerShell snippets in this section are built with the following assumptions:

  • The Azure AD administrator has created security groups to represent the three roles: Contoso Security Team, Contoso App DevOps, and Contoso App Auditors. The admin has added users to their respective groups.
  • All resources are located in the ContosoAppRG resource group.
  • The Key Vault logs are stored in the contosologstorage storage account.
  • The ContosoKeyVault key vault and the contosologstorage storage account are in the same Azure location.

The subscription admin assigns the key vault Contributor and User Access Administrator roles to the security team. These roles allow the security team to manage access to other resources and key vaults, both of which in the ContosoAppRG resource group.

New-AzRoleAssignment -ObjectId (Get-AzADGroup -SearchString 'Contoso Security Team')[0].Id -RoleDefinitionName "key vault Contributor" -ResourceGroupName ContosoAppRG
New-AzRoleAssignment -ObjectId (Get-AzADGroup -SearchString 'Contoso Security Team')[0].Id -RoleDefinitionName "User Access Administrator" -ResourceGroupName ContosoAppRG

The security team creates a key vault and sets up logging and access permissions. For details about Key Vault access policy permissions, see About Azure Key Vault keys, secrets, and certificates.

# Create a key vault and enable logging
$sa = Get-AzStorageAccount -ResourceGroup ContosoAppRG -Name contosologstorage
$kv = New-AzKeyVault -Name ContosoKeyVault -ResourceGroup ContosoAppRG -SKU premium -Location 'westus' -EnabledForDeployment
Set-AzDiagnosticSetting -ResourceId $kv.ResourceId -StorageAccountId $sa.Id -Enabled $true -Category AuditEvent

# Set up data plane permissions for the Contoso Security Team role
Set-AzKeyVaultAccessPolicy -VaultName ContosoKeyVault -ObjectId (Get-AzADGroup -SearchString 'Contoso Security Team')[0].Id -PermissionsToKeys backup,create,delete,get,import,list,restore -PermissionsToSecrets get,list,set,delete,backup,restore,recover,purge

# Set up management plane permissions for the Contoso App DevOps role
# Create the new role from an existing role
$devopsrole = Get-AzRoleDefinition -Name "Virtual Machine Contributor"
$devopsrole.Id = $null
$devopsrole.Name = "Contoso App DevOps"
$devopsrole.Description = "Can deploy VMs that need secrets from a key vault"
$devopsrole.AssignableScopes = @("/subscriptions/<SUBSCRIPTION-GUID>")

# Add permissions for the Contoso App DevOps role so members can deploy VMs with secrets deployed from key vaults
$devopsrole.Actions.Add("Microsoft.KeyVault/vaults/deploy/action")
New-AzRoleDefinition -Role $devopsrole

# Assign the new role to the Contoso App DevOps security group
New-AzRoleAssignment -ObjectId (Get-AzADGroup -SearchString 'Contoso App Devops')[0].Id -RoleDefinitionName "Contoso App Devops" -ResourceGroupName ContosoAppRG

# Set up data plane permissions for the Contoso App Auditors role
Set-AzKeyVaultAccessPolicy -VaultName ContosoKeyVault -ObjectId (Get-AzADGroup -SearchString 'Contoso App Auditors')[0].Id -PermissionsToKeys list -PermissionsToSecrets list

Our defined custom roles are assignable only to the subscription where the ContosoAppRG resource group is created. To use a custom role for other projects in other subscriptions, add other subscriptions to the scope for the role.

For our DevOps staff, the custom role assignment for the key vault deploy/action permission is scoped to the resource group. Only VMs created in the ContosoAppRG resource group are allowed access to the secrets (SSL and bootstrap certificates). VMs created in other resource groups by a DevOps member can't access these secrets, even if the VM has the secret URIs.

Our example describes a simple scenario. Real-life scenarios can be more complex. You can adjust permissions to your key vault based on your needs. We assumed the security team provides the key and secret references (URIs and thumbprints), which are used by the DevOps staff in their applications. Developers and operators don't require any data plane access. We focused on how to secure your key vault. Give similar consideration when you secure your VMs, storage accounts, and other Azure resources.

Note

This example shows how Key Vault access is locked down in production. Developers should have their own subscription or resource group with full permissions to manage their vaults, VMs, and the storage account where they develop the application.

We recommend that you set up additional secure access to your key vault by configuring Key Vault firewalls and virtual networks.

Resources

Next steps

Configure Key Vault firewalls and virtual networks.

For a getting-started tutorial for an administrator, see What is Azure Key Vault?.

For more information about usage logging for Key Vault, see Azure Key Vault logging.

For more information about using keys and secrets with Azure Key Vault, see About keys and secrets.

If you have questions about Key Vault, visit the forums.