Share via

Set up Customer Key

Customer Key lets you control your organization's encryption keys and configure Microsoft 365 to use those keys to encrypt your data at rest in Microsoft's data centers. In other words, it allows you to add a layer of encryption that you own and manage.

Before using Customer Key, you need to set up the required Azure resources. This article walks you through creating and configuring those resources, followed by the steps to enable Customer Key. After setting up Azure, you choose which policy applies, and in turn, which keys will encrypt data across Microsoft 365 workloads in your organization.

For a general overview and more information, see Overview of Customer Key.

Important

Be sure to follow the best practices in this article marked as TIP, IMPORTANT, and NOTE. Customer Key gives you control over root encryption keys that can affect your entire organization. Mistakes with these keys can lead to service interruptions or permanent data loss.

Tip

If you're not an E5 customer, use the 90-day Microsoft Purview solutions trial to explore how additional Purview capabilities can help your organization manage data security and compliance needs. Start now at the Microsoft Purview trials hub. Learn details about signing up and trial terms.

Important

Microsoft recommends that you use roles with the fewest permissions. Minimizing the number of users with the Global Administrator role helps improve security for your organization. Learn more about Microsoft Purview roles and permissions.

Before you set up Customer Key

Before you begin, make sure your organization has the right Azure subscriptions and Microsoft 365, Office 365, and Windows 365 licenses. You must use paid Azure subscriptions. Subscriptions acquired through Free, Trial, Sponsorship, MSDN, or Legacy Support programs aren't eligible.

Important

Microsoft 365 and Office 365 licenses that offer Microsoft 365 Customer Key:

  • Office 365 E5
  • Microsoft 365 E5
  • Microsoft 365 E5 Compliance
  • Microsoft 365 E5 Information Protection & Governance SKUs
  • Microsoft 365 Security and Compliance for FLW

Existing Office 365 Advanced Compliance licenses are still supported.

To better understand the concepts and procedures in this article, review the Azure Key Vault documentation. You should also be familiar with key Azure terms like Microsoft Entra tenant.

If you need help beyond the documentation, contact Microsoft Support. To share feedback or suggestions about Customer Key or this documentation, visit the Microsoft 365 Community.

Overview of steps to set up Customer Key

To set up Customer Key, complete the following tasks in order. The rest of this article provides detailed instructions for each task, or links out to more information for each step in the process.

In Azure:

Complete the following pre-requisites using Azure PowerShell. (version 4.4.0 or later is recommended):

Enable the tenant after completing the setup:

Complete tasks in Azure Key Vault for Customer Key

Complete the following tasks in Azure Key Vault. You only need to do this step once for each Customer Key workload you plan to use, such as Customer Key for Multiple Workloads, Exchange, or SharePoint and OneDrive.

Create two new Azure subscriptions

Customer Key requires two Azure subscriptions. As a best practice, Microsoft recommends creating new Azure subscriptions specifically for use with Customer Key.

Azure Key Vault keys can only be authorized for applications in the same Microsoft Entra tenant. To assign data encryption policies (DEPs), make sure to create both subscriptions under the same Microsoft Entra tenant used by your organization. For example, use your work or school account that has proper administrator privileges in your organization. For step-by-step guidance, see Sign up for Azure as an organization.

Important

Customer Key requires two keys for each data encryption policy (DEP). To support this requirement, you must create two separate Azure subscriptions. As a best practice, have different members of your organization manage one key in each subscription. These subscriptions should be used only to administer encryption keys for Microsoft 365. This configuration helps protect your organization in case someone accidentally, intentionally, or maliciously deletes or mismanages a key they control.

There's no practical limit to how many Azure subscriptions your organization can create. Following these best practices helps reduce the risk of human error and makes it easier to manage Customer Key resources.

Register the required Service Principals

To use the Customer Key, your tenant must have the required service principals registered. The following sections show you how to check whether the service principals are already registered in your tenant. If they aren't, run the 'New-AzADServicePrincipal' cmdlet.

Register the Service Principal for the Customer Key Onboarding Application

To check if the Customer Key Onboarding application is already registered with the correct permissions, run the following command:

Get-AzADServicePrincipal -ServicePrincipalName 19f7f505-34aa-44a4-9dcc-6a768854d2ea

If it isn't registered, run:

New-AzADServicePrincipal -ApplicationId 19f7f505-34aa-44a4-9dcc-6a768854d2ea

Register the Service Principal for the M365DataAtRestEncryption Application

To check if the M365DataAtRestEncryption application is already registered with the correct permissions, run the following command:

Get-AzADServicePrincipal -ServicePrincipalName c066d759-24ae-40e7-a56f-027002b5d3e4

If it isn't registered, run:

New-AzADServicePrincipal -ApplicationId c066d759-24ae-40e7-a56f-027002b5d3e4

Register the Service Principal for the Office 365 Exchange Online Application

To check if the Office 365 Exchange Online application is already registered with the correct permissions, run the following command:

Get-AzADServicePrincipal -ServicePrincipalName 00000002-0000-0ff1-ce00-000000000000

If it isn't registered, run:

New-AzADServicePrincipal -ApplicationId 00000002-0000-0ff1-ce00-000000000000

Create a premium Azure Key Vault in each subscription

To create a key vault, follow the steps in Getting Started with Azure Key Vault. These steps guide you through installing and launching Azure PowerShell, and connecting to your subscription. Next, create a resource group and a key vault.

When you create a key vault, you must choose a SKU: either Standard or Premium. The Standard SKU uses software-protected keys without a Hardware Security Module (HSM), while the premium SKU allows the use of HSMs to protect keys. Customer Key supports key vaults with either SKU, but Microsoft strongly recommends using the Premium SKU. The cost of operations is the same for both, so the only price difference comes from the monthly cost of each HSM-protected key. For pricing details, see Key Vault pricing.

If you're planning to use Azure Managed HSM instead of Azure Key Vault, see Customer Key using Managed HSM.

Important

Use the Premium SKU key vaults and HSM-protected keys for production data. Only use Standard SKU key vaults and keys for testing and validation.

For each Microsoft 365 workload you use Customer Key, create a key vault in each of the two Azure subscriptions you set up earlier.

For example, if your'e using Customer Key for Multiple Workloads, Exchange and SharePoint scenarios, you need three pairs of key vaults, for a total of six. Use a clear naming convention that reflects the intended use of the DEP with which you associate the vaults. The following table shows how to map each Azure Key Vault to each workload.

Key Vault Name Permissions for Multiple Microsoft 365 Workloads (M365DataAtRestEncryption) Permissions for Exchange Permissions for SharePoint and OneDrive
ContosoM365AKV01 Yes No No
ContosoM365AKV02 Yes No No
ContosoEXOAKV01 No Yes No
ContosoEXOAKV02 No Yes No
ContosoSPOAKV01 No No Yes
ContosoSPOAKV02 No No Yes

Vault Configuration

Creating key vaults also requires setting up Azure resource groups. Key vaults require a small amount of storage, and logging (if enabled) also stores data. As a best practice, Microsoft recommends assigning different administrators to manage each resource group. These roles should align with the admins responsible for managing the associated Customer Key resources.

For Exchange, a data encryption policy is scoped at the mailbox level. Each mailbox can have only one policy assigned, and you can create up to 50 policies. A SharePoint policy covers all data in an organization's geographic location (or geo), while a multi-workload policy covers supported workloads across all users in the organization.

Important

If you're using Customer Key for Multiple Workloads, Exchange, and SharePoint & OneDrive, make sure to create two Azure Key Vaults for each workload. This means you need a total of six key vaults.

Assign permissions to each key vault

Assign the required permissions to each key vault using Azure role-based access control (Azure RBAC) in the Azure portal. This section explains how to apply the correct permissions using RBAC.

Assigning permissions using RBAC method

To assign (wrapKey, unwrapkey, and get) on your Azure Key Vault, assign the Key Vault Crypto Service Encryption User role to the appropriate Microsoft 365 app. See Grant permission to applications to access an Azure key vault using Azure RBAC | Microsoft Learn.

When assigning the role, search for the following app names in your tenant:

  • Multiple Workloads: M365DataAtRestEncryption

  • Exchange: Office 365 Exchange Online

  • SharePoint and OneDrive: Office 365 SharePoint Online

If you don't see the app you're looking for, make sure you register the app in the tenant.

For more information about assigning roles and permissions, see Use role-based access control to manage access to your Azure subscription resources.

Assigning User roles

Customer Key requires both Key Vault Administrators and Key Vault Contributors to manage and safeguard access to encryption keys.

  • Key Vault Administrators handle daily management tasks such as backup, create, get, import, list, and restore. By design, they don’t have permission to delete keys. This helps prevent permanent data loss. Only grant delete permissions temporarily and with caution, using the Contributor role.

  • Key Vault Contributors can manage permissions and assign roles in the key vault. Use this role to control access when team members join or leave.

For detailed steps on assigning these roles using Azure RBAC, see Azure built-in roles for Key Vault data plane operations.

Add a key to each key vault either by creating or importing a key

There are two ways to add keys to an Azure Key Vault: you can create a key directly in the vault, or import an existing key. Creating a key in Azure is simpler, but importing a key gives you full control over how the key is generated. Use RSA keys. Customer Key supports RSA key lengths up to 4,096 bits. Azure Key Vault doesn't support wrapping and unwrapping with elliptical curve (EC) keys.

To add a key to each vault, see Add-AzKeyVaultKey.

If you prefer to generate a key on-premises and then import it into Azure, follow the steps in How to generate and transfer HSM-protected keys for Azure Key Vault. Use the Azure instructions to add a key to each key vault.

Verify expiration date of your keys

To check that your keys don't have an expiration date, run the Get-AzKeyVaultKey cmdlet.

For Azure Key Vault:

Get-AzKeyVaultKey -VaultName <vault name>

Customer Key can't use expired keys. If a key is expired, any operation using it fails, which can lead to a service outage. We strongly recommend that keys used with Customer Key don't have an expiration date.

Once set, an expiration date can't be removed, but you can change it. If you must use a key with an expiration date, update it to 12/31/9999 and use the legacy onboarding method. Any other expiration value fails Microsoft 365 validation.

Note

The Customer Key Onboarding Service only accepts keys without an expiration date.

To change the expiration date to 12/31/9999, use the Update-AzKeyVaultKey cmdlet.

Update-AzKeyVaultKey -VaultName <vault name> -Name <key name> -Expires (Get-Date -Date "12/31/9999")

Caution

Don't set expiration dates on encryption keys used with Customer Key.

Make sure soft delete is enabled on your key vaults

When you can quickly recover your keys, you're less likely to experience extended service outages from accidental or malicious deletion. This recovery feature is called soft delete. It allows you to recover deleted keys or vaults within 90 days without needing to restore from a backup.

Soft delete is automatically enabled for new Azure Key Vaults. If you use existing vaults where it's not turned on, you can enable it manually.

To enable soft delete on your key vaults, follow these steps:

  1. Sign in to your Azure subscription using Azure PowerShell. For help, see Sign in with Azure PowerShell.

  2. Run the Get-AzKeyVault cmdlet. Replace <vault name> with the name of your key vault:

    $v = Get-AzKeyVault -VaultName <vault name>
$r = Get-AzResource -ResourceId $v.ResourceId
$r.Properties | Add-Member -MemberType NoteProperty -Name enableSoftDelete -Value 'True'
Set-AzResource -ResourceId $r.ResourceId -Properties $r.Properties

  3. Confirm that soft delete is enabled by running:

    Get-AzKeyVault -VaultName <vault name> | fl

Check that Soft Delete Enabled is set to True, and Soft Delete Retention Period (days) is set to 90.

PowerShell output showing 'Soft Delete Enabled: True'

Back up Azure Key Vault Key

After you create or modify a key, make sure to immediately back it up. Store backup copies in both online and offline locations to help prevent data loss.

To back up a key in Azure Key Vault, use the Backup-AzKeyVaultKey cmdlet.

Important

If a key is deleted without a backup, it can't be recovered. Always create a backup after any key change or creation.

Obtain the URI for each Azure Key Vault key

After you set up your key vaults and add your keys, run the following command to get the URI for each key. You need these URIs when creating and assigning data encryption policies (DEPs), so be sure to save them somewhere secure.

Run the following command in Azure PowerShell—once for each key vault:

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

Onboard using the Customer Key Onboarding Service

The Microsoft 365 Customer Key Onboarding Service allows you to enable Customer Key in your tenant. This service automatically validates the required Customer Key resources. If you'd prefer, you can validate your resources separately before proceeding with enablement.

Important

This service isn't currently available for the following scenarios:

The account used for onboarding must have the following permissions:

  1. Service principal registration permissions: To register the required service principals.
  2. Reader role: On each Azure Key Vault used in the onboarding cmdlet.

Install the M365CustomerKeyOnboarding PowerShell module

  1. Sign in to your Azure subscription with Azure PowerShell. For guidance, see Sign in with Azure PowerShell.

  2. Install the latest version of the M365CustomerKeyOnboarding module from the PowerShell Gallery.

  • To confirm you're using the latest version, check the Version History tab at the bottom of the module page.
  • Copy and paste the install command into your session and run it.
  • If you're prompted, select Yes to All to continue.

Using the three different onboarding modes

There are three different onboarding modes available when using the Customer Key Onboarding Service: Validate, Prepare, and Enable. Each mode serves a different purpose in the onboarding process.

When running the cmdlet(see Create an Onboarding request), specify the mode using the -OnboardingMode parameter.

Validate

Use the Validate mode to confirm that your Customer Key resource configuration is correct. This mode doesn’t make any changes to your environment.

Important

You can run this mode as many times as needed, especially after making changes to your configuration.

Prepare

The Prepare mode registers the two Azure subscriptions specified in the cmdlet for a Mandatory Retention Period. This setting is a safeguard to prevent the accidental or immediate deletion of encryption keys, which could result in permanent data loss or service disruption.

After you run the cmdlet in this mode, it may take up to 1 hour for the subscriptions to reflect the change. Once complete, use Validate mode again to check the status.

Important

Registering the Mandatory Retention Period is required. You only need to run Prepare once per environment unless the cmdlet specifically prompts you to do so again.

Enable

Use the Enable mode when you're ready to onboard your tenant to Customer Key. This mode enables Customer Key for the specific workload you specify using the -Scenario parameter.

If you want to enable Customer Key for both Multiple Workloads and Exchange, run the cmdlet twice, once for each workload.

Before running in Enable mode, make sure your validation results show Passed under ValidationResult.

Important

Your resources must pass all checks in Validate mode for the onboarding process to succeed in Enable mode.

Creating an Onboarding request

The first step in the onboarding process is to create a new request. In PowerShell, you can store the results of a cmdlet in a variable using the $ symbol followed by the variable name.

In this example, the onboarding request is stored in a variable named $request:

$request = New-CustomerKeyOnboardingRequest -Organization <tenantID> -Scenario <Scenario> -Subscription1 <subscriptionID1> -VaultName1 <AKVVaultName1> -KeyName1 <KeyName1> -Subscription2 <subscriptionID2> -VaultName2 <AKVVaultName2> -KeyName2 <KeyName2> -OnboardingMode <OnboardingMode>
Parameter Description Example
-Organization Your tenant ID in the format xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx. abcd1234-abcd-efgh-hijk-abcdef123456
-Scenario The workload you're onboarding to. Options:
  • MDEP – Customer Key for Multiple Workloads
  • EXO – Customer Key for Exchange
 MDEP or EXO
-Subscription1 Azure subscription ID of the first subscription registered with a Mandatory Retention Period. p12ld534-1234-5678-9876-g3def67j9k12
-VaultName1 Name of the first Azure Key Vault configured for Customer Key. EXOVault1
-KeyName1 Name of the first key in your first Azure Key Vault. EXOKey1
-Subscription2 Azure subscription ID of the second subscription registered with a Mandatory Retention Period. 21k9j76f-ed3g-6789-8765-43215dl21pbd
-VaultName2 Name of the second Azure Key Vault configured for Customer Key. EXOVault2
-KeyName2 Name of the second key in your second Azure Key Vault. EXOKey2
-OnboardingMode The onboarding action to perform. Options:
  • Prepare – Applies the Mandatory Retention Period to your subscriptions. May take up to 1 hour to take effect.
  • Validate – Validates your configuration without making changes. Useful for verifying before onboarding.
  • Enable – Validates and enables Customer Key in your tenant if validation passes.
 Prepare, Validate, or Enable

Log in with your tenant admin credentials

When prompted, a browser window opens. Sign in using your tenant admin account with the necessary privileges to complete onboarding.

Prompt to sign in with a privileged account

View the validation and enablement details

After successfully signing in, return to your PowerShell window. Run the variable you used when creating the onboarding request to view its output:

$request

CKO Request Output

You receive an output that includes ID, CreatedDate, ValidationResult, and EnablementResult.

Output Description
ID ID associated with the created onboarding request.
CreatedDate Date of when the request was created.
ValidationResult Indicator of successful/unsuccessful validation.
EnablementResult Indicator of successful/unsuccessful enablement.

A tenant that's ready to use Customer Key shows Success for both ValidationResult and EnablementResult as shown:

CKO Successful Output

If both values show Success proceed to Next Steps.

Troubleshooting failed validations details

If validation fails during onboarding, use the following steps to investigate the cause. This process helps identify which Customer Key resources are misconfigured.

  1. List all onboarding requests for your tenant to find the RequestID of the one you want to investigate:
Get-CustomerKeyOnboardingRequest -OrganizationID <OrganizationID>
  1. Store the specific onboarding request into a variable:
$request = Get-CustomerKeyOnboardingRequest -OrganizationID <OrganizationID> -RequestID <RequestID>
  1. View the failed validation details:
$request.FailedValidations

Example of failed validation output in PowerShell

Each validation rule includes the following fields:

  • ExpectedValue: What the resource configuration should be.
  • ActualValue: What was detected in your environment.
  • Scope: The first five characters of the subscription ID that helps you identify which subscription (and its associated key vault) has the issue.
  • Details: Describes the root cause and offers guidance to resolve the problem.

The following table summarizes common validation rules and how to resolve failures:

RuleName Description Solution
MandatoryRetentionPeriodState Returns the state of the MandatoryRetentionPeriod. Verify that you ran Prepare mode. If the issue persists, see Incorrect Mandatory Retention Period State.
SubscriptionInRequestOrganization Confirms your Azure subscription belongs to your organization. Make sure the subscription was created within the specified tenant.
VaultExistsinSubscription Confirms the Azure Key Vault is part of the given subscription. Verify the key vault was created in the correct subscription.
SubscriptionUniquePerScenario Ensures you're using two unique subscriptions per scenario. Double-check that both subscription IDs are different.
SubscriptionsCountPerScenario Confirms two subscriptions were provided. Make sure your onboarding request includes two subscriptions.
RecoveryLevel Checks if the key vault recovery level is Recoverable+ProtectedSubscription. See Incorrect Mandatory Retention Period State.
KeyOperationsSupported Verifies the key supports required operations for the workload. See Assign the proper permissions to AKV keys.
KeyNeverExpires Ensures the key has no expiration date. See Verify the expiration of your keys.
KeyAccessPermissions Confirms the key has the right access permissions. See Assign the proper permissions to AKV keys.
OrganizationHasRequiredServicePlan Verifies your organization has the required licenses. See Ensure your tenant has the required licenses.

Incorrect mandatory retention period state

If the MandatoryRetentionPeriodState remains set to Recoverable or Recoverable+Purgeable more than one hour after running the onboarding cmdlet in Prepare mode, and you already enabled soft delete on your Azure Key Vaults, follow these steps to troubleshoot and resolve the issue:

  1. Check feature registration status
    Run the following commands in Azure PowerShell to confirm that both Azure subscriptions show a state of Registered:
Set-AzContext -SubscriptionId <Subscription ID>
Get-AzProviderFeature -FeatureName mandatoryRetentionPeriodEnabled -ProviderNamespace Microsoft.Resources

  1. Re-register required resource providers
    Re-register both the Microsoft.Resources and Microsoft.KeyVault resource providers in each subscription. You can do this action through Azure PowerShell, Azure CLI, or the Azure portal:

    • Azure PowerShell:

        Register-AzResourceProvider -ProviderNamespace Microsoft.Resources 
  Register-AzResourceProvider -ProviderNamespace Microsoft.Keyvault

    • Azure CLI:

        az provider register --namespace Microsoft.Resources 
  az provider register --namespace Microsoft.Keyvault

    • Azure portal: Re-register Resource Provider

  2. Verify key recovery level
    To confirm that a key has the correct recovery level, run the following command in Azure PowerShell.

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

    Look for the RecoveryLevel property in the output. It should be set to Recoverable+ProtectedSubscription

Checking passed validations

To view which validations were successful during the onboarding process, follow these steps:

  1. Store the specific onboarding request into the variable '$request'
$request = Get-CustomerKeyOnboardingRequest -OrganizationID <OrganizationID> -RequestID <RequestID>
  1. Run the following command to display all passed validations:
$request.PassedValidations

This command returns a list of all the validations that passed successfully for the selected onboarding request.

CKO PassedValidation

Onboard to Customer Key using the legacy method

Use this method only if the Customer Key Onboarding Service doesn't support your tenant's scenario.

After completing all required steps to set up your Azure Key Vaults and subscriptions, contact Microsoft Support and request assistance with Customer Key onboarding.

Onboard to Customer Key for special clouds

If your tenant is located in GCC-H, DoD, or Gallatin, complete all required Customer Key setup steps first.

Onboard to Customer Key for SharePoint and OneDrive

To onboard to Customer Key for SharePoint and OneDrive, your tenant must meet the following prerequisites:

  1. The tenant is already onboarded to Customer Key for either Multiple Workloads or Exchange.
  2. Both Azure subscriptions are registered with a Mandatory Retention Period.

If both prerequisites are satisfied, follow the steps in Create a DEP for use with SharePoint and OneDrive.

Next steps

After completing the setup steps in this article, you're ready to create and assign data encryption policies (DEPs). For detailed instructions, see Manage Customer Key.