📣
TiDB Cloud Serverless is now
TiDB Cloud Starter
! Same experience, new name.
Try it out →
TiDB Cloud
TiDB Self-Managed
Learning Center
Contact Us
​
Sign InStart for Free

Encryption at Rest Using Customer-Managed Encryption Keys on Azure

Customer-Managed Encryption Key (CMEK) enables you to secure your static data in a TiDB Cloud Dedicated cluster by utilizing a symmetric encryption key that is under your complete control. This key is referred to as the CMEK key.

Once CMEK is enabled for a project, all clusters created within that project encrypt their static data using the CMEK key. Additionally, any backup data generated by these clusters is encrypted using the same key. If CMEK is not enabled, TiDB Cloud employs an escrow key to encrypt all data in your cluster when it is at rest.

Restrictions

  • Currently, TiDB Cloud only supports using AWS KMS and Azure Key Vault to provide CMEK.
  • To use CMEK, you need to enable CMEK when creating a project and complete CMEK-related configurations before creating a cluster. You cannot enable CMEK for existing projects.
  • Currently, in CMEK-enabled projects, you can only create TiDB Cloud Dedicated clusters hosted on AWS and Azure.
  • Currently, in CMEK-enabled projects, dual region backup is not supported.
  • Currently, in CMEK-enabled projects, you can enable CMEK on AWS and Azure. For each cloud provider, you can configure one unique encryption key per region. You can only create clusters in regions where you have configured an encryption key for the chosen cloud provider.

Enable CMEK

If you want to encrypt your data using the encryption keys owned by your account, take the following steps.

Step 1. Create a CMEK-enabled project

If you are in the Organization Owner role of your organization, you can create a CMEK-enabled project by performing the following steps:

  1. In the TiDB Cloud console, switch to your target organization using the combo box in the upper-left corner.
  2. In the left navigation pane, click Projects.
  3. On the Projects page, click Create New Project in the upper-right corner.
  4. Fill in a project name.
  5. Choose to enable the CMEK capability of the project.
  6. Click Confirm to complete the project creation.

Step 2. Complete the CMEK configuration of the project

You can complete the CMEK configuration for a project by using the TiDB Cloud console with either the Azure portal or Azure Resource Manager.

    To configure CMEK using the TiDB Cloud console and Azure portal, take the following steps:

    1. In the TiDB Cloud console, switch to your target project using the combo box in the upper-left corner.

    2. In the left navigation pane, click Project Settings > Encryption Access.

    3. On the Encryption Access page, click Create Encryption Key.

    4. Under Key Management Service, select Azure Key Vault, and choose the region where the encryption key will be used.

    5. If a Service Principal for the TiDB-provided enterprise application does not already exist in your tenant, create one. The TiDB Cloud console displays the Microsoft Entra Application Name and ID, which you need for this process and later steps. To create the Service Principal, run the following command from the Create Service Principal section:

      az ad sp create --id {Microsoft_Entra_Application_ID}

      For more information, see Application and service principal objects in Microsoft Entra ID.

    6. Create a Key Vault in your Azure account, or select an existing one. Ensure that:

      • Purge protection is enabled.
      • The region matches your cluster's region.

    7. In the TiDB Cloud console, enter the Key Vault name and Key name. TiDB Cloud adds a unique suffix to the key name for enhanced security. Copy the full key name and create the encryption key in the Azure portal. For more information, see Create your encryption key.

    8. Assign the Key Vault Crypto Officer role to your current user:

      1. In the Azure portal, navigate to your Key Vault.
      2. Click Access control (IAM), and then click Add > Add role assignment.
      3. Search for and select the Key Vault Crypto Officer role, then click Next.
      4. On the Members tab, set Assign access to as User, group, or service principal.
      5. Click + Select members, search for and select your current user as the member. Then, click Select.
      6. Review the settings and click Review + assign.

    9. Assign the Key Vault Crypto Service Encryption User role to the TiDB-provided enterprise application for the encryption key:

      1. In your Key Vault, go to the encryption key object you created.
      2. Click Add > Add role assignment.
      3. Search for and select the Key Vault Crypto Service Encryption User role, then click Next.
      4. On the Members tab, set Assign access to as User, group, or service principal.
      5. Click + Select members, enter the TiDB-provided Enterprise Application Name, and select it as the member. Then, click Select.
      6. Review the configuration and click Review + assign.

    10. In the TiDB Cloud console, click Test Encryption Key and Create to validate the configuration and create the encryption key.

    To configure CMEK using the TiDB Cloud console and Azure Resource Manager, take the following steps:

    1. In the TiDB Cloud console, use the combo box in the upper-left corner to switch to your target project.

    2. In the left navigation pane, go to Project Settings > Encryption Access.

    3. On the Encryption Access page, click Create Encryption Key.

    4. Under Key Management Service, select Azure Key Vault, and specify the region where the encryption key will be available.

    5. If a Service Principal for the TiDB-provided enterprise application does not already exist in your tenant, create one. To create the Service Principal, run the following command from the Create Service Principal section:

      az ad sp create --id {Microsoft_Entra_Application_ID}

      For more information, see Application and service principal objects in Microsoft Entra ID.

    6. Open the TiDB custom deployment template for Azure Resource Manager in the Azure portal. Select your Subscription and Resource Group, then fill in the Instance Details section as follows:

      • Region: select the location where you want to create the Key Vault. This must match your cluster's region.
      • Key Vault Name: enter the name of your Azure Key Vault.
      • Key Name: provide the full key name to be created in the Key Vault. In the TiDB Cloud console, enter the key name prefix and click Copy to get the full key name.
      • Enterprise App Service Principal ID: enter the Service Principal ID for the TiDB-provided enterprise application. To retrieve the Service Principal ID, run the following command (replace {microsoft_enterprise_app_id} with the actual ID shown in the TiDB Cloud console):
      az ad sp show --id {microsoft_enterprise_app_id} --query id -o tsv

    Step 3. Create a cluster

    Under the project created in Step 1, create a TiDB Cloud Dedicated cluster hosted on Azure. For detailed steps, refer to Create a TiDB Cloud Dedicated Cluster.

    When you select a cloud provider and region, the appropriate encryption key is automatically matched. If no key is available for your provider and region, the console displays a tip to help you create one.

    Rotate CMEK

    You can configure cryptographic key auto-rotation in Azure Key Vault. With this rotation enabled, you do not need to update Encryption Access in project settings in TiDB Cloud.

    Disable and re-enable CMEK

    If you need to temporarily revoke TiDB Cloud's access to CMEK, follow these steps:

    1. In the TiDB Cloud console, pause the corresponding cluster in the project.
    2. In the Azure Key Vault console, right-click the encryption key and select Disable.

    After disabling TiDB Cloud's access to CMEK, if you need to restore the access, follow these steps:

    1. In the Azure Key Vault console, select the encryption key and click Enable.
    2. In the TiDB Cloud console, restore the corresponding cluster in the project.

    Was this page helpful?

    Request docs changesAsk the community