Docs Menu

Docs Home → Launch & Manage MongoDB → MongoDB Atlas

Manage Customer Keys with Azure Key Vault

On this page

  • Enable Customer-Managed Keys with Azure Key Vault
  • Example
  • Required Access
  • Prerequisites
  • Enable Customer-Managed Keys for a Project
  • Enable Customer Key Management for an Atlas Cluster
  • Disable Customer-Managed Keys for a Project
  • Revoke Access to an Encryption Key
  • Alerts
  • Rotate your Azure Key Identifier
  • MongoDB Master Key - MongoDB Responsibility
  • Rotate your Azure Key ID - Your Responsibility
  • Prerequisites
  • Procedure
  • Alerts
  • Azure Key Vault Failover During an Outage
  • Related Topics

Note

  • This feature is not available for M0 free clusters, M2, and M5 clusters. To learn more, see Atlas M0 (Free Cluster), M2, and M5 Limits.

  • This feature is not supported on Serverless instances at this time. To learn more, see Serverless Instance Limitations.

You can use a customer-managed key (CMK) from Azure Key Vault (AKV) to further encrypt your data at rest in Atlas.

Atlas uses your Azure Key Vault CMK to encrypt and decrypt your MongoDB Master Keys. These MongoDB Master Keys are used to encrypt cluster database files and cloud providers snapshots. To learn more about how Atlas uses CMKs for encryption, see Enable Customer-Managed Keys with Azure Key Vault.

When you use your own cloud provider KMS, Atlas automatically rotates MongoDB Master Keys every 90 days. These keys are rotated on a rolling basis and the process does not require the data to be rewritten.

This page covers configuring customer key management using AKV on your Atlas project.

You must configure customer key management for the Atlas project before enabling it on clusters in that project.

Enable Customer-Managed Keys with Azure Key Vault

Customer key management in Atlas follows a process called envelope encryption. This process creates multiple layers of encryption by encrypting one key with another key. To enable customer key management, Atlas uses the following encryption keys:

Customer-Managed Key (CMK)

Customer-managed keys are encryption keys that you create, own, and manage in Azure Key Vault. You create the CMK in Azure Key Vault and connect it to Atlas at the Project level. To learn more about the CMKs used in Azure Key Vault, see the Azure Documentation.

Atlas uses this key only to encrypt the MongoDB Master Keys.

MongoDB Master Key

Each node in your Atlas cluster creates a MongoDB Master Key. MongoDB Master Keys are encryption keys that a MongoDB Server uses to encrypt files via the WiredTiger storage engine. Atlas saves an encrypted copy of the key locally.

This key is encrypted with the CMK and encrypts the per-database encryption keys.

Per-Database Encryption Key

Each node in your Atlas cluster also creates an encryption key per database in your cluster. Atlas uses these keys to read and write data via WiredTiger, which also encrypts and stores these keys.

This key is encrypted with the MongoDB Master Key.

Example

Consider the following encryption hierarchy for a three-node replica set. Atlas uses the CMK from Azure Key Vault to encrypt a unique MongoDB Master Key for each node in the cluster. Each node also contains three databases, each of which is encrypted with a unique per-database encryption key. When the cluster starts up, Atlas decrypts the MongoDB Master Key by using the CMK from Azure Key Vault and supplies this to the MongoDB Server.

Note

If you revoke Atlas's access to the CMK, Atlas shuts down the nodes in your cluster and you can't access your data until you restore access to the CMK.

Diagram of CMK workflow with AKV and Atlas
click to enlarge

Required Access

To configure customer key management, you must have Project Owner access to the project.

Users with Organization Owner access must add themselves to the project as a Project Owner.

Prerequisites

To enable customer-managed keys with Azure Key Vault for a MongoDB project, you must:

  • Have the Tenant ID (or Directory ID) for an Active Directory tenant.

  • Have the Client ID (or Application ID) and a non-expired application Password for an Azure Application associated to the Active Directory tenant.

  • Have the Resource Group name of an Azure Resource Group containing the Key Vault.

  • Have an Active Directory Application with the role of Azure key Vault Reader assigned to it.

  • Have the Subscription ID and Key Vault Name of an Azure Key Vault. Ensure the Key Vault resource group matches the resource group name specified to Resource Group.

    The Key Vault must have the following Access Policies:

    • Key Management Operations

      • GET

    • Cryptographic Operations

      • ENCRYPT

      • DECRYPT

  • Have the Key Identifier for a key in the specified Azure Key Vault.

    Atlas uses these resources when enabling encryption at rest for a cluster in the Atlas project. Consider creating an Azure Application, Resource Group, and Key Vault specifically for use with the Atlas project.

    To learn how to configure the referenced Azure components, see the Azure Documentation.

  • To help users easily create or change a cluster, you can allow public access to the key. To narrow the scope of the key and mitigate risks, use controls such as TLS and authentication.

  • For restricted access to defined IP ranges, allow access from Atlas IP addresses and the public IP addresses of your cluster nodes.

    • Ensure Atlas can communicate with your key vault. To avoid connectivity interruptions, update your configuration whenever node IP addresses change. For example, you might need to update your inbound access rules.

    • If you restrict access to the key vault, you create more complexity when IP addresses change. For example, when you create or update a cluster, you must grant access in the Azure Key Vault to any new IP addresses. You should implement a process to remove IP addresses and keys when you delete a cluster or remove nodes.

Enable Customer-Managed Keys for a Project

You must enable customer key management for a project before you can enable it on a cluster in that project.

1

Navigate to the Advanced page for your project.

  1. If it is not already displayed, select the organization that contains your desired project from the Organizations menu in the navigation bar.

  2. If it is not already displayed, select your desired project from the Projects menu in the navigation bar.

  3. Click Advanced in the sidebar.

2

Toggle the button next to Encryption at Rest using your Key Management to On.

3

Select Azure Key Vault.

4

Enter your Account Credentials.

Client ID
Enter the Client ID (or Application ID) of the Azure application.
Tenant ID
Enter the Tenant ID (or Directory ID) of the Active Directory tenant.
Secret
Enter one of the application's non-expired Passwords.
Azure Environment
Select the Azure cloud your Active Directory tenant lives in.
5

Enter the Key Vault Credentials.

Subscription ID
Enter the Subscription ID of the Key Vault.
Resource Group Name
Enter the Resource Group of the Key Vault.
Key Vault Name
Enter the name of the Key Vault.
6

Enter the Encryption Key.

Key Identifier

Enter the full URL for the key created in the Key Vault.

Important

The key identifier must be provided in the full Azure general format

https://{keyvault-name}.vault.azure.net/{object-type}/{object-name}/{object-version}
7

Click Save.

Atlas displays a banner in the Atlas console during the encryption process.

Enable Customer Key Management for an Atlas Cluster

After you Enable Customer-Managed Keys for a Project, you must enable customer key management for each Atlas cluster that contains data that you want to encrypt.

Note

You must have the Project Owner role to enable customer key management for clusters in that project.

For new clusters, toggle the Manage your own encryption keys setting to Yes when you create the cluster.

For existing clusters:

1

Navigate to the Database Deployments page for your project.

  1. If it is not already displayed, select the organization that contains your desired project from the Organizations menu in the navigation bar.

  2. If it is not already displayed, select your desired project from the Projects menu in the navigation bar.

  3. If the Database Deployments page is not already displayed, click Database in the sidebar.

2

Optional: Add IP addresses from your cluster nodes.

Depending on your Key Management Service configuration, you may have to add Atlas cluster node IP addresses to your cloud provider KMS list, so that the cluster can communicate with your KMS. To enable communication between the cluster and KMS:

  1. Send a GET request to the ipAddresses endpoint. The API endpoint returns a list of IP addresses from the existing cluster nodes, similar to the following:

    {
      "groupId": "xxx", // ObjectId
      "services": {
        "clusters": [
          {
            "clusterName": "Cluster0",
            "inbound": [
              "3.92.113.229",
              "3.208.110.31",
              "107.22.44.69"
              ],
            "outbound": [
              "3.92.113.229",
              "3.208.110.31",
              "107.22.44.69"
            ]
          }
        ]
      }
    }

  2. Add the returned IP addresses to your cloud provider's IP access list. See the prerequisites for managing customer keys with AWS, Azure, and GCP for more information.

3

Modify the cluster's configuration.

For the cluster that contains data that you want to encrypt, click the ellipses ..., then select Edit Configuration.

4

Enable cluster encryption.

  1. Expand the Additional Settings panel.

  2. Toggle the Manage your own encryption keys setting to Yes.

5

Review and apply your changes.

  1. Click Review Changes.

  2. Review your changes, then click Apply Changes to update your cluster.

Disable Customer-Managed Keys for a Project

You must disable customer key management on each cluster in a project before you can disable the feature for the project.

Important

Do not disable or delete any AKV keys that any cluster in your Atlas project uses before you have disabled customer key management within the Atlas project. If Atlas cannot access an AKV key, any data that key encrypted becomes inaccessible.

Revoke Access to an Encryption Key

You can revoke Atlas's access to an encryption key from within AKV. Atlas automatically pauses your clusters when you revoke access to the encryption key unless your AKV IP access list restricts the Atlas control plane.

To allow automatic pausing of your cluster, you must either:

Note

MongoDB adds new Atlas control plane IP addresses over time. You must keep the IP access list updated to allow automatic cluster pausing while using an IP access list for your AKV.

If the IP access list for your AKV restricts access from the Atlas control plane when you revoke access to an encryption key, you must pause your clusters manually to revoke Atlas's access.

Alerts

Atlas automatically creates an encryption key rotation alert once you configure customer key management for a project.

To reset this alert, Rotate your Azure Key Identifier.

Rotate your Azure Key Identifier

Note

MongoDB Master Key - MongoDB Responsibility

When you use your own cloud provider KMS, Atlas automatically rotates MongoDB Master Keys every 90 days. These keys are rotated on a rolling basis and the process does not require the data to be rewritten.

Rotate your Azure Key ID - Your Responsibility

Atlas does not automatically rotate the Key Identifier used for Azure Key Vault.

Atlas automatically creates an encryption key rotation alert to remind you to rotate your Azure Key Identifier every 90 days by default when you enable Encryption at Rest for an Atlas project.

You can rotate CMK stored in Azure Key Vault yourself or configure your Azure Key Vault to automatically rotate your keys. If you configure automatic rotation in Azure Key Vault, the default time period for rotation is approximately 365 days.

If you have already set up an automatic rotation in Azure Key Vault and don't want to receive the Atlas alert to rotate your Azure Key Identifier every 90 days, you can modify the default alert period to be greater than 365 days.

Prerequisites

You must create a new key in the Azure Key Vault associated to the Atlas project.

Procedure

The following procedure documents how to rotate your Atlas project Key Identifier by specifying a new key identifier in Atlas.

1

Navigate to the Advanced page for your project.

  1. If it is not already displayed, select the organization that contains your desired project from the Organizations menu in the navigation bar.

  2. If it is not already displayed, select your desired project from the Projects menu in the navigation bar.

  3. Click Advanced in the sidebar.

2

Click Edit .

3

Update the Azure credentials.

  1. Click Azure Key Vault if the Azure Key Vault selector is not already active.

  2. Click Encryption Key if the Encryption Key selector is not already active.

  3. Enter the Azure Key Identifier in the Key Identifier field.

    Include the full URL to the new encryption key identifier. For example:

    https://mykeyvault.vault.azure.net/keys/AtlasKMSKey/a241124e3d364e9eb99fbd3e11124b23

    Important

    The encryption key must belong to the Key Vault configured for the project. Click the Key Vault section to view the currently configured Key Vault for the project.

  4. Click Update Credentials.

Atlas displays a banner in the Atlas UI during the Key Identifier rotation process. Do not delete or disable the original Key Identifier until your changes have deployed.

If the cluster uses Back Up Your Database Deployment, do not delete or disable the original Key Identifier until you validate that no snapshots used that key for encryption.

Alerts

Atlas resets the encryption key rotation alert alert at the completion of this procedure.

Azure Key Vault Failover During an Outage

During a regional outage, your Azure KMS region might become unavailable. If this happens, Azure automatically routes incoming KMS requests to a pre-assigned secondary region. To learn more, see Azure Key Vault Failover and Regional Pairings.

If both regions are down, you can manually migrate your key to a region outside of the regional pairing. To learn more, see Move a Key Vault across Regions.

Note

If you've enabled Encryption at Rest using Customer Key Management, you can perform encrypt and decrypt operations while at least one node is still available during the outage.

Related Topics

← Manage Customer Keys with AWS KMS
Manage Customer Keys with Google Cloud KMS →

On this page