Bring your own key (BYOK) details for Azure Information Protection
Applies to: Azure Information Protection, Office 365
Relevant for: AIP unified labeling client and classic client
Note
To provide a unified and streamlined customer experience, we are sunsetting the Azure Information Protection classic client and Label Management in the Azure Portal as of March 31, 2021. No further support is provided for the classic client and maintenance versions will no longer be released.
- The classic client will be fully retired, and will stop functioning, on March 31, 2022.
- As of March 18, 2022, we are also sunsetting the AIP audit log and analytics, with a full retirement date of September 31, 2022.
For more information, see Removed and retired services.
Organizations with an Azure Information Protection subscription can choose to configure their tenant with their own key, instead of a default key generated by Microsoft. This configuration is often referred to as Bring Your Own Key (BYOK).
BYOK and usage logging work seamlessly with applications that integrate with the Azure Rights Management service used by Azure Information Protection.
Supported applications include:
Cloud services, such as Microsoft SharePoint or Microsoft 365
On-premises services running Exchange and SharePoint applications that use the Azure Rights Management service via the RMS connector
Client applications, such as Office 2019, Office 2016, and Office 2013
Tip
If needed, apply additional security to specific documents using an additional on-premises key. For more information, see Double Key Encryption (DKE) protection (unified labeling client only).
If you have the classic client and need additional, on-premises protection, implement Hold your own key (HYOK) protection protection instead.
Azure Key Vault key storage
Customer-generated keys must be stored in the Azure Key Vault for BYOK protection.
Note
Using HSM-protected keys in the Azure Key Vault requires an Azure Key Vault Premium service tier, which incurs an additional monthly subscription fee.
Sharing key vaults and subscriptions
We recommend using a dedicated key vault for your tenant key. Dedicated key vaults help to ensure that calls by other services do not cause service limits to be exceeded. Exceeding service limits on the key vault where your tenant key is stored may cause response time throttling for Azure Rights Management service.
As different services have varying key management requirements, Microsoft also recommends using a dedicated Azure subscription for your key vault. Dedicated Azure subscriptions:
Help safeguard against misconfigurations
Are more secure when different services have different administrators
To share an Azure subscription with other services that use Azure Key Vault, make sure that the subscription shares a common set of administrators. Confirming that all administrators who use the subscription have a solid understanding of every key they can access, means they are less likely to misconfigure your keys.
Example: Using a shared Azure subscription when the administrators for your Azure Information Protection tenant key are the same individuals that administer your keys for Office 365 Customer Key and CRM online. If the key administrators for these services are different, we recommend using dedicated subscriptions.
Benefits of using Azure Key Vault
Azure Key Vault provides a centralized and consistent key management solution for many cloud-based and on-premises services that use encryption.
In addition to managing keys, Azure Key Vault offers your security administrators the same management experience to store, access, and manage certificates and secrets (such as passwords) for other services and applications that use encryption.
Storing your tenant key in the Azure Key Vault provides the following advantages:
| Advantage | Description |
|---|---|
| Built-in interfaces | Azure Key Vault supports a number of built-in interfaces for key management, including PowerShell, CLI, REST APIs, and the Azure portal. Other services and tools have integrated with Key Vault for optimized capabilities for specific tasks, such as monitoring. For example, analyze your key usage logs with Operations Management Suite Log analytics, set alerts when specified criteria are met, and so on. |
| Role separation | Azure Key Vault provides role separation as a recognized security best practice. Role separation ensures that Azure Information Protection administrators can focus on their highest priorities, including managing data classification and protection, as well as encryption keys and policies for specific security or compliance requirements. |
| Master key location | Azure Key Vault is available in a variety of locations, and supports organizations with restrictions where master keys can live. For more information, see the Products available by region page on the Azure site. |
| Separated security domains | Azure Key Vault uses separate security domains for its data centers in regions such as North America, EMEA (Europe, Middle East and Africa), and Asia. Azure Key Vault also uses different instances of Azure, such as Microsoft Azure Germany, and Azure Government. |
| Unified experience | Azure Key Vault also enables security administrators to store, access, and manage certificates and secrets, such as passwords, for other services that use encryption. Using Azure Key Vault for your tenant keys provides a seamless user experience for administrators who manage all of these elements. |
For the latest updates and to learn how other services use Azure Key Vault, visit the Azure Key Vault team blog.
Usage logging for BYOK
Usage logs are generated by every application that makes requests to the Azure Rights Management service.
Although usage logging is optional, we recommend using the near real-time usage logs from Azure Information Protection to see exactly how and when your tenant key is being used.
For more information about key usage logging for BYOK, see Logging and analyzing the protection usage from Azure Information Protection.
Tip
For additional assurance, Azure Information Protection usage logging can be cross referenced with Azure Key Vault logging. Key Vault logs provide a reliable method to independently monitor that your key is only used by Azure Rights Management service.
If necessary, immediately revoke access to your key by removing permissions on the key vault.
Options for creating and storing your key
Note
For more information about the Managed HSM offering, and how to set up a vault and a key, see the Azure Key Vault documentation.
Additional instructions on granting key authorization are described below.
BYOK supports keys that are created either in Azure Key Vault or on-premises.
If you create your key on-premises, you must then transfer or import it into your Key Vault and configure Azure Information Protection to use the key. Perform any additional key management from within Azure Key Vault.
Options to create and store your own key:
Created in Azure Key Vault. Create and store your key in Azure Key Vault as an HSM-protected key or a software-protected key.
Created on-premises. Create your key on-premises and transfer it to Azure Key Vault using one of the following options:
HSM-protected key, transferred as an HSM-protected key. The most typical method chosen.
While this method has the most administrative overhead, it may be required for your organization to follow specific regulations. The HSMs used by Azure Key Vault are FIPS 140-2 Level 2 validated.
Created on-premises as a software-protected key and transferred to Azure Key Vault as a software-protected key. This method requires a .PFX certificate file.
For example, do the following to use a key created on-premises:
Generate your tenant key on your premises, in line with your organization's IT and security policies. This key is the master copy. It remains on-premises, and you are required for its backup.
Create a copy of the master key, and securely transfer it from your HSM to Azure Key Vault. Throughout this process, the master copy of the key never leaves the hardware protection boundary.
Once transferred, the copy of the key is protected by Azure Key Vault.
Exporting your trusted publishing domain
If you ever decide to stop using Azure Information Protection, you'll need a trusted publishing domain (TPD) to decrypt content that was protected by Azure Information Protection.
However, exporting your TPD isn't supported if you're using BYOK for your Azure Information Protection key.
To prepare for this scenario, make sure to create a suitable TPD ahead of time. For more information, see How to prepare an Azure Information Protection "Cloud Exit" plan.
Implementing BYOK for your Azure Information Protection tenant key
Use the following steps to implement BYOK:
Prerequisites for BYOK
BYOK prerequisites vary, depending on your system configuration. Verify that your system complies with the following prerequisites as needed:
| Requirement | Description |
|---|---|
| Azure subscription | Required for all configurations. For more information, see Verifying that you have a BYOK-compatible Azure subscription. |
| AIPService PowerShell module for Azure Information Protection | Required for all configurations. For more information, see Installing the AIPService PowerShell module. |
| Azure Key Vault prerequisites for BYOK | If you are using an HSM-protected key that was created on-premises, ensure that you also comply with the prerequisites for BYOK listed in the Azure Key Vault documentation. |
| Thales firmware version 11.62 | You must have a Thales firmware version of 11.62 if you are migrating from AD RMS to Azure Information Protection by using software key to hardware key and are using Thales firmware for your HSM. |
| Firewall bypass for trusted Microsoft services | If the key vault that contains your tenant key uses Virtual Network Service Endpoints for Azure Key Vault, you must allow trusted Microsoft services to bypass this firewall. For more information, see Virtual Network Service Endpoints for Azure Key Vault. |
Verifying that you have a BYOK-compatible Azure subscription
Your Azure Information Protection tenant must have an Azure subscription. If you don't have one yet, you can sign up for a Trial. However, to use an HSM-protected key, you must have the Azure Key Vault Premium service tier.
The free Azure subscription that provides access to Azure Active Directory configuration and Azure Rights Management custom template configuration is not sufficient for using Azure Key Vault.
To confirm whether you have an Azure subscription that is compatible with BYOK, do the following to verify, using Azure PowerShell cmdlets:
Start an Azure PowerShell session as an administrator.
Sign in as a global admin for your Azure Information Protection tenant using
Connect-AzAccount.Copy the token displayed to your clipboard. Then, in a browser, go to https://microsoft.com/devicelogin and enter the copied token.
For more information, see Sign in with Azure PowerShell.
In your PowerShell session, enter
Get-AzSubscription, and confirm that the following values are displayed:- Your subscription name and ID
- Your Azure Information Protection tenant ID
- Confirmation that the state is enabled
If no values are displayed and you are returned to the prompt, you do not have an Azure subscription that can be used for BYOK.
Choosing your key vault location
When you create a key vault to contain the key to be used as your tenant key for Azure Information, you must specify a location. This location is an Azure region, or Azure instance.
Make your choice first for compliance, and then to minimize network latency:
If you have chosen the BYOK key method for compliance reasons, those compliance requirements might also mandate which Azure region or instance can be used to store your Azure Information Protection tenant key.
All cryptographic calls for protection chain to your Azure Information Protection key. Therefore, you may want to minimize the network latency these calls require by creating your key vault in the same Azure region or instance as your Azure Information Protection tenant.
To identify the location of your Azure Information Protection tenant, use the Get-AipServiceConfiguration PowerShell cmdlet and identify the region from the URLs. For example:
LicensingIntranetDistributionPointUrl : https://5c6bb73b-1038-4eec-863d-49bded473437.rms.na.aadrm.com/_wmcs/licensing
The region is identifiable from rms.na.aadrm.com, and for this example, it is in North America.
The following table lists recommended Azure regions and instances for minimizing network latency:
| Azure region or instance | Recommended location for your key vault |
|---|---|
| rms.na.aadrm.com | North Central US or East US |
| rms.eu.aadrm.com | North Europe or West Europe |
| rms.ap.aadrm.com | East Asia or Southeast Asia |
| rms.sa.aadrm.com | West US or East US |
| rms.govus.aadrm.com | Central US or East US 2 |
| rms.aadrm.us | US Gov Virginia or US Gov Arizona |
| rms.aadrm.cn | China East 2 or China North 2 |
Create and configure your key
Important
For information specific for Managed HSMs, see Enabling key authorization for Managed HSM keys via Azure CLI.
Create an Azure Key Vault and the key you want to use for Azure Information Protection. For more information, see the Azure Key Vault documentation.
Note the following for configuring your Azure Key Vault and key for BYOK:
- Key length requirements
- Creating an HSM-protected key on-premises and transferring it to your key vault
- Configuring Azure Information Protection with your key ID
- Authorizing the Azure Rights Management service to use your key
Key length requirements
When creating your key, make sure that the key length is either 2048 bits (recommended) or 1024 bits. Other key lengths are not supported by Azure Information Protection.
Note
1024-bit keys are not considered to offer an adequate level of protection for active tenant keys.
Microsoft doesn't endorse the use of lower key lengths, such as 1024-bit RSA keys, and the associated use of protocols that offer inadequate levels of protection, such as SHA-1.
Configuring Azure Information Protection with your key ID
Keys stored in the Azure Key Vault each have a key ID.
The key ID is a URL that contains the name of the key vault, the keys container, the name of the key, and the key version. For example:
https://contosorms-kv.vault.azure.net/keys/contosorms-byok/aaaabbbbcccc111122223333.
Configure Azure Information Protection to use your key by specifying its key vault URL.
Authorizing the Azure Rights Management service to use your key
The Azure Rights Management service must be authorized to use your key. Azure Key Vault administrators can enable this authorization using the Azure portal or Azure PowerShell.
Enabling key authorization using the Azure portal
Sign in to the Azure portal, and go to Key vaults > <your key vault name> > Access policies > Add new.
From the Add access policy pane, from the Configure from template (optional) list box, select Azure Information Protection BYOK, and then click OK.
The selected template has the following configuration:
- The Select principal value is set to Microsoft Rights Management Services.
- Selected key permissions include Get, Decrypt, and Sign.
Enabling key authorization using PowerShell
Run the Key Vault PowerShell cmdlet, Set-AzKeyVaultAccessPolicy, and grant permissions to the Azure Rights Management service principal using the GUID 00000012-0000-0000-c000-000000000000.
For example:
Set-AzKeyVaultAccessPolicy -VaultName 'ContosoRMS-kv' -ResourceGroupName 'ContosoRMS-byok-rg' -ServicePrincipalName 00000012-0000-0000-c000-000000000000 -PermissionsToKeys decrypt,sign,get
Enabling key authorization for Managed HSM keys via Azure CLI
To grant the Azure Rights Management service principal user permissions as a Managed HSM Crypto user, run the following command:
az keyvault role assignment create --hsm-name "ContosoMHSM" --role "Managed HSM Crypto User" --assignee 00000012-0000-0000-c000-000000000000 --scope /keys/contosomhsmkey
Where:
- 00000012-0000-0000-c000-000000000000 is the GUID to use in this command
- ContosoMHSM is a sample HSM name. When running this command, replace this value with your own HSM name.
The Managed HSM Crypto User user role allows the user to decrypt, sign, and get permissions to the key, which are all required for the Managed HSM functionality.
Configure Azure Information Protection to use your key
Once you've completed all of the steps above, you're ready to configure Azure Information Protection to use this key as your organization's tenant key.
Using Azure RMS cmdlets, run the following commands:
Connect to the Azure Rights Management service and sign in:
Connect-AipServiceRun the Use-AipServiceKeyVaultKey cmdlet, specifying the key URL. For example:
Use-AipServiceKeyVaultKey -KeyVaultKeyUrl "https://contosorms-kv.vault.azure.net/keys/contosorms-byok/<key-version>"Important
In this example,
<key-version>is the version of the key you want to use. If you do not specify the version, the current version of the key is used by default, and the command may appear to work. However, if your key is later updated or renewed, the Azure Rights Management service will stop working for your tenant, even if you run the Use-AipServiceKeyVaultKey command again.Use the Get-AzKeyVaultKey command as needed to get the version number of the current key.
For example:
Get-AzKeyVaultKey -VaultName 'contosorms-kv' -KeyName 'contosorms-byok'To confirm that the key URL is set correctly for Azure Information Protection, run the Get-AzKeyVaultKey command in the Azure Key Vault to display the key URL.
If the Azure Rights Management service is already activated, run Set-AipServiceKeyProperties to tell Azure Information Protection to use this key as the active tenant key for the Azure Rights Management service.
Azure Information Protection is now configured to use your key instead of the default Microsoft-created key that was automatically created for your tenant.
Next steps
Once you've configured BYOK protection, continue to Getting started with your tenant root key for more information about using and managing your key.