Secure your key vault
Azure Key Vault is a cloud service that safeguards encryption keys and secrets (such as certificates, connection strings, and passwords). Because this data is sensitive and business critical, you must secure access to your key vaults, 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.
Access to a key vault is controlled through two separate interfaces: management plane and data plane. Management plane deals with managing the vault, for example - creating a vault, updating a vault, deleting a vault. Data plane deals with secrets inside a vault, that is create, update, delete and read a secret inside the vault. For both planes, proper authentication and authorization are required before a caller (a user or an application) can get access to key vault. Authentication establishes the identity of the caller, while authorization determines the operations the caller is allowed to perform.
For authentication both management plane and data plane use Azure Active Directory. For authorization, management plane uses role-based access control (RBAC) while data plane uses key vault access policy.
Here is a brief overview of the topics covered:
Authentication using Azure Active Directory - This section explains how a caller authenticates with Azure Active Directory to access a key vault via management plane and data plane.
For authentication, both planes use Azure Active Directory (Azure AD). For authorization, the management plane uses role-based access control (RBAC), while the data plane uses Key Vault access policy.
Authenticate by using Azure Active Directory
When you create a key vault in an Azure subscription, it's automatically associated with the subscription's Azure AD tenant. All callers must be registered in this tenant, and must authenticate to access the key vault. This requirement applies to both management plane and data plane access. In both cases, an application can access Key Vault in two ways:
user+app access: Used with applications that access Key Vault on behalf of a signed-in user. Azure PowerShell and the Azure portal are examples of this type of access. There are two ways to grant access to users:
- Access Key Vault from any application.
- Access Key Vault only when they use a specific application (referred to as compound identity).
app-only access: Used with applications that run as daemon services or background jobs. The application's identity is granted access to the key vault.
In both types of applications, the application authenticates with Azure AD by using any of the supported authentication methods, and acquires a token. The authentication method used depends on the application type. Then the application uses this token and sends a REST API request to Key Vault. Management plane requests are routed through an Azure Resource Manager endpoint. When accessing the data plane, the application talks directly to a Key Vault endpoint. For more information, see the whole authentication flow.
The resource name for which the application requests a token depends on which plane the application is accessing. The resource name is either a management plane endpoint, or a data plane endpoint, depending on the Azure environment. For more details, see the table later in this article.
Having one single mechanism for authentication to both planes has some benefits:
- Organizations can centrally control access to all key vaults in their organization.
- If a user leaves, he or she instantly loses access to all key vaults in the organization.
- Organizations can customize authentication via the options in Azure AD (for example, enabling multi-factor authentication for added security).
The management plane and the data plane
Use the management plane to manage Key Vault itself. This includes operations such as managing attributes and setting data plane access policies. Use the data plane to add, delete, modify, and use the keys, secrets, and certificates stored in Key Vault.
Access the management plane and data plane interfaces through the different endpoints listed in the following table. The second column of the table describes the DNS names for these endpoints in different Azure environments. The third column describes the operations you can perform from each access plane. Each access plane also has its own access control mechanism. Management plane access control is set by using Azure Resource Manager role-based access control (RBAC). Data plane access control is set by using Key Vault access policy.
|Access plane||Access endpoints||Operations||Access control mechanism|
Azure China 21Vianet:
Azure US Government:
|Create/Read/Update/Delete Key Vault
Set access policies for Key Vault
Set tags for Key Vault
|Azure Resource Manager RBAC|
Azure China 21Vianet:
Azure US Government:
|For keys: Decrypt, Encrypt, UnwrapKey, WrapKey, Verify, Sign, Get, List, Update, Create, Import, Delete, Backup, Restore
For secrets: Get, List, Set, Delete
|Key Vault access policy|
Management plane and data plane access controls work independently. For example, if you want to grant an application access to use keys in a key vault, you only need to grant data plane access. You grant access through Key Vault access policies. Conversely, a user who needs to read Key Vault properties and tags, but not access data (keys, secrets, or certificates), only needs management plane access. You grant access by assigning read access to the user with RBAC.
Management plane access control
The management plane consists of operations that affect the key vault itself, such as:
- Creating or deleting a key vault.
- Getting a list of vaults in a subscription.
- Retrieving Key Vault properties (such as SKU and tags).
- Setting Key Vault access policies that control user and application access to keys and secrets.
Management plane access control uses RBAC.
Role-based access control (RBAC)
Each Azure subscription has an Azure AD instance. You grant access to users, groups, and applications from this directory to manage resources in the Azure subscription that use the Azure Resource Manager deployment model. This type of access control is referred to as RBAC. To manage this access, you can use the Azure portal, the Azure CLI tools, PowerShell, or the Azure Resource Manager REST APIs.
You create a key vault in a resource group, and control access to the management plane by using Azure AD. For example, you can grant users or a group the ability to manage key vaults in a resource group.
You can grant access to users, groups, and applications at a specific scope by assigning appropriate RBAC roles. For example, to grant access to a user to manage key vaults, you assign a predefined Key Vault Contributor role to this user, at a specific scope. The scope in this case would be either a subscription, a resource group, or a specific key vault. A role assigned at the subscription level applies to all resource groups and resources within that subscription. A role assigned at the resource group level applies to all resources in that resource group. A role assigned for a specific resource applies to that resource. There are several predefined roles (see RBAC: Built-in roles). If a predefined role doesn't fit your needs, you can define your own role.
Note that if a user has Contributor permissions to a Key Vault management plane, she can grant herself access to the data plane by setting Key Vault access policy. Therefore, you should tightly control who has Contributor access to your key vaults. Ensure that only authorized persons can access and manage your key vaults, keys, secrets, and certificates.
Data plane access control
Key Vault data plane operations apply to stored objects such as keys, secrets, and certificates. Key operations include create, import, update, list, back up, and restore keys. Cryptographic operations include sign, verify, encrypt, decrypt, wrap, unwrap, set tags, and set other attributes for keys. Similarly, operations on secrets include get, set, list, delete.
You grant data plane access by setting access policies for a key vault. A user, group, or application must have Contributor permissions for the management plane for a key vault to be able to set access policies for that key vault. You can grant a user, group, or application access to perform specific operations for keys or secrets in a key vault. Key Vault supports up to 1024 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
Key Vault access policies grant permissions to keys, secrets, and certificates separately. For example, you can give a user access to only keys, and no permissions for secrets. Permissions to access keys, secrets, or certificates are at the vault level. Key Vault access policy doesn't support granular, object-level permissions, such as a specific key, secret, or certificate. You can use the Azure portal, the Azure CLI tools, PowerShell, or the Key Vault Management REST APIs to set access policies for a key vault.
Key Vault access policies apply at the vault level. For example, when a user is granted permission to create and delete keys, she can perform those operations on all keys in that key vault.
In addition to using access policies, you can also restrict data plane access by using Virtual network service endpoints for Azure Key Vault. You configure Firewalls and virtual network rules for an additional layer of security.
Let's say you're developing an application that uses a certificate for SSL, Azure Storage for storing data, and an RSA 2048-bit key for sign operations. Let's say this application is running in an Azure virtual machine (or a virtual machine scale set). You can use a key vault to store all the application secrets, and store the bootstrap certificate used by the application to authenticate with Azure AD.
Here's a summary of the types of keys and secrets stored:
- SSL Cert: Used for SSL.
- Storage Key: Used to get access to the Storage account.
- RSA 2048-bit key: Used for sign operations.
- Bootstrap certificate: Used to authenticate with Azure AD. After access is granted, you can fetch the storage key and use the RSA key for signing.
Now let's meet the people who are managing, deploying, and auditing this application. We'll use three roles in this example.
- Security team: Typically IT staff from the office of the CSO (Chief Security Officer), or equivalent. This team is responsible for the proper safekeeping of secrets. Examples include SSL certificates, RSA keys used for signing, connection strings, and storage account keys.
- Developers/operators: Folks who develop the application and then deploy it in Azure. Typically, they're not part of the security team, and hence they shouldn't have access to sensitive data, such as SSL certificates and RSA keys. Only the application they deploy should have access to those objects.
- Auditors: Usually a different set of people, isolated from developers and general IT staff. Their responsibility is to review use and maintenance of certificates, keys, and secrets to ensure compliance with security standards.
There's one more role that's outside the scope of this application, but relevant here to be mentioned. That role is the subscription (or resource group) administrator. The subscription administrator sets up initial access permissions for the security team. The subscription administrator grants access to the security team, using a resource group that contains the resources required by this application.
Now let's see what actions each role performs in the context of this application.
- Security team
- Creates key vaults.
- Turns on Key Vault logging.
- Adds keys/secrets.
- Creates backup of keys for disaster recovery.
- Sets Key Vault access policy to grant permissions to users and applications to perform specific operations.
- Periodically rolls keys/secrets.
- Get references to bootstrap and SSL certs (thumbprints), storage key (secret URI), and signing key (key URI) from the security team.
- Develop and deploy application that accesses keys and secrets programmatically.
- Review usage logs to confirm proper key/secret use, and compliance with data security standards.
Now let's see what access permissions are required for each role and the application, to perform their assigned tasks.
|User role||Management plane permissions||Data plane permissions|
|Security Team||Key Vault Contributor||Keys: backup, create, delete, get, import, list, restore
|Developers/Operators||Key Vault deploy permission, so that the virtual machines they deploy can fetch secrets from the key vault.||None|
Auditors need list permission for keys and secrets so they can inspect attributes for keys and secrets that are not emitted in the logs. These attributes include tags, activation, and expiration dates.
In addition to Key Vault permissions, all three roles also need access to other resources. For example, to be able to deploy VMs (or the Web Apps feature of Azure App Service), developers and operators also need Contributor access to those resource types. Auditors need Read access to the storage account where the Key Vault logs are stored.
Because the focus of this article is securing access to your key vault, we only illustrate concepts pertaining to this topic. Details regarding deploying certificates and accessing keys and secrets programmatically are covered elsewhere. For instance:
- Deploying certificates stored in Key Vault to VMs is covered in Deploy Certificates to VMs from customer-managed Key Vault (blog post).
- The Azure Key Vault client samples download illustrates how to use a bootstrap certificate to authenticate to Azure AD to access a key vault.
You can grant most of the access permissions by using the Azure portal. To grant granular permissions, you might need to use Azure PowerShell or the CLI to achieve the desired result.
The following PowerShell snippets assume:
- The Azure AD administrator has created security groups that represent the three roles (the Contoso Security Team, Contoso App Devops, and Contoso App Auditors). The administrator has also added users to the groups to which they belong.
- ContosoAppRG is the resource group where all the resources reside. contosologstorage is where the logs are stored.
- The key vault ContosoKeyVault, and the storage account used for Key Vault logs contosologstorage, must be in the same Azure location.
First the subscription administrator assigns
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 manage key vaults, in the resource group ContosoAppRG.
New-AzureRmRoleAssignment -ObjectId (Get-AzureRmADGroup -SearchString 'Contoso Security Team').Id -RoleDefinitionName "key vault Contributor" -ResourceGroupName ContosoAppRG New-AzureRmRoleAssignment -ObjectId (Get-AzureRmADGroup -SearchString 'Contoso Security Team').Id -RoleDefinitionName "User Access Administrator" -ResourceGroupName ContosoAppRG
The following script shows how the security team can create a key vault, and set up logging and access permissions. For details about Key Vault access policy permissions, see About Azure Key Vault keys, secrets and certificates.
# Create key vault and enable logging $sa = Get-AzureRmStorageAccount -ResourceGroup ContosoAppRG -Name contosologstorage $kv = New-AzureRmKeyVault -Name ContosoKeyVault -ResourceGroup ContosoAppRG -SKU premium -Location 'westus' -EnabledForDeployment Set-AzureRmDiagnosticSetting -ResourceId $kv.ResourceId -StorageAccountId $sa.Id -Enabled $true -Categories AuditEvent # Data plane permissions for Security team Set-AzureRmKeyVaultAccessPolicy -VaultName ContosoKeyVault -ObjectId (Get-AzureRmADGroup -SearchString 'Contoso Security Team').Id -PermissionsToKeys backup,create,delete,get,import,list,restore -PermissionsToSecrets get,list,set,delete,backup,restore,recover,purge # Management plane permissions for Dev/ops # Create a new role from an existing role $devopsrole = Get-AzureRmRoleDefinition -Name "Virtual Machine Contributor" $devopsrole.Id = $null $devopsrole.Name = "Contoso App Devops" $devopsrole.Description = "Can deploy VMs that need secrets from key vault" $devopsrole.AssignableScopes = @("/subscriptions/<SUBSCRIPTION-GUID>") # Add permission for dev/ops so they can deploy VMs that have secrets deployed from key vaults $devopsrole.Actions.Add("Microsoft.KeyVault/vaults/deploy/action") New-AzureRmRoleDefinition -Role $devopsrole # Assign this newly defined role to Dev ops security group New-AzureRmRoleAssignment -ObjectId (Get-AzureRmADGroup -SearchString 'Contoso App Devops').Id -RoleDefinitionName "Contoso App Devops" -ResourceGroupName ContosoAppRG # Data plane permissions for Auditors Set-AzureRmKeyVaultAccessPolicy -VaultName ContosoKeyVault -ObjectId (Get-AzureRmADGroup -SearchString 'Contoso App Auditors').Id -PermissionsToKeys list -PermissionsToSecrets list
The custom role defined is only assignable to the subscription where the
ContosoAppRG resource group is created. If the same custom roles will be used for other projects in other subscriptions, its scope can have more subscriptions added.
The custom role assignment for the "deploy/action" permission for developers and operators is scoped to the resource group. This allows only VMs created in the resource group
ContosoAppRG to have access to the secrets (the SSL cert and bootstrap cert). VMs created in another resource group by a developers and operators team member won't have access to these secrets, even if they have the secret URIs.
This example shows a simple scenario. Real life scenarios can be more complex, and you can adjust permissions to your key vault based on your needs. In our example, we assume the security team provides the key and secret references (URIs and thumbprints) that developers and operators need to reference in their applications. Developers and operators don't require any data plane access. This example focuses on securing your key vault. You should give similar consideration to secure your VMs, storage accounts, and other Azure resources.
This example shows how Key Vault access will be locked down in production. The developers should have their own subscription or resource group where they have full permissions to manage their vaults, VMs, and storage account where they develop the application.
We highly recommend that you further secure access to your key vault by configuring Key Vault firewalls and virtual networks.
This 2015 Microsoft Ignite conference video discusses access management and reporting capabilities in Azure. It also explores best practices for securing access to Azure subscriptions by using Azure AD.
This document is the reference for the REST APIs to manage your key vault programmatically, including setting Key Vault access policy.
For a getting started tutorial for an administrator, see Get Started with 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.