Bring your own key for the Azure Rights Management service root key

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 about 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.

Azure Key Vault key storage

Customer-generated keys must be stored in the Azure Key Vault for BYOK.

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:

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.

Options for creating and storing your key

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 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:

1. 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.

2. 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.

• 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. Most organizations that use BYOK have compliance requirements that mandate that they maintain their own copy of the key outside of Azure Key Vault. Do not create the key directly in Azure Key Vault; instead, create the key on-premises and transfer it to 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.

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:

1. Review BYOK prerequisites
2. Choose a key vault location
3. Create and configure your key

Prerequisites for BYOK

BYOK prerequisites vary, depending on your system configuration. Verify that your system complies with the following prerequisites as needed:

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:

1. Start an Azure PowerShell session as an administrator.

2. Run Connect-AzAccount and sign in with a role that can access resources in Azure Key Vault.

3. Run Get-AzSubscription to 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.

4. Verify that you can use the Azure Key Vault Premium tier, which is required for HSM-protected keys. If you have an existing key vault, run the following command to check its SKU:

   Get-AzKeyVault -VaultName "YourVaultName" | Select-Object VaultName, Sku
   

   The Sku value must be Premium for HSM-protected keys. If you're creating a new key vault, ensure you select the Premium tier during creation. For pricing information, see Azure Key Vault pricing.

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:

Create and configure your key

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.

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 2048 bits. Other key lengths aren't supported by the Azure Rights Management service.

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, the following Key Vault operations must be permitted for the key:

• get
• decrypt
• sign

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

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 through Azure RBAC. This requires creating a custom role with the necessary permissions and assigning it to the Rights Management service principal.

Enabling key authorization using Azure CLI

1. Sign in to Azure CLI and get your key vault's subscription ID:

   az login
   az keyvault show --name <vault-name> --resource-group <resource-group-name> --query "id" -o tsv
   

   The output contains the subscription ID in the format: /subscriptions/<subscription-id>/resourceGroups/...

2. Create a JSON file named PurviewRMSCustomAKVRole.json with the following content, replacing <subscription-id> with the subscription ID from the previous step:

   {
     "Name": "Purview Rights Management key vault Encryption User",
     "IsCustom": true,
     "Description": "Grants access to use key vault keys for the Purview Rights Management service.",
     "Actions": [
       "Microsoft.KeyVault/vaults/keys/read"
     ],
     "NotActions": [],
     "DataActions": [
       "Microsoft.KeyVault/vaults/keys/sign/action",
       "Microsoft.KeyVault/vaults/keys/decrypt/action"
     ],
     "NotDataActions": [],
     "AssignableScopes": [
       "/subscriptions/<subscription-id>"
     ]
   }
   

3. Create the custom role definition, changing the role definition file path if necessary:

   az role definition create --role-definition "./PurviewRMSCustomAKVRole.json"
   

   Note

   Run this command from the directory where you saved PurviewRMSCustomAKVRole.json, or replace ./PurviewRMSCustomAKVRole.json with the full path to the file.

4. Get the key vault resource ID and assign the role to the Rights Management service principal in a single command:

   az role assignment create --role "Purview Rights Management key vault Encryption User" --assignee "00000012-0000-0000-c000-000000000000" --scope $(az keyvault show --name <vault-name> --resource-group <resource-group-name> --query "id" -o tsv)
   

Enabling key authorization using Azure PowerShell

1. Sign in to Azure PowerShell and get your key vault's subscription ID:

   Connect-AzAccount
   
   # Define your key vault and resource group names
   $vaultName = "<vault-name>"
   $resourceGroupName = "<resource-group-name>"
   
   # Get the key vault resource ID and subscription ID
   $keyVault = Get-AzKeyVault -VaultName $vaultName -ResourceGroupName $resourceGroupName
   $resourceId = $keyVault.ResourceId
   $subscriptionId = ($resourceId -split "/")[2]
   
   # Create the custom role definition JSON file
   $jsonRoleDefinition = @"
   {
     "Name": "Purview Rights Management key vault Encryption User",
     "IsCustom": true,
     "Description": "Grants access to use key vault keys for the Purview Rights Management service.",
     "Actions": [
       "Microsoft.KeyVault/vaults/keys/read"
     ],
     "NotActions": [],
     "DataActions": [
       "Microsoft.KeyVault/vaults/keys/sign/action",
       "Microsoft.KeyVault/vaults/keys/decrypt/action"
     ],
     "NotDataActions": [],
     "AssignableScopes": [
       "/subscriptions/$($subscriptionId)"
     ]
   }
   "@
   
   $jsonRoleDefinition | Out-File -FilePath "./PurviewRMSCustomAKVRole.json"
   
   # Create the custom role definition
   New-AzRoleDefinition -InputFile "./PurviewRMSCustomAKVRole.json"
   
   # Assign the role to the Rights Management service principal
   New-AzRoleAssignment -RoleDefinitionName "Purview Rights Management key vault Encryption User" -ServicePrincipalName "00000012-0000-0000-c000-000000000000" -Scope $resourceId
   

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 the previous steps, you're ready to configure the Azure Rights Management service to use this key as your organization's tenant key.

First, copy the URL for your key from Azure Key Vault, including the key version. You can retrieve this using Azure CLI or PowerShell:

Azure CLI:

az keyvault key show --vault-name <vault-name> --name <key-name> --query "key.kid" -o tsv

Azure PowerShell:

(Get-AzKeyVaultKey -VaultName "<vault-name>" -Name "<key-name>").Id

Configuring a new BYOK key

If this is a new key, use the following steps to configure the Azure Rights Management service:

1. Install and import the AIPService PowerShell module if you haven't already:

   Note

   The AIPService module only runs on Windows PowerShell 5.1. It isn't compatible with PowerShell 7 or other modern versions. Run powershell.exe to open Windows PowerShell.

   Install-Module -Name AIPService
   Import-Module -Name AIPService
   

2. Connect to the Azure Rights Management service:

   Connect-AipService
   

3. Run the Use-AipServiceKeyVaultKey cmdlet, specifying the key URL:

   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. You must specify the key version. If your key is later updated or renewed, the Azure Rights Management service will stop working for your tenant unless you update the configuration with the new key version.

4. List the keys configured for your tenant to get the key ID of the new key using Get-AipServiceKeys. Find the key with the matching KeyVaultKeyUrl. Copy the KeyIdentifier value:

   Get-AipServiceKeys | Select-Object KeyIdentifier, KeyVaultKeyUrl
   

5. Set the new key as the active tenant key using new key ID from the previous command:

   Set-AipServiceKeyProperties -KeyIdentifier <key-id-from-previous-step> -Active $true
   

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.

Migrating from Azure Key Vault hsmPlatform 1 to hsmPlatform 2

Azure Key Vault hsmPlatform 1 is being retired. For more information about this retirement, see Azure Key Vault hsmPlatform 1 retirement announcement.

If your Azure Rights Management tenant key is stored on a hsmPlatform 1 key vault, you must migrate to hsmPlatform 2 to continue using BYOK.

Determine if your key is on hsmPlatform 1

First, identify whether your existing Rights Management key is on hsmPlatform 1:

Using Azure CLI:

az keyvault key show --vault-name <vault-name> --name <key-name> --query "attributes.hsmPlatform" -o tsv

Using Azure PowerShell:

(Get-AzKeyVaultKey -VaultName "<vault-name>" -Name "<key-name>").Attributes.HsmPlatform

• If the hsmPlatform value is 1, your key is on hsmPlatform 1 and requires migration.
• If the hsmPlatform value is 2 or higher, your key is already on hsmPlatform 2 and no action is required.

Migration steps for keys on hsmPlatform 1

If your key is on hsmPlatform 1, follow these steps to migrate:

Step 1: Locate your on-premises HSM

You must have access to the on-premises HSM that was originally used to generate the key material, or a backup of that key that can be imported into a compatible HSM within your administrative boundary.

Step 2: Create a new hsmPlatform 2 key vault

Create a new Azure Key Vault that uses hsmPlatform 2. New key vaults created today automatically use hsmPlatform 2. Ensure you:

• Select the Premium tier for HSM-protected keys.
• Enable soft delete and purge protection.
• Choose a location that minimizes network latency as described in Choosing your key vault location.

Step 3: Import your key from the on-premises HSM

Follow the HSM migration process to import your key from the on-premises HSM to the new Azure Key Vault. For detailed instructions, see How to generate and transfer HSM-protected keys for Azure Key Vault.

Step 4: Verify that the public keys match

Before updating the Rights Management service configuration, verify that the public keys match across all locations:

1. Get the public key from the new key vault:

   Using Azure CLI:

   az keyvault key show --vault-name <new-vault-name> --name <key-name> --query "key.n" -o tsv
   

   Using Azure PowerShell:

   Get-AzKeyVaultKey -VaultName "<new-vault-name>" -Name "<key-name>" | Format-List Key
   

Review the n value from the output, which represents the public key modulus.

1. Get the public key from the Rights Management service:

   Connect-AipService
   Get-AipServiceKeys | Select-Object KeyIdentifier, PublicKey
   

2. Compare with your on-premises HSM copy using your HSM vendor's tools to export or display the public key. Contact your HSM vendor for assistance if you're unable to locate the public key details. Microsoft Support can't assist with HSM-specific operations.

All three public keys must match exactly. If they don't match, verify you're importing the correct key from your HSM.

Step 5: Configure access control on the new key vault

Follow the steps in Authorizing the Azure Rights Management service to use your key to create the custom RBAC role and assign it to the Rights Management service principal on the new key vault.

Step 6: Update the Rights Management service to use the new key vault

Run Convert-AipServiceKeyToKeyVault to update the key URL to the new vault:

Connect-AipService
Convert-AipServiceKeyToKeyVault -KeyIdentifier <existing-key-id> -KeyVaultKeyUrl "https://<new-vault-name>.vault.azure.net/keys/<key-name>/<key-version>"

My organization has lost access to the original key material

If you no longer have access to the original on-premises HSM or the key material used to create your BYOK key, you must create a new key:

1. Create a new key following the steps in Create and configure your key.

2. Configure access control as described in Authorizing the Azure Rights Management service to use your key.

3. Set the new key as active:

   Connect-AipService
   Use-AipServiceKeyVaultKey -KeyVaultKeyUrl "https://<vault-name>.vault.azure.net/keys/<key-name>/<key-version>"
   Set-AipServiceKeyProperties -KeyIdentifier <new-key-id> -Active $true
   

4. Open a support case with Microsoft Purview support to discuss next steps for content that was protected with the previous key. Go to Microsoft 365 admin center and open a service request, or contact your Microsoft support representative. For more information, see Get support for Microsoft 365 for business.

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.