Edit

Share via

Manage the encryption key

  • Article

All environments of Microsoft Dataverse use SQL Server Transparent Data Encryption (TDE) to perform real-time encryption of data when written to disk, also known as encryption at rest.

By default, Microsoft stores and manages the database encryption key for your environments so you don't have to. The manage keys feature in the Microsoft Power Platform admin center gives administrators the ability to self-manage the database encryption key that is associated with the Dataverse tenant.

Important

  • As of June 2, 2023, this service is upgraded to Customer-managed encryption key. New customers who need to manage their own encryption key will use the upgraded service as this service is no longer offered.
  • Self-managed database encryption keys are only available for customers who have more than 1000 Power Apps per user licenses, or more than 1000 Dynamics 365 Enterprise licenses, or more than 1000 licenses from a combination of both in a single tenant. To opt in to this program, submit a support request.

Encryption key management is only applicable to Azure SQL environment databases. The following features and services continue to use the Microsoft-managed encryption key to encrypt their data and can't be encrypted with the self-managed encryption key:

Note

  • The self-manage database encryption key feature must be turned on by Microsoft for your tenant before you can use the feature.
  • To use the data encryption management features for an environment, the environment must be created after the self-manage the database encryption key feature is turned on by Microsoft.
  • After the feature is turned on in your tenant, all new environments are created with Azure SQL storage only. These environments, regardless of whether they're encrypted with bring-your-own-key (BYOK) or a Microsoft-managed key, have restrictions with file upload size, can't use Cosmos and Datalake services, and Dataverse Search indexes are encrypted with a Microsoft-managed key. To use these services, you must migrate to customer-managed key.
  • Files and Images with sizes less than 128 MB can be used if your environment is version 9.2.21052.00103 or higher.
  • A majority of existing environments have file and log stored in non-Azure SQL databases. These environments cannot be opted in to self-managed encryption key. Only new environments (once you signed up for this program) can be enabled with self-managed encryption key.

Introduction to key management

With key management, administrators can provide their own encryption key or have an encryption key generated for them, which is used to protect the database for an environment.

The key management feature supports both PFX and BYOK encryption key files, such as those stored in a hardware security module (HSM). To use the upload encryption key option you need both the public and private encryption key.

The key management feature takes the complexity out of encryption key management by using Azure Key Vault to securely store encryption keys. Azure Key Vault helps safeguard cryptographic keys and secrets used by cloud applications and services. The key management feature doesn't require that you have an Azure Key Vault subscription and for most situations there is no need to access encryption keys used for Dataverse within the vault.

The manage keys feature lets you perform the following tasks.

  • Enable the ability to self-manage database encryption keys that are associated with environments.

  • Generate new encryption keys or upload existing .PFX or .BYOK encryption key files.

  • Lock and unlock tenant environments.

    Warning

    While a tenant is locked, all environments within the tenant can't be accessed by anyone. More information: Lock the tenant.

Understand the potential risk when you manage your keys

As with any business critical application, personnel within your organization who have administrative-level access must be trusted. Before you use the key management feature, you should understand the risk when you manage your database encryption keys. It is conceivable that a malicious administrator (a person who is granted or has gained administrator-level access with intent to harm an organization's security or business processes) working within your organization might use the manage keys feature to create a key and use it to lock all environments in the tenant.

Consider the following sequence of events.

The malicious administrator signs in to the Power Platform admin center, goes to the Environments tab and selects Manage encryption key. The malicious administrator then creates a new key with a password and downloads the encryption key to their local drive, and activates the new key. Now all the environment databases are encrypted with the new key. Next, the malicious administrator locks the tenant with the newly downloaded key, and then takes or deletes the downloaded encryption key.

These actions will result in disabling all the environments within the tenant from online access and make all database backups un-restorable.

Important

To prevent the malicious administrator from interrupting the business operations by locking the database, the managed keys feature doesn't allow tenant environments to be locked for 72 hours after the encryption key has changed or activated. This provides up to 72 hours for other administrators to roll back any unauthorized key changes.

Encryption key requirements

If you provide your own encryption key, your key must meet these requirements that are accepted by Azure Key Vault.

  • The encryption key file format must be PFX or BYOK.
  • 2048-bit RSA.
  • RSA-HSM key type (requires a Microsoft Support request).
  • PFX encryption key files must be password protected.

For more information about generating and transferring an HSM-protected key over the Internet see How to generate and transfer HSM-protected keys for Azure Key Vault. Only nCipher Vendor HSM key is supported. Before generating your HSM key, go to the Power Platform admin center Manage encryption keys/Create New key window to obtain the subscription ID for your environment region. You need to copy and paste this subscription ID into your HSM to create the key. This will ensure that only our Azure Key Vault can open your file.

Key management tasks

To simplify the key management tasks, the tasks are broken down into three areas:

  1. Generate or upload the encryption key for a tenant
  2. Activate an encryption key for a tenant
  3. Manage encryption for an environment

Administrators can use the Power Platform admin center or the Power Platform administration module cmdlets to perform the tenant protection key management tasks described here.

Generate or upload the encryption key for a tenant

All encryption keys are stored in the Azure Key Vault, and there can only be one active key at any time. Since the active key is used to encrypt all the environments in the tenant, managing the encryption is operated at the tenant level. Once the key is activated, each individual environment can then be selected to use the key for encryption.

Use this procedure to set the manage key feature the first time for an environment or to change (or roll-over) an encryption key for an already self-managed tenant.

Warning

When you perform the steps described here for the first time you are opting in to self-managing your encryption keys. More information: Understand the potential risk when you manage your keys.

  1. Sign in to the Power Platform admin center, as an admin (Dynamics 365 admin or Microsoft Power Platform admin).

  2. Select the Environments tab, and then select Manage encryption keys on the toolbar.

  3. Select Confirm to acknowledge the manage key risk.

  4. Select New key on the toolbar.

  5. On the left pane, complete the details to generate or upload a key:

    • Select a Region. This option is only shown if your tenant has multiple regions.
    • Enter a Key name.
    • Choose from the following options:

  6. Select Next.

Generate a new key (.pfx)

  1. Enter a password, and then re-enter the password to confirm.
  2. Select Create, and then select the created file notification on your browser.
  3. The encryption key .PFX file is downloaded to your web browser's default download folder. Save the file in a secure location (we recommend that this key is backed up along with its password).

Upload a key (.pfx or .byok)

  1. Select Upload the Key, select the .pfx or .byok1 file, and then select Open.
  2. Enter the password for the key, and then select Create.

1 For .byok encryption key files, make sure you use the subscription ID as shown on the screen when you export the encryption key from your local HSM. More information: How to generate and transfer HSM-protected keys for Azure Key Vault.

Note

To reduce the number of steps for the administrator to manage the key process, the key is automatically activated when it is uploaded the first time. All subsequent key uploads require an additional step to activate the key.

Activate an encryption key for a tenant

Once an encryption key is generated or uploaded for the tenant, it can be activated.

  1. Sign in to the Power Platform admin center, as an admin (Dynamics 365 admin or Microsoft Power Platform admin).
  2. Select the Environments tab, and then select Manage encryption keys on the toolbar.
  3. Select Confirm to acknowledge the manage key risk.
  4. Select a key that has an Available state and then select Activate key on the toolbar.
  5. Select Confirm to acknowledge the key change.

When you activate a key for the tenant, it takes a while for the key management service to activate the key. The status of the Key state displays the key as Installing when the new or uploaded key is activated. Once the key is activated, the following occurs:

  • All encrypted environments automatically get encrypted with the active key (there is no downtime with this action).
  • When activated, the encryption key will be applied to all environments that are changed from Microsoft-provided to self-managed encryption key.

Important

To streamline the key management process so that all environments are managed by the same key, the active key can't be updated when there are locked environments. All locked environments must be unlocked before a new key can be activated. If there are locked environments that don't need to be unlocked, they must be deleted.

Note

After an encryption key is activated, you can't activate another key for 24 hours.

Manage encryption for an environment

By default, each environment is encrypted with the Microsoft-provided encryption key. Once an encryption key is activated for the tenant, administrators can elect to change the default encryption to use the activated encryption key. To use the activated key, follow these steps.

Apply encryption key to an environment

  1. Sign in to the Power Platform admin center, using Environment Admin or System Administrator role credentials.
  2. Select the Environments tab.
  3. Open a Microsoft-provided encrypted environment.
  4. Select See all.
  5. In the Environment Encryption section, select Manage.
  6. Select Confirm to acknowledge the manage key risk.
  7. Select Apply this key to accept changing the encryption to use the activated key.
  8. Select Confirm to acknowledge that you are managing the key directly and that there is downtime for this action.

Return a managed encryption key back to Microsoft-provided encryption key

Returning to the Microsoft-provided encryption key configures the environment back to the default behavior where Microsoft manages the encryption key for you.

  1. Sign in to the Power Platform admin center, using Environment Admin or System Administrator role credentials.
  2. Select the Environments tab, and then select an environment that is encrypted with a self-managed key.
  3. Select See all.
  4. In the Environment Encryption section, select Manage, and then select Confirm.
  5. Under Return to standard encryption management, select Return .
  6. For production environments, confirm the environment by entering the environment's name.
  7. Select Confirm to return to standard encryption key management.

Lock the tenant

Since there is only one active key per tenant, locking the encryption for the tenant disables all the environments that are in the tenant. All locked environments remain inaccessible to everyone, including Microsoft, until a Power Platform admin in your organization unlocks it by using the key that was used to lock it.

Caution

You should never lock the tenant environments as part of your normal business process. When you lock a Dataverse tenant, all the environments will be taken completely offline and they can't be accessed by anyone, including Microsoft. Additionally, services such as synchronization and maintenance are all stopped. If you decide to leave the service, locking the tenant can ensure that your online data is never accessed again by anyone.
Note the following about tenant environments locking:

  • Locked environments can't be restored from backup.
  • Locked environments are deleted if not unlocked after 28 days.
  • You can't lock environments for 72 hours after an encryption key change.
  • Locking a tenant locks all active environments within the tenant.

Important

  • You must wait at least one hour after you lock active environments before you can unlock them.
  • Once the lock process begins, all encryption keys with either an Active or Available state are deleted. The lock process can take up to an hour and during this time unlocking locked environments is not allowed.
  1. Sign in to the Power Platform admin center, as an admin (Dynamics 365 admin or Microsoft Power Platform admin).
  2. Select the Environments tab and then on the command bar select Manage encryption keys.
  3. Select the Active key and then select Lock active environments.
  4. On the right pane select Upload active key, browse to and select the key, enter the password, and then select Lock.
  5. When prompted, enter the text that is displayed on your screen to confirm that you want to lock all environments in the region, and then select Confirm.

Unlock locked environments

To unlock environments you must first upload and then activate the tenant encryption key with the same key that was used to lock the tenant. Please note that locked environments do not get unlocked automatically once the key has been activated. Each locked environment has to be unlocked individually.

Important

  • You must wait at least one hour after you lock active environments before you can unlock them.
  • The unlock process can take up to an hour. Once the key is unlocked, you can use the key to Manage encryption for an environment.
  • You can't generate a new or upload an existing key until all locked environments are unlocked.
Unlock encryption key
  1. Sign in to the Power Platform admin center, as an admin (Dynamics 365 admin or Microsoft Power Platform admin).
  2. Select the Environments tab and then select Manage encryption keys.
  3. Select the key that has a Locked state, and then on the command bar select Unlock key.
  4. Select Upload locked key, browse to and select the key that was used to lock the tenant, enter the password, and then select Unlock. The key goes into an Installing state. You must wait until the key is in an Active state before you can unlock locked environments.
  5. To unlock an environment, see the next section.
Unlock environments

  1. Select the Environments tab, and then select the locked environment name.

    Tip

    Don't select the row. Select the environment name. Open environment to view settings.

  2. In the Details section, select See all to display the Details pane on the right.

  3. In the Environment encryption section on the Details pane select Manage.

    Environment-details-pane.

  4. On the Environment encryption page select Unlock.

    Unlock environment.

  5. Select Confirm to confirm that you want to unlock the environment.

  6. Repeat the previous steps to unlock additional environments.

Environment database operations

A customer tenant can have environments that are encrypted using the Microsoft managed key and environments that are encrypted with the customer managed key. To maintain data integrity and data protection, the following controls are available when managing environment database operations.

  1. Restore The environment to overwrite (the restored to environment) is restricted to the same environment that the backup was taken from or to another environment that is encrypted with the same customer managed key.

    Restore backup.

  2. Copy The environment to overwrite (the copied to environment) is restricted to another environment that is encrypted with the same customer managed key.

    Copy environment.

    Note

    If a Support Investigation environment was created to resolve support issue in a customer managed environment, the encryption key for the Support Investigation environment must be changed to customer managed key before the Copy environment operation can be performed.

  3. Reset The environment's encrypted data will be deleted including backups. After the environment is reset, the environment encryption will revert back to the Microsoft managed key.

See also

SQL Server: Transparent Data Encryption (TDE)