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.
After setting up Customer Key, the next step is to create and assign one or more data encryption policies (DEPs). Once assigned, you can manage your encryption keys and policies as described in this article.
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.
Microsoft Purview Customer Key also supports Windows 365 Cloud PCs. For more information, see Microsoft Purview Customer Key for Windows 365 Cloud PCs.
To learn more about Customer Key concepts and setup, see the related articles at the end of this page.
Create a DEP for use with multiple workloads for all tenant users
Before proceeding, complete the Customer Key setup steps. For guidance, see Set up Customer Key.
To create the DEP, you need the Key Vault URIs retrieved during setup. See Obtain the URI for each Azure Key Vault key for instructions.
On your local computer, sign in using a work or school account with Compliance Administrator permissions, and connect to Exchange Online PowerShell.
Run the following cmdlet to create a multi-workload data encryption policy:
New-M365DataAtRestEncryptionPolicy -Name <PolicyName> -AzureKeyIDs <KeyVaultURI1, KeyVaultURI2> [-Description <String>]Parameter definitions:
-Name: The name you want to use for the policy. No spaces allowed.-AzureKeyIDs: URIs of the two Azure Key Vault keys used in the policy, separated by commas.Example:
"https://contosoCentralUSvault1.vault.azure.net/keys/Key_02""https://contosoWestUSvault1.vault.azure.net/keys/Key_01"Description(optional): A human-readable description of the policy.Example:
"Policy for multiple workloads for all users in the tenant."
New-M365DataAtRestEncryptionPolicy -Name "Contoso_Global" -AzureKeyIDs "https://contosoWestUSvault1.vault.azure.net/keys/Key_01","https://contosoCentralUSvault1.vault.azure.net/keys/Key_02" -Description "Policy for multiple workloads for all users in the tenant."
Assign multi-workload policy
After creating a multi-workload data encryption policy (DEP), assign it using the Set-M365DataAtRestEncryptionPolicyAssignment cmdlet. Once assigned, Microsoft 365 encrypts your organization's data using the keys specified in the DEP.
Set-M365DataAtRestEncryptionPolicyAssignment -DataEncryptionPolicy <PolicyName or ID>
Replace <PolicyName or ID> with the name or GUID of the policy.
Example:
Set-M365DataAtRestEncryptionPolicyAssignment -DataEncryptionPolicy "Contoso_Global"
Windows 365 Cloud PCs:
After assigning the policy, allow 3–4 hours for the Intune admin center to reflect the update. Once updated, follow the steps in the admin center to encrypt existing Cloud PCs.
For more information, see Set up Customer Keys for your Windows 365 Cloud PCs.
Create a DEP for use with Exchange mailboxes
Before you begin, complete the required setup steps. For details, see Set up Customer Key. To create the DEP, you’ll need the Azure Key Vault URIs obtained during setup. For more info, see Obtain the URI for each Azure Key Vault key.
To create a DEP for Exchange mailboxes, follow these steps:
On your local computer, using a work or school account that has Exchange admin permissions, connect to Exchange Online PowerShell.
Create a DEP using the
New-DataEncryptionPolicycmdlet:New-DataEncryptionPolicy -Name <PolicyName> -Description "Policy Description" -AzureKeyIDs <KeyVaultURI1>, <KeyVaultURI2>
| Parameter | Description | Example |
|---|---|---|
-Name |
Enter a name for the policy. Names can't contain spaces. | USA_mailboxes |
-AzureKeyIDs |
Enter the URIs for two keys in separate Azure Key Vaults. Separate them with a comma and a space. | https://contosoEastUSvault01.vault.azure.net/keys/USA_key_01, https://contosoEastUS2vault01.vault.azure.net/keys/USA_key_02 |
-Description |
A user-friendly description that helps identify the policy’s purpose. | "Root key for mailboxes in USA and its territories" |
Example:
New-DataEncryptionPolicy -Name USA_mailboxes -Description "Root key for mailboxes in USA and its territories" -AzureKeyIDs https://contoso_EastUSvault02.vault.azure.net/keys/USA_key_01, https://contoso_CentralUSvault02.vault.azure.net/keys/USA_Key_02
For syntax and parameter information, see New-DataEncryptionPolicy.
Assign a DEP to a mailbox
Assign the DEP by using the Set-Mailbox cmdlet. Once you assign the policy, Microsoft 365 encrypts the mailbox with the keys identified in the DEP.
Set-Mailbox -Identity <MailboxIdParameter> -DataEncryptionPolicy <PolicyName>
| Parameter | Description |
|---|---|
-Identity |
Specifies the mailbox to assign the DEP to. Use a valid user identifier. |
-DataEncryptionPolicy |
Name of the Data Encryption Policy (DEP) to assign to the mailbox. |
For more information, see Set-Mailbox.
Assign a DEP to hybrid mailboxes
In hybrid environments, assign a DEP to synchronized on-premises mailbox data using the Set-MailUser cmdlet.
Set-MailUser -Identity <MailUserIdParameter> -DataEncryptionPolicy <PolicyName>
| Parameter | Description |
|---|---|
-Identity |
Specifies the mail user (mail-enabled user) to assign the DEP to. |
-DataEncryptionPolicy |
Name of the Data Encryption Policy (DEP) to assign to the mail user. |
For more information, see Set-MailUser.
To learn more about hybrid mailbox support, see on-premises mailboxes using Outlook for iOS and Android with hybrid Modern Authentication.
Assign a DEP before you migrate a mailbox to the cloud
Assigning a Data Encryption Policy (DEP) before migrating a mailbox ensures that mailbox contents are encrypted during migration. This method is more efficient than assigning the DEP after migration, which might result in delays while the encryption process completes.
Using a work or school account that has proper permissions in your organization, connect to Exchange Online PowerShell.
Run the following command:
Set-MailUser -Identity <GeneralMailboxOrMailUserIdParameter> -DataEncryptionPolicy <DataEncryptionPolicyIdParameter>
| Parameter | Description |
|---|---|
-Identity |
Specifies the user mailbox (or mail-enabled user) |
-DataEncryptionPolicy |
Name or ID of the data encryption policy to apply. |
For more information, see Set-MailUser.
View the DEPs you created for Exchange mailboxes
You can view all Data Encryption Policies (DEPs) created for Exchange mailboxes using PowerShell.
Using a work or school account that has proper permissions in your organization, connect to Exchange Online PowerShell.
To return all DEPs in your organization, run the following command:
Get-DataEncryptionPolicyFor detailed cmdlet information, see Get-DataEncryptionPolicy.
Determine the DEP assigned to a mailbox
To determine the DEP assigned to a mailbox, use the Get-MailboxStatistics cmdlet. The cmdlet returns a unique identifier (GUID).
Using a work or school account that has proper permissions in your organization, connect to Exchange Online PowerShell.
Get-MailboxStatistics -Identity <GeneralMailboxOrMailUserIdParameter> | fl DataEncryptionPolicyID
| Parameter | Description |
|---|---|
-Identity |
Specifies the user mailbox (or mail-enabled user) |
DataEncryptionPolicyID |
Returns the GUID of the DEP. |
For more information about the Get-MailboxStatistics cmdlet, see Get-MailboxStatistics.
Run the Get-DataEncryptionPolicy cmdlet to find out the friendly name of the DEP to which the mailbox is assigned.
Get-DataEncryptionPolicy <GUID>Where GUID is the GUID returned by the Get-MailboxStatistics cmdlet in the previous step.
Create a DEP for use with SharePoint and OneDrive
Before you begin, make sure you complete the required setup steps. For more information, see Set up Customer Key.
To configure Customer Key for SharePoint and OneDrive, use SharePoint PowerShell.
About Data Encryption Policies:
A Data Encryption Policy (DEP) is associated with two keys stored in separate Azure Key Vaults. These keys must reside in different Azure regions to avoid geo-redundancy.
Single-geo tenants: You can create one DEP to protect all data in your geo.
Multi-geo tenants: Create one DEP per geo, each using different keys.
You need the Key Vault URIs for both keys. For details, see Obtain the URI for each Azure Key Vault key.
On your local computer, using a work or school account that has proper permissions in your organization, connect to SharePoint PowerShell.
Use the
Register-SPODataEncryptionPolicycmdlet to register the DEP.Register-SPODataEncryptionPolicy -PrimaryKeyVaultName <PrimaryKeyVaultName> -PrimaryKeyName <PrimaryKeyName> -PrimaryKeyVersion <PrimaryKeyVersion> -SecondaryKeyVaultName <SecondaryKeyVaultName> -SecondaryKeyName <SecondaryKeyName> -SecondaryKeyVersion <SecondaryKeyVersion>Example:
Register-SPODataEncryptionPolicy -PrimaryKeyVaultName 'stageRG3vault' -PrimaryKeyName 'SPKey3' -PrimaryKeyVersion 'f635a23bd4a44b9996ff6aadd88d42ba' -SecondaryKeyVaultName 'stageRG5vault' -SecondaryKeyName 'SPKey5' -SecondaryKeyVersion '2b3e8f1d754f438dacdec1f0945f251a'If using Managed HSM: Use the full URL of the key including version for each vault.
Register-SPODataEncryptionPolicy -PrimaryKeyVaultURL <PrimaryKeyVaultURL> -SecondaryKeyVaultURL <SecondaryKeyVaultURL>Example:
Register-SPODataEncryptionPolicy -PrimaryKeyVaultURL https://M365-Test.managedhsm.azure.net/keys/Sharepoint-01/aaaa5513974f4780ea67b2f5d8c3dd -SecondaryKeyVaultURL https://M365-Test-02.managedhsm.azure.net/keys/Sharepoint-02/7d8f30343bed4e44a57225bae2012388Note
Once the DEP is registered, encryption of the geo's data begins. This process might take some time.
For full cmdlet reference, see Register-SPODataEncryptionPolicy.
Verify that encryption with Customer Key is complete
After rolling a Customer Key, assigning a new data encryption policy (DEP), or migrating a mailbox, follow the steps in this section to confirm that encryption is complete.
Verify encryption completes for Exchange mailboxes
Encrypting a mailbox can take time. For first-time encryption, the mailbox must be fully moved to a new database before encryption can complete.
To check if a mailbox is encrypted, use the Get-MailboxStatistics cmdlet:
Get-MailboxStatistics -Identity <GeneralMailboxOrMailUserIdParameter> | fl IsEncrypted
The IsEncrypted property returns true if the mailbox is encrypted, and false if it's not.
The time required to complete mailbox moves depends on the number of mailboxes being encrypted for the first time and their sizes. If a mailbox isn't encrypted within one week of assigning the data encryption policy (DEP), contact Microsoft Support.
Note
The New-MoveRequest cmdlet is no longer available for local mailbox moves. For more information, see this announcement.
Verify encryption completes for SharePoint and OneDrive
Check on the status of encryption by running the Get-SPODataEncryptionPolicy cmdlet as follows:
Get-SPODataEncryptionPolicy <SPOAdminSiteUrl>
The output from this cmdlet includes:
Primary key URI
The URI of the primary key.
Secondary key URI
The URI of the primary key.
Encryption Status for the geo
The status can be one of the following states:
- Unregistered: Customer Key encryption is not applied.
- Registering: Customer Key encryption is in progress. If the key for the geo is registering, the output includes the percentage of encrypted sites so you can monitor progress.
- Registered: Customer Key encryption is complete. All files in all sites are encrypted.
- Rolling: A key roll is in progress. If the key for the geo is rolling, the output includes the percentage of completed site rollouts so you can monitor progress.
Sites onboarded
The percentage of sites onboarded for encryption.
Get details about DEPs you use with multiple workloads
To view details about the DEPs you created for use with multiple workloads, follow these steps:
On your local computer, use a work or school account with Compliance Administrator permissions to connect to Exchange Online PowerShell.
Run the following command to list all multi-workload DEPs in your organization:
Get-M365DataAtRestEncryptionPolicyTo view details about a specific DEP, use the following command. This example shows information for the DEP named
Contoso_Global:Get-M365DataAtRestEncryptionPolicy -Identity "Contoso_Global"
Get multi-workload DEP assignment information
To identify which DEP is currently assigned to your tenant, follow these steps:
On your local computer, use a work or school account with Compliance Administrator permissions to connect to Exchange Online PowerShell.
Run the following command:
Get-M365DataAtRestEncryptionPolicyAssignment
Disable a multi-workload DEP
Before you disable a multi-workload DEP, unassign the DEP from workloads in your tenant. To disable a DEP used with multiple workloads, complete these steps:
On your local computer, use a work or school account with Compliance Administrator permissions to connect to Exchange Online PowerShell.
Run the following command, replacing
PolicyNamewith the name or unique ID of the policy (for example,Contoso_Global):Set-M365DataAtRestEncryptionPolicy -[Identity] "PolicyName" -Enabled $falseExample:
Set-M365DataAtRestEncryptionPolicy -Identity "Contoso_Global" -Enabled $false
Restore Azure Key Vault keys
Before performing a restore, use the soft delete feature to recover keys if possible. All keys used with Customer Key must have soft delete enabled. Soft delete functions like a recycle bin and allows you to recover deleted keys for up to 90 days without needing a full restore.
Key restoration should only be necessary in rare or exceptional cases—for example, if a key or key vault is permanently lost.
To restore a key using Azure PowerShell, run the following command:
Restore-AzKeyVaultKey -VaultName <vault name> -InputFile <filename>
Example:
Restore-AzKeyVaultKey -VaultName Contoso-O365EX-NA-VaultA1 -InputFile Contoso-O365EX-NA-VaultA1-Key001-Backup-20170802.backup
Important
If the key vault already contains a key with the same name, the restore operation fails. The Restore-AzKeyVaultKey cmdlet restores all versions of the key, including its metadata and name.
Manage key vault permissions
You can use Azure PowerShell to view or remove key vault permissions. For example, you might need to remove a user's access when they leave the team.
Tip
To get started with Azure PowerShell, see Overview of Azure PowerShell.
To view the permissions for a key vault, run the following command:
Get-AzKeyVault -VaultName <vault name>
Example:
Get-AzKeyVault -VaultName Contoso-O365EX-NA-VaultA1
To remove a user's access to a key vault, use the following command:
Remove-AzKeyVaultAccessPolicy -VaultName <vault name> -UserPrincipalName <UPN of user>
Example:
Remove-AzKeyVaultAccessPolicy -VaultName Contoso-O365EX-NA-VaultA1 -UserPrincipalName alice@contoso.com
Roll back from Customer Key to Microsoft managed Keys
If needed, you can revert to using Microsoft-managed keys. When you roll back, your data is re-encrypted using the default encryption method supported by each workload. For example, Exchange and Windows 365 Cloud PCs use Microsoft-managed keys for default encryption.
Important
Rolling back isn't the same as performing a data purge.
- A data purge permanently crypto-deletes your organization's data from Microsoft 365.
- A roll back reverts encryption but doesn't delete any data.
- You can't perform a data purge for a multi-workload policy.
Roll back from Customer Key for multiple workloads
If you no longer want to use Customer Key with multi-workload data encryption policies (DEPs), submit a support request through Microsoft Support. Include the following information in your request:
- Tenant fully qualified domain name (FQDN)
- Tenant contact for the rollback request
- Reason for discontinuing Customer Key
- Incident number
Important
You must retain your Azure Key Vaults (AKVs) and encryption keys with the appropriate permissions. This action is required so that data can be rewrapped using Microsoft-managed keys.
Important
Rolling back from Customer Key for multiple workloads is not supported in Gallatin.
Roll back from Customer Key for Exchange
If you no longer want to encrypt individual mailboxes using mailbox-level data encryption policies (DEPs), you can unassign those DEPs from all mailboxes.
To unassign a mailbox-level DEP, follow these steps:
Use a work or school account that has the necessary Exchange Online PowerShell permissions, and connect to Exchange Online PowerShell.
Run the following cmdlet.
Set-Mailbox -Identity <mailbox> -DataEncryptionPolicy $null
This command unassigns the current DEP and re-encrypts the mailbox using the default Microsoft-managed keys.
Note
You can't unassign the DEP associated with Microsoft-managed keys. If you don't want to use Microsoft-managed keys, assign a different DEP to the mailbox instead.
Roll back from Customer Key for SharePoint and OneDrive
Rolling back from Customer Key to Microsoft-managed keys isn't supported for SharePoint or OneDrive.
Revoke your keys and start the data purge path
You control the revocation of all root keys, including the availability key. Customer Key gives you control over the exit planning process required by many regulatory standards. If you decide to revoke your keys to purge data and exit the service, the availability key is deleted after the data purge process completes.
This functionality is only supported for Customer Key DEPs assigned to individual mailboxes.
Microsoft 365 audits and validates the data purge process. For more information, see the SSAE 18 SOC 2 Report available on the Service Trust Portal.
Microsoft also recommends reviewing the following documents:
Important
Purging a multi-workload DEP isn't supported. These policies encrypt data across multiple workloads and users within your tenant. Purging such a DEP would make data across all workloads inaccessible.
If you're exiting Microsoft 365 services entirely, see how to delete a tenant in Microsoft Entra ID.
Revoke your Customer Keys and the availability key for Exchange
When you initiate the data purge path for Exchange, you place a permanent data purge request on a data encryption policy (DEP). This action permanently deletes encrypted data in all mailboxes assigned to that DEP.
Because the PowerShell cmdlet works on only one DEP at a time, consider reassigning a single DEP to all mailboxes before starting the data purge process.
Warning
Don't use the data purge path to delete a subset of mailboxes. This process is intended only for organizations that are fully exiting the service.
To initiate the data purge path, follow these steps:
Remove wrap and unwrap permissions for O365 Exchange Online from your Azure Key Vaults.
Use a work or school account with the appropriate Exchange Online PowerShell permissions, and connect to Exchange Online PowerShell.
For each DEP that includes mailboxes you want to purge, run the
Set-DataEncryptionPolicycmdlet:Set-DataEncryptionPolicy <Policy ID> -PermanentDataPurgeRequested -PermanentDataPurgeReason <Reason> -PermanentDataPurgeContact <ContactName>If the command fails, confirm that Exchange Online permissions were removed from both keys in the Azure Key Vault, as noted earlier. After you run the
Set-DataEncryptionPolicycmdlet with the-PermanentDataPurgeRequestedswitch, the DEP can't be assigned to mailboxes anymore.Contact Microsoft Support and request the Data Purge eDocument.
Microsoft sends a legal document to confirm and authorize the data purge. The person in your organization who was listed as the approver during onboarding (typically through the FastTrack program) must sign this document. This person is usually an executive or other legally authorized representative.
After your representative signs the document, return it to Microsoft (usually via e-signature).
Once Microsoft receives the signed eDocument, they run the necessary cmdlets to complete the data purge. This process deletes the DEP, marks affected mailboxes for permanent deletion, and removes the availability key. After the process finishes, the data is purged, inaccessible to Exchange, and can't be recovered.
Revoke your Customer Keys and the availability key for SharePoint and OneDrive
Purging DEPs for SharePoint and OneDrive isn't supported in Customer Key. If you're exiting Microsoft 365 services entirely, you can follow the documented process to delete your tenant.
For details, see how to delete a tenant in Microsoft Entra ID.
Migrate your Key Vaults from the legacy access policy model to RBAC
If you onboarded to Customer Key using the legacy access policy model, follow these steps to migrate all Azure Key Vaults to use role-based access control (RBAC). To compare the two models and understand why Microsoft recommends RBAC, see Azure role-based access control (Azure RBAC) vs. access policies (legacy).
Remove legacy access policies
To remove the existing access policies from your Key Vaults, use the Remove-AzKeyVaultAccessPolicy cmdlet.
Sign in to your Azure subscription with Azure PowerShell. For guidance, see Sign in with Azure PowerShell.
Run the following command to remove access for the Microsoft 365 Service principal:
Remove-AzKeyVaultAccessPolicy -VaultName <VaultName> -ServicePrincipalName c066d759-24ae-40e7-a56f-027002b5d3e4Run the following command to remove access for the Exchange Online principal:
Remove-AzKeyVaultAccessPolicy -VaultName <VaultName> -ServicePrincipalName 00000002-0000-0ff1-ce00-000000000000Run the following command to remove access for the SharePoint and OneDrive for work or school service principal:
Remove-AzKeyVaultAccessPolicy -VaultName <VaultName> -ServicePrincipalName 00000003-0000-0ff1-ce00-000000000000
Changing the Access configuration permission model
After removing the access policies, update the permission model for each Key Vault in the Azure portal:
In the Azure portal, navigate to your Key Vault.
In the left-hand menu, under Settings, select Access configuration.
Under Permission model, choose Azure role-based access control.
Select Apply at the bottom of the screen.
Assigning RBAC permissions
After you switch the permission model, follow the steps in Assign permissions to each Key Vault to grant the necessary roles.