Controlling your data in Office 365 using Customer Key

With Customer Key, you control your organization's encryption keys and then configure Office 365 to use them to encrypt your data at rest in Microsoft's data centers. Data at rest includes data from Exchange Online and Skype for Business that is stored in mailboxes and files that are stored in SharePoint Online and OneDrive for Business.

You must set up Azure before you can use Customer Key for Office 365. This topic describes the steps you need to follow to create and configure the required Azure resources and then provides the steps for setting up Customer Key in Office 365. After you have completed Azure setup, you determine which policy, and therefore, which keys, to assign to mailboxes and files in your organization. Mailboxes and files for which you don't assign a policy will use encryption policies that are controlled and managed by Microsoft. For more information about Customer Key, or for a general overview, see the Customer Key for Office 365 FAQ.

Note: We strongly recommend that you follow the best practices in this topic. These are called out as TIP and IMPORTANT. Customer Key gives you control over root encryption keys whose scope can be as large as your entire organization. This means that mistakes made with these keys can have a broad impact and may result in service interruptions or irrevocable loss of your data.

Before you begin setting up Customer Key

Before you get started, be sure you have the appropriate licensing for your organization. Customer Key in Office 365 is offered in Office 365 E5 or the Advanced Compliance SKU.

Then, to understand the concepts and procedures in this topic, you should review the Azure Key Vault documentation. Also, become familiar with the terms used in Azure, for example, tenant.

Overview of setting up Customer Key for Office 365

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

In Azure and Microsoft FastTrack:   

You will complete most of these tasks by remotely connecting to Azure PowerShell. For best results, use version 4.4.0 or later of Azure PowerShell.

In Office 365:   

Exchange Online and Skype for Business:

SharePoint Online and OneDrive for Business:

Complete tasks in Azure Key Vault and Microsoft FastTrack for Customer Key

Complete these tasks in Azure Key Vault in order to set up Customer Key for Office 365. You will need to complete these steps regardless of whether you intend to set up Customer Key for Exchange Online and Skype for Business or SharePoint Online and OneDrive for Business or for all supported services in Office 365.

Create two new Azure subscriptions

Two Azure subscriptions are required for Customer Key. As a best practice, Microsoft recommends that you create new Azure subscriptions for use with Customer Key. Azure Key Vault keys can only be authorized for applications in the same Azure Active Directory (AAD) tenant, you must create the new subscriptions using the same Azure AD tenant used with your Office 365 organization where the DEPs will be assigned. For example, using your work or school account that has global administrator privileges in your Office 365 organization. For detailed steps, see Sign up for Azure as an organization.

Notes: 

  • Customer Key requires two keys for each data encryption policy (DEP). In order to achieve this, you must create two Azure subscriptions. As a best practice, Microsoft recommends that you have separate members of your organization configure one key in each subscription. In addition, these Azure subscriptions should only be used to administer encryption keys for Office 365. This protects your organization in case one of your operators accidentally, intentionally, or maliciously deletes or otherwise mismanages the keys for which they are responsible.

  • We recommend that you set up new Azure subscriptions that are solely used for managing Azure Key Vault resources for use with Customer Key. There is no practical limit to the number of Azure subscriptions that you can create for your organization. Following these best practices will minimize the impact of human error while helping to manage the resources used by Customer Key.

Submit a request to activate Customer Key for Office 365 through Microsoft FastTrack

Once you've completed the Azure steps, you'll need to submit an Offer request in the Microsoft FastTrack portal. When you submit your request through FastTrack, Microsoft verifies your Azure Key Vault setup, and collects important contact information from you that we will need if you ever choose to revoke Office 365’s access to your keys. You'll need to do this step once to activate Customer Key for Exchange Online and Skype for Business coverage and once to activate Customer Key for SharePoint Online and OneDrive for Business.

To submit an offer to activate Customer Key, complete these steps:

  1. Using a work or school account that has global administrator permissions in your Office 365 organization, log in to the Microsoft FastTrack portal.

  2. Once you're logged in, browse to the Dashboard.

  3. Choose Offers, and review the list of current offers.

  4. Choose Learn More for the offer that applies to you:

    • Exchange Online and Skype for Business: Choose Learn More on the Customer Key for Exchange offer.

    • SharePoint Online and OneDrive for Business: Chose Learn More on the Customer Key for SharePoint and OneDrive for Business offer.

  5. On the Offer details page, choose Create Request.

  6. Fill out all applicable details and requested information on the offer form and then choose Submit.

    Once you have submitted the offer form, wait until Microsoft notifies you that you can proceed. This process can take up to five business days once Microsoft has been notified of your request.

Register Azure subscriptions as Do Not Cancel (DNC)

The temporary or permanent loss of root encryption keys can be very disruptive or even catastrophic to service operation and can result in data loss. For this reason, the resources used with Customer Key require strong protection. All the Azure resources that are used with Customer Key offer protection mechanisms beyond the default configuration. Azure subscriptions can be tagged or registered in a way that will prevent immediate and irrevocable cancellation. This is referred to as Do Not Cancel (DNC). The steps required to register Azure subscriptions require collaboration with the Office 365 team. This process can take several days.

Before contacting the Office 365 team, you must perform the following steps for each Azure subscription that you use with Customer Key:

  1. Log in to your Azure subscription with Azure PowerShell. For instructions, see Log in with Azure PowerShell.

  2. Run the Register-AzureRmProviderFeature cmdlet to register your subscriptions as Do Not Cancel.

    Register-AzureRmProviderFeature -FeatureName mandatoryRetentionPeriodEnabled -ProviderNamespace Microsoft.Resources
  3. Contact Microsoft to have the process finalized. For the SharePoint and OneDrive for Business team, contact spock@microsoft.com. For Exchange Online and Skype for Business, contact exock@microsoft.com. The Service Level Agreement (SLA) for completion of this process is five business days once Microsoft has been notified (and verified) that you have registered your subscriptions for DNC.

  4. Wait until Microsoft notifies you that you can proceed. This can take up to five days.

  5. Once you receive notification from Microsoft, check the status of your registration by running the Get-AzureRmProviderFeature cmdlet as follows:

    Get-AzureRmProviderFeature -ProviderNamespace Microsoft.Resources -FeatureName mandatoryRetentionPeriodEnabled
  6. Once the Registration State property from the Get-AzureRmProviderFeature cmdlet returns a value of Registered, run the following command to complete the process:

    Register-AzureRmResourceProvider -ProviderNamespace "Microsoft.KeyVault"

Create a premium Azure Key Vault in each subscription

The steps to create a key vault are documented in Getting Started with Azure Key Vault, which guides you through installing and launching Azure PowerShell, connecting to your Azure subscription, creating a resource group, and creating a key vault in that resource group.

When you create a key vault, you must choose a SKU: either Standard or Premium. The Standard SKU allows Azure Key Vault keys to be protected with software – there is no Hardware Security Module (HSM) key protection – and the Premium SKU allows the use of HSMs for protection of Key Vault keys. Customer Key accepts key vaults that use either SKU, though Microsoft strongly recommends that you use only the Premium SKU. The cost of operations with keys of either type is the same, so the only difference in cost is the cost per month for each HSM-protected key. See Key Vault pricing for details.

Note: Use the Premium SKU key vaults and HSM-protected keys for production data, and only use Standard SKU key vaults and keys for testing and validation purposes.

For each Office 365 service with which you will use Customer Key, create a key vault in each of the two Azure subscriptions that you created. For example, for Exchange Online and Skype for Business only or SharePoint Online and OneDrive for Business only, you will create only one pair of vaults. To enable Customer Key for both Exchange Online and SharePoint Online, you will create two pairs of key vaults.

Use a naming convention for key vaults that reflects the intended use of the DEP with which you will associate the vaults. See the Best Practices section below for naming convention recommendations.

Create a separate, paired set of vaults for each data encryption policy. For Exchange Online, the scope of a data encryption policy is chosen by you when you assign the policy to mailbox. A mailbox can have only one policy assigned, and you can create up to fifty policies. For SharePoint Online the scope of a policy is all of the data within an organization in a geographic location, or geo.

The creation of key vaults also requires the creation of Azure resource groups, since key vaults need storage capacity (though very small) and Key Vault logging, if enabled, also generates stored data. As a best practice Microsoft recommends using separate administrators to manage each resource group, with the administration aligned with the set of administrators that will manage all related Customer Key resources.

Notes: 

  • To maximize availability, your key vaults should be in regions close to your Office 365 service. For example, if your Exchange Online organization is in North America, place your key vaults in North America. If your Exchange Online organization is in Europe, place your key vaults in Europe.

  • Use a common prefix for key vaults, and include an abbreviation of the use and scope of the key vault and keys (e.g., for the Contoso SharePoint service where the vaults will be located in North America, a possible pair of names is Contoso-O365SP-NA-VaultA1 and Contoso-O365SP-NA-VaultA2. Vault names are globally unique strings within Azure, so you may need to try variations of your desired names in case the desired names are already claimed by other Azure customers. As of July 2017 vault names cannot be changed, so a best practice is to have a written plan for setup and use a second person to verify the plan is executed correctly.

  • If possible, create your vaults in non-paired regions. Paired Azure regions provide high availability across service failure domains. Therefore, regional pairs can be thought of as each other’s backup region. This means that an Azure resource that is placed in one region is automatically gaining fault tolerance through the paired region. For this reason, choosing regions for two vaults used in a DEP where the regions are paired means that only a total of two regions of availability are in use. Most geographies only have two regions, so it's not yet possible to select non-paired regions. If possible, choose two non-paired regions for the two vaults used with a DEP. This benefits from a total of four regions of availability. For more information, see Business continuity and disaster recovery (BCDR): Azure Paired Regions for a current list of regional pairs.

Assign permissions to each key vault

For each key vault, you will need to define three separate sets of permissions for Customer Key, depending on your implementation. For example, you will need to define one set of permissions for each of the following:

  • Key vault administrators that will perform day-to-day management of your key vault for your organization. These tasks include backup, create, get, import, list, and restore.

    Note: The set of permissions assigned to key vault administrators does not include the permission to delete keys. This is intentional and an important practice. Deleting encryption keys is not typically done, since doing so permanently destroys data. As a best practice, do not grant this permission to key vault administrators by default. Instead, reserve this for key vault contributors and only assign it to an administrator on a short term basis once a clear understanding of the consequences is understood.

    To assign these permissions to a user in your Office 365 organization, log in to your Azure subscription with Azure PowerShell. For instructions, see Log in with Azure PowerShell.

  • Run the Set-AzureRmKeyVaultAccessPolicy cmdlet to assign the necessary permissions.

    Set-AzureRmKeyVaultAccessPolicy -VaultName <vaultname> 
    -UserPrincipalName <UPN of user> -PermissionsToKeys create,import,list,get,backup,restore
    

    For example:

    Set-AzureRmKeyVaultAccessPolicy -VaultName Contoso-O365EX-NA-VaultA1 
    -UserPrincipalName alice@contoso.com -PermissionsToKeys create,import,list,get,backup,restore
    
  • Key vault contributors that can change permissions on the Azure Key Vault itself. You'll need to change these permissions as employees leave or join your team, or in the extremely rare situation that the key vault administrators legitimately need permission to delete or restore a key. This set of key vault contributors needs to be granted the Contributor role on your key vault. You can assign this role by using Azure Resource Manager. For detailed steps, see Use Role-Based Access Control to manage access to your Azure subscription resources. The administrator who creates a subscription has this access implicitly, as well as the ability to assign other administrators to the Contributor role.

  • If you intend to use Customer Key with Exchange Online and Skype for Business, you need to give permission to Office 365 to use the key vault on behalf of Exchange Online and Skype for Business. Likewise, if you intend to use Customer Key with SharePoint Online and OneDrive for Business, you need to add permission for the Office 365 to use the key vault on behalf of SharePoint Online and OneDrive for Business. To give permission to Office 365, run the Set-AzureRmKeyVaultAccessPolicy cmdlet using the following syntax:

    Set-AzureRmKeyVaultAccessPolicy –VaultName <vaultname> -PermissionsToKeys wrapKey,unwrapKey,get -ServicePrincipalName <Office 365 appID>

    Where:

    • vaultname is the name of the key vault you created.

    • For Exchange Online and Skype for Business, replace Office 365 appID with 00000002-0000-0ff1-ce00-000000000000

    • For SharePoint Online and OneDrive for Business, replace Office 365 appID with 00000003-0000-0ff1-ce00-000000000000

    Example: Setting permissions for Exchange Online and Skype for Business:

    Set-AzureRmKeyVaultAccessPolicy –VaultName Contoso-O365EX-NA-VaultA1 
    -PermissionsToKeys wrapKey,unwrapKey,get -ServicePrincipalName 00000002-0000-0ff1-ce00-000000000000

    Example: Setting permissions for SharePoint Online and OneDrive for Business

    Set-AzureRmKeyVaultAccessPolicy –VaultName Contoso-O365SP-NA-VaultA1 
    -PermissionsToKeys wrapKey,unwrapKey,get -ServicePrincipalName 00000003-0000-0ff1-ce00-000000000000

Enable and then confirm soft delete on your key vaults

When you can quickly recover your keys, you are less likely to experience an extended service outage due to accidentally or maliciously deleted keys. You need to enable this configuration, referred to as Soft Delete, before you can use your keys with Customer Key. Enabling Soft Delete allows you to recover keys or vaults within 90 days of deletion without having to restore them from backup.

To enable Soft Delete on your key vaults, complete these steps:

  1. Log in to your Azure subscription with Windows Powershell. For instructions, see Log in with Azure PowerShell.

  2. Run the Get-AzureRmKeyVault cmdlet as follows:

    $v = Get-AzureRmKeyVault -VaultName <vaultname>
    $r = Get-AzureRmResource -ResourceId $v.ResourceId
    $r.Properties | Add-Member -MemberType NoteProperty -Name enableSoftDelete -Value 'True'
    Set-AzureRmResource -ResourceId $r.ResourceId -Properties $r.Properties

    Where vaultname is the name of the key vault for which you are enabling soft delete.

  3. Confirm soft delete is configured for the key vault by running the Get-AzureRmKeyVault cmdlet:

    Get-AzureRmKeyVault -VaultName <vaultname> | fl

    If soft delete is configured properly for the key vault, then the Soft Delete Enabled? property returns a value of True.

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 Key Vault, or you can import a key. Creating a key directly in Key Vault is the less complicated method, while importing a key provides total control over how the key is generated.

To create a key directly in your key vault, run the Add-AzureKeyVaultKey cmdlet as follows:

Add-AzureKeyVaultKey -VaultName <vaultname> -Name <keyname> -Destination <HSM|Software> -KeyOps wrapKey,unwrapKey

Where:

  • vaultname is the name of the key vault in which you want to create the key.

  • keyname is the name you want to give the new key.

    Note: Name keys using a similar naming convention as described above for key vaults. This way, in tools that show only the key name, the string is self-describing.

  • If you intend to protect the key with an HSM, ensure that you specify HSM as the value of the Destination parameter, otherwise, specify Software.

For example,

Add-AzureKeyVaultKey -VaultName Contoso-O365EX-NA-VaultA1 -Name Contoso-O365EX-NA-VaultA1-Key001 -Destination Software -KeyOps wrapKey,unwrapKey

To import a key directly into your key vault, you need to have a Thales nShield Hardware Security Module.

Some organizations prefer this approach to establish the provenance of their keys, and the this method also provides the following:

  • The toolset used for import includes attestation from Thales that the Key Exchange Key (KEK) that is used to encrypt the key you generate is not exportable and is generated inside a genuine HSM that was manufactured by Thales.

  • The toolset includes attestation from Thales that the Azure Key Vault security world was also generated on a genuine HSM manufactured by Thales. This attestation proves to you that Microsoft is also using genuine Thales hardware.

Check with your security group to determine if the above attestations are required. For detailed steps to create a key on-premises and import it into your key vault, see How to generate and transfer HSM-protected keys for Azure Key Vault. Use the Azure instructions to create a key in each key vault.

Check the recovery level of your keys

Office 365 requires that the Azure Key Vault subscription is set to Do Not Cancel and that the keys used by Customer Key have soft delete enabled. You can confirm this by looking at the recovery level on your keys.

To check the recovery level of a key, in Azure PowerShell, run the Get-AzureKeyVaultKey cmdlet as follows:

(Get-AzureKeyVaultKey -VaultName <vaultname> -Name <keyname>).Attributes 

If the Recovery Level property returns anything other than a value of Recoverable+ProtectedSubscription, you will need to review this topic and ensure that you have followed all of the steps to put the subscription on the Do Not Cancel list and that you have soft delete enabled on each of your key vaults.

Backup Azure Key Vault

Immediately following creation or any change to a key, perform a backup and store copies of the backup, both online and offline. Offline copies should not be connected to any network, such as in a physical safe or commercial storage facility. At least one copy of the backup should be stored in a location that will be accessible in the event of a disaster. The backup blobs are the sole means of restoring key material should a Key Vault key be permanently destroyed or otherwise rendered inoperable. Keys that are external to Azure Key Vault and were imported to Azure Key Vault do not qualify as a backup because the metadata necessary for Customer Key to use the key does not exist with the external key. Only a backup taken from Azure Key Vault can be used for restore operations with Customer Key. Therefore, it is essential that a backup of Azure Key Vault be made once a key is uploaded or created.

To create a backup of an Azure Key Vault key, run the Backup-AzureKeyVaultKey cmdlet as follows:

Backup-AzureKeyVaultKey -VaultName <vaultname> -Name <keyname> 
-OutputFile <filename.backup>

Ensure that your output file uses the suffix .backup.

The output file resulting from this cmdlet is encrypted and cannot be used outside of Azure Key Vault. The backup can be restored only to the Azure subscription from which the backup was taken.

Note: For the output file, choose a combination of your vault name and key name. This will make the file name self-describing. It will also ensure that backup file names do not collide.

For example:

Backup-AzureKeyVaultKey -VaultName Contoso-O365EX-NA-VaultA1 -Name Contoso-O365EX-NA-VaultA1-Key001 -OutputFile Contoso-O365EX-NA-VaultA1-Key001-Backup-20170802.backup

Validate Azure Key Vault configuration settings

Performing validation before using keys in a DEP is optional, but highly recommended. In particular, if you use steps to set up your keys and vaults other than the ones described in this topic, you should validate the health of your Azure Key Vault resources before you configure Customer Key.

To verify that your keys have get, wrapKey, and unwrapKey operations enabled:

Run the Get-AzureRmKeyVault cmdlet as follows:

Get-AzureRMKeyVault -VaultName <vaultname>

In the output, look for the Access Policy and for the Exchange Online identity (GUID) or the SharePoint Online identity (GUID) as appropriate. All three of the above permissions must be shown under Permissions to Keys.

If the access policy configuration is incorrect, run the Set-AzureRmKeyVaultAccessPolicy cmdlet as follows:

Set-AzureRmKeyVaultAccessPolicy –VaultName <vaultname> -PermissionsToKeys wrapKey,unwrapKey,get -ServicePrincipalName <Office 365 appID>

For example, for Exchange Online and Skype for Business:

Set-AzureRmKeyVaultAccessPolicy –VaultName Contoso-O365EX-NA-VaultA1 
-PermissionsToKeys wrapKey,unwrapKey,get -ServicePrincipalName 00000002-0000-0ff1-ce00-000000000000

For example, for SharePoint Online and OneDrive for Business:

Set-AzureRmKeyVaultAccessPolicy –VaultName Contoso-O365SP-NA-VaultA1 
-PermissionsToKeys wrapKey,unwrapKey,get -ServicePrincipalName TBD

To verify that an expiration date is not set for your keys:

Run the Get-AzureKeyVaultKey cmdlet as follows:

Get-AzureKeyVaultKey -VaultName <vaultname> -KeyName <keyname> 

An expired key cannot be used by Customer Key and operations attempted with an expired key will fail, and possibly result in a service outage. We strongly recommend that keys used with Customer Key do not have an expiration date. An expiration date, once set, cannot be removed, but can be changed to a different date. If a key must be used that has an expiration date set, change the expiration value to 12/31/9999. Keys with an expiration date set to a date other than 12/31/9999 will not pass Office 365 validation.

To change an expiration date that has been set to any value other than 12/31/9999, run the Set-AzureKeyVaultKeyAttribute cmdlet as follows:

Set-AzureKeyVaultKeyAttribute –VaultName <vaultname> -Name <keyname> 
-Expires (Get-Date -Date “12/31/9999”)

Note: Don't set expiration dates on encryption keys you use with Customer Key.

Obtain the URI for each Azure Key Vault key

Once you have completed all the steps in Azure to set up your key vaults and added your keys, run the following command to get the URI for the key in each key vault. You will need to use these URIs when you create and assign each DEP later, so save this information in a safe place. Remember to run this command once for each key vault.

In Azure PowerShell:

(Get-AzureKeyVaultKey -VaultName <vaultname>).Id

Office 365: Setting up Customer Key for Exchange Online and Skype for Business

Before you begin, ensure that you have completed the tasks required to set up Azure Key Vault. See Complete tasks in Azure Key Vault and Microsoft FastTrack for Customer Key for information.

To set up Customer Key for Exchange Online and Skype for Business, you will need to perform these steps by remotely connecting to Exchange Online with Windows PowerShell.

Create a data encryption policy (DEP) for use with Exchange Online and Skype for Business

A DEP is associated with a set of keys stored in Azure Key Vault. You assign a DEP to a mailbox in Office 365. Office 365 will then use the keys identified in the policy to encrypt the mailbox. To create the DEP, you need the Key Vault URIs you obtained earlier. See Obtain the URI for an Azure Key Vault key for instructions.

Remember! When you create a DEP, you specify two keys that reside in two different Azure Key Vaults. Ensure that these keys are located in two separate Azure regions to ensure geo-redundancy.

To create the DEP, follow these steps:

  1. On your local computer, using a work or school account that has global administrator permissions in your Office 365 organization, connect to Exchange Online PowerShell by opening Windows PowerShell and running the following command.

    $UserCredential = Get-Credential
  2. In the Windows PowerShell Credential Request dialog box, enter your work or school account information, and then click OK and then enter the following command.

    $Session = New-PSSession -ConfigurationName Microsoft.Exchange -ConnectionUri https://outlook.office365.com/powershell-liveid/ -Credential $UserCredential -Authentication Basic -AllowRedirection
  3. Run the following command.

    Import-PSSession $Session
  4. To create a DEP, use the New-DataEncryptionPolicy cmdlet by typing the following command.

    New-DataEncryptionPolicy -Name <PolicyName> -Description "PolicyDescription" -AzureKeyIDs <KeyVaultURI1>, <KeyVaultURI2>

    Where:

    • PolicyName is the name you want to use for the policy. Names cannot contain spaces. For example, USA_mailboxes.

    • PolicyDescription is a user friendly description of the policy that will help you remember what the policy is for. You can include spaces in the description. For example, Root key for mailboxes in USA and its territories.

    • KeyVaultURI1 is the URI for the first key in the policy. For example, https://contoso_EastUSvault01.vault.azure.net/keys/USA_key_01.

      KeyVaultURI2 is the URI for the second key in the policy. For example, https://contoso_EastUS2vault01.vault.azure.net/keys/USA_Key_02. Separate the two URIs by a comma and a space.

Example:

New-DataEncryptionPolicy -Name USA_mailboxes -Description "Root key for mailboxes in USA and its territories" -AzureKeyIDs https://contoso_EastUSvault01.vault.azure.net/keys/USA_key_01, https://contoso_EastUS2vault01.vault.azure.net/keys/USA_Key_02

Assign a DEP to a mailbox

Assign the DEP to a mailbox by using the Set-Mailbox cmdlet. Once you assign the policy, Office 365 can encrypt the mailbox with the key designated in the DEP.

Set-Mailbox -Identity <MailboxIdParameter> -DataEncryptionPolicy <PolicyName>

Where MailboxIdParameter specifies a mailbox. For more information about the Set-Mailbox cmdlet, see Set-Mailbox.

Validate mailbox encryption

Encrypting a mailbox can take some time. For first time policy assignment, the mailbox must also complete the move from one database to another before the service can encrypt the mailbox. We recommend that you wait 72 hours before you attempt to validate encryption after you change a DEP or the first time you assign a DEP to a mailbox.

Use the Get-MailboxStatistics cmdlet to determine if a mailbox is encrypted.

Get-MailboxStatistics -Identity <GeneralMailboxOrMailUserIdParameter> | fl IsEncrypted

The IsEncrypted property returns a value of true if the mailbox is encrypted and a value of false if the mailbox is not encrypted.

Office 365: Setting up Customer Key for SharePoint Online and OneDrive for Business

Before you begin, ensure that you have completed the tasks required to set up Azure Key Vault. See Complete tasks in Azure Key Vault and Microsoft FastTrack for Customer Key for information.

To set up Customer Key for SharePoint Online and OneDrive for Business, you will need to perform these steps by remotely connecting to SharePoint Online with Windows PowerShell.

Create a data encryption policy (DEP) for each SharePoint Online and OneDrive for Business geo

A DEP is associated with a set of keys stored in Azure Key Vault. You apply a DEP to all of your data in one geographic location, also called a geo. If you use the multi-geo feature of Office 365 (currently in Preview), you can create one DEP per geo. If you are not using multi-geo, you can create one DEP in Office 365 for use with SharePoint Online and OneDrive for Business. Office 365 will then use the keys identified in the DEP to encrypt your data in that geo. To create the DEP, you need the Key Vault URIs you obtained earlier. See Obtain the URI for an Azure Key Vault key for instructions.

Remember! When you create a DEP, you specify two keys that reside in two different Azure Key Vaults. Ensure that these keys are located in two separate Azure regions to ensure geo-redundancy.

To create a DEP, you need to remotely connect to SharePoint Online by using Windows PowerShell.

  1. On your local computer, using a work or school account that has global administrator permissions in your Office 365 organization, Connect to SharePoint Online Powershell.

  2. In the Microsoft SharePoint Online Management Shell, run the Register-SPODataEncryptionPolicy cmdlet as follows:

    Register-SPODataEncryptionPolicy -Identity <SPOAdminSiteUrl> -PrimaryKeyVaultName <PrimaryKeyVaultName> -PrimaryKeyName <PrimaryKeyName> -PrimaryKeyVersion <PrimaryKeyVersion> -SecondaryKeyVaultName <SecondaryKeyVaultName> -SecondaryKeyName <SecondaryKeyName> -SecondaryKeyVersion <SecondaryKeyVersion>

    When you register the DEP, encryption begins on the data in the geo. This can take some time.

Validate encryption of Group Sites, Team Sites, and OneDrive for Business

You can check on the status of encryption by running the Get-SPODataEncryptionPolicy cmdlet as follows:

Get-SPODataEncryptionPolicy -Identity <SPOAdminSiteUrl>

The output from this cmdlet includes:

  • The URI of the primary key.

  • The URI of the secondary key.

  • The encryption status for the geo. Possible states include:

    • Unregistered: Customer Key encryption has not yet been applied.

    • Registering: Customer Key encryption has been applied and your files are in the process of being encrypted. If your geo is in this state, you'll also be shown information on what percentage of sites in the geo are complete so that you can monitor encryption progress.

    • Registered: Customer Key encryption has been applied, and all files in all sites have been encrypted.

    • Rolling: A key roll is in progress. If your geo is in this state, you'll also be shown information on what percentage of sites have completed the key roll operation so that you can monitor progress.

Managing Customer Key for Office 365

After you've set up Customer Key for Office 365, you can perform these additional management tasks.

Restore Azure Key Vault keys

Before performing a restore, use the recovery capabilities provided by soft delete. All keys that are used with Customer Key are required to have soft delete enabled. Soft delete acts like a recycle bin and allows recovery for up to 90 days without the need to restore. Restore should only be required in extreme or unusual circumstances, for example if the key or key vault is lost. If you must restore a key for use with Customer Key, in Azure PowerShell, run the Restore-AzureKeyVaultKey cmdlet as follows:

Restore-AzureKeyVaultKey -VaultName <vaultname> -InputFile <filename>

For example:

Restore-AzureKeyVaultKey -VaultName Contoso-O365EX-NA-VaultA1 -InputFile Contoso-O365EX-NA-VaultA1-Key001-Backup-20170802.backup

If a key with the same name already exists in the key vault, the restore operation will fail. Restore-AzureKeyVaultKey restores all key versions and all metadata for the key including the key name.

Rolling or rotating a key in Azure Key Vault that you use with Customer Key

Rolling keys is not required by either Azure Key Vault or by Customer Key. In addition, keys that are protected with an HSM are virtually impossible to compromise. Even if a root key were in the possession of a malicious actor there is no feasible means of using it to decrypt data, since only Office 365 code knows how to use it. However, rolling a key is supported by Customer Key.

Notes: 

  • Only roll an encryption key that you use with Customer Key when a clear technical reason exists or a compliance requirement dictates that you have to roll the key. In addition, do not delete any keys that are or were associated with policies. When you roll your keys, there will be content encrypted with the previous keys. For example, while active mailboxes will be re-encrypted frequently, inactive, disconnected, and disabled mailboxes may still be encrypted with the previous keys. SharePoint Online performs backup of content for restore and recovery purposes, so there may still be archived content using older keys.

  • To ensure the safety of your data, SharePoint Online will allow no more than one Key Roll operation to be in progress at a time. If you want to roll both of the keys in a key vault, you’ll need to wait for the first key roll operation to fully complete. Our recommendation is to stagger your key roll operations at different intervals, so that this is not an issue.

When you roll a key, you are requesting a new version of an existing key. In order to request a new version of an existing key, you use the same cmdlet, Add-AzureKeyVaultKey, with the same syntax that you used to create the key in the first place.

For example:

Add-AzureKeyVaultKey -VaultName Contoso-O365EX-NA-VaultA1 -Name Contoso-O365EX-NA-VaultA1-Key001 -Destination HSM -KeyOps @(‘wrapKey’,’unwrapKey’) -NotBefore (Get-Date -Date “12/27/2016 12:01 AM”)

In this example, since a key named Contoso-O365EX-NA-VaultA1-Key001 already exists in the Contoso-O365EX-NA-VaultA1 vault, a new key version will be created. The operation adds a new key version. This operation preserves the previous key versions in the key’s version history, so that data previously encrypted with that key can still be decrypted. Once you have completed rolling any key that is associated with a DEP, you must then run an additional cmdlet to ensure Customer Key begins using the new key.

Enable Exchange Online and Skype for Business to use a new key after you roll or rotate keys in Azure Key Vault

When you roll either of the Azure Key Vault keys associated with a DEP used with Exchange Online and Skype for Business, you must run the following command to update the DEP and enable Office 365 to start using the new key.

To instruct Customer Key to use the new key to encrypt mailboxes in Office 365 run the Set-DataEncryptionPolicy cmdlet as follows:

Set-DataEncryptionPolicy <policyname> -Refresh 

Within 48 hours, the active mailboxes encrypted using this policy will become associated with the updated key. Use the steps in Determine the DEP assigned to a mailbox to check the value for the DataEncryptionPolicyID property for the mailbox. The value for this property will change once the updated key has been applied.

Enable SharePoint Online and OneDrive for Business to use a new key after you roll or rotate keys in Azure Key Vault

When you roll either of the Azure Key Vault keys associated with a DEP used with SharePoint Online and OneDrive for Business, you must run the Update-SPODataEncryptionPolicy cmdlet to update the DEP and enable Office 365 to start using the new key.

Update-SPODataEncryptionPolicy -Identity <SPOAdminSiteUrl> -KeyVaultName <ReplacementKeyVaultName> -KeyName <ReplacementKeyName> -KeyVersion <ReplacementKeyVersion> -KeyType <Primary | Secondary>

This will start the key roll operation for SharePoint Online and OneDrive for Business. This action is not immediate. To see the progress of the key roll operation, run the Get-SPODataEncryptionPolicy cmdlet as follows:

Get-SPODataEncryptionPolicy -Identity <SPOAdminSiteUrl>

Manage key vault permissions

Several cmdlets are available that enable you to view and, if necessary, remove key vault permissions. You might need to remove permissions, for example, when an employee leaves the team.

To view key vault permissions, run the Get-AzureRmKeyVault cmdlet:

Get-AzureRmKeyVault -VaultName <vaultname>

For example:

Get-AzureRmKeyVault -VaultName Contoso-O365EX-NA-VaultA1

To remove an administrator's permissions, run the Remove-AzureRmKeyVaultAccessPolicy cmdlet:

Remove-AzureRmKeyVaultAccessPolicy -VaultName <vaultname> 
-UserPrincipalName <UPN of user>

For example:

Remove-AzureRmKeyVaultAccessPolicy -VaultName Contoso-O365EX-NA-VaultA1 
-UserPrincipalName alice@contoso.com

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

Get-MailboxStatistics -Identity <GeneralMailboxOrMailUserIdParameter> | fl DataEncryptionPolicyID

Where GeneralMailboxOrMailUserIdParameter specifies a mailbox. For more information about the Get-MailboxStatistics cmdlet, see Get-MailboxStatistics.

Use the GUID to find out the friendly name of the DEP to which the mailbox is assigned by running the following cmdlet.

Get-DataEncryptionPolicy <GUID>

Where GUID is the GUID returned by the Get-MailboxStatistics cmdlet in the previous step.

Connect with an expert
Contact us
Expand your skills
Explore training

Was this information helpful?

Thank you for your feedback!

Thank you for your feedback! It sounds like it might be helpful to connect you to one of our Office support agents.

×