Note
Access to this page requires authorization. You can try signing in or changing directories.
Access to this page requires authorization. You can try changing directories.
Use the information in this article if you've decided to configure your tenant to use your own root key for the Azure Rights Management service, instead of a default key generated by Microsoft. This configuration is often referred to as Bring Your Own Key (BYOK).
For more information the root key options, see Key types for the service.
BYOK and usage logging work seamlessly with applications that integrate with the Azure Rights Management service used by Microsoft Purview 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 by using the Rights Management connector
Client applications, such as Office 2024 and Office 2021.
Tip
If needed, apply additional security to specific documents using an additional on-premises key. For more information, see Double Key Encryption (DKE).
Azure Key Vault key storage
Customer-generated keys must be stored in the Azure Key Vault for BYOK.
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 Azure Rights Management tenant key. Dedicated key vaults help to ensure that calls by other services don't 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 the Azure Rights Management service.
Because different services have varying key management requirements, Microsoft also recommends using a dedicated Azure subscription for your key vault for the following reasons:
Help safeguard against misconfigurations
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. Confirm that all administrators who use the subscription have a thorough understanding of every key they can manage. Administrators with this level of understanding are less likely to misconfigure your keys.
Example: Use a shared Azure subscription when the administrators for your Azure Rights Management tenant key are the same people that administer your keys for Microsoft Purview Customer Key and Dynamics 365 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 Azure Monitor Agent, 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 administrators for the Azure Rights Management service 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 for the Azure Rights Management service to see exactly how and when your Azure Rights Management tenant key is being used.
For more information about key usage logging for BYOK, see Usage logging for the Azure Rights Management service.
Tip
For additional assurance, this 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 general information about the Managed HSM offering, and how to set up a vault and a key, see the Azure Key Vault documentation.
This section contains additional instructions about granting key authorization for the Azure Rights Management service.
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 the Azure Rights Management service 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.
Important
Keys that are generated directly in Azure Key Vault can't be exported for use outside Azure Key Vault.
If your organization requires that keys are exportable and in your possession, you must create the key on-premises and import to Azure Key Vault, and maintain your own backups of the key on-premises. Disaster recovery planning and testing should include measures to regularly test recovery of these keys. Keys can be backed up from Azure Key Vault, but can only be imported to the original subscription.
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 have FIPS 140 validation.
Software-protected key that is converted and transferred to Azure Key Vault as an HSM-protected key. This method is supported only when migrating from Active Directory Rights Management Services (AD RMS).
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're responsible 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 the Azure Rights Management service, you'll need a trusted publishing domain (TPD) to decrypt content that was encrypted by the Azure Rights Management service.
However, exporting your TPD isn't supported if you're using BYOK for your Azure Rights Management tenant 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 Rights Management 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 the Azure Rights Management service | Required for all configurations. For more information, see Install the AIPService PowerShell module for the Azure Right Management service. |
| Azure Key Vault prerequisites for BYOK | If you're 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're migrating from AD RMS to the Azure Rights Management service 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 Rights Management tenant must have an Azure subscription. If you don't have one yet, you can sign up for a free account. 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 Microsoft Entra configuration isn't 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.
Run
Connect-AzAccountand sign in with a role that can access resources in Azure Key Vault.Run the following commands to get an access token for Azure Key Vault:
$token = (Get-AzAccessToken -ResourceUrl https://vault.azure.net).Token $token # This displays the tokenImportant
This token should be treated like a password. It grants temporary access to Azure Key Vault and shouldn't be logged or shared.
Copy the token displayed to your clipboard. Then, in a browser, go to https://microsoft.com/devicelogin and enter the copied token.
In your PowerShell session, enter
Get-AzSubscription, and confirm that the following values are displayed:- Your subscription name and ID
- Your tenant ID for the Azure Rights Management service
- Confirmation that the state is enabled
If no values are displayed and you're returned to the prompt, you don't 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 the Azure Rights Management service, 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 Rights Management tenant key.
All cryptographic calls for protection chain to your Azure Rights Management 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 Rights Management tenant.
To identify the location of your tenant that uses the Azure Rights Management service, 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 the Azure Rights Management service. For more information, see the Azure Key Vault documentation.
Important
After creating the Azure Key Vault, immediately enable both soft delete and purge protection. This prevents accidental deletion of the vault and keys. Loss of the keys without sufficient backups results in complete data loss of encrypted files and emails. For details, see Azure Key Vault: soft-delete overview.
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 the Azure Rights Management service for your key ID
- Authorizing the Azure Rights Management service to use your key
Key length requirements
When you create your key, make sure that the key length is either 2048 bits (recommended) or 1024 bits. Other key lengths aren't supported by the Azure Rights Management service.
Note
1024-bit keys aren't 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.
Creating an HSM-protected key on-premises and transferring it to your key vault
To create an HSM-protected key on-premises and transfer it to your key vault as an HSM-protected key, follow the procedures in the Azure Key Vault documentation: How to generate and transfer HSM-protected keys for Azure Key Vault.
For the Azure Rights Management service to use the transferred key, all Key Vault operations must be permitted for the key, including:
- encrypt
- decrypt
- wrapKey
- unwrapKey
- sign
- verify
By default, all Key Vault operations are permitted.
To check the permitted operations for a specific key, run the following PowerShell command:
(Get-AzKeyVaultKey -VaultName <key vault name> -Name <key name>).Attributes.KeyOps
If necessary, add permitted operations by using Update-AzKeyVaultKey and the KeyOps parameter.
Configuring the Azure Rights Management service for 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 the Azure Rights Management service 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-principal-type ServicePrincipal --assignee https://aadrm.com/ --scope /keys/contosomhskey
Where:
- 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 the Azure Rights Management service to use your key
After you've completed all the previous steps, you're ready to configure the Azure Rights Management service to use this key as your organization's tenant key.
Using PowerShell from the AIPService module] 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 don't 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 the Azure Rights Management service, 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 the service to use this key as the active tenant key.
The Azure Rights Management service is now configured to use your key instead of the default Microsoft-created key that was automatically created for your tenant.
Next steps
If you haven't yet activated the Rights Management service, do this step now.
If the service was activated before you configured BYOK, users are gradually transitioned from the old key to the new key over the course of a few weeks. During this transition, documents and files that were encrypted with the old tenant key remain accessible to authorized users.
Use the Azure Rights Management usage logging to see every transaction that the Azure Rights Management service and your key performs. For example, from a log file displayed in Excel, the KeyVaultDecryptRequest and KeyVaultSignRequest request types show that the tenant key is being used.
