Docs Menu

Docs Home → Launch & Manage MongoDB → MongoDB Atlas

Encryption at Rest using Customer Key Management

On this page

  • Required Access
  • Configure Atlas with Customer Key Management
  • Enable Customer Key Management for an Atlas Cluster
  • Add Nodes to an Encrypted Atlas Cluster
  • Validate your KMS Configuration
  • Restore a Deleted Key
  • Encrypted Backups

Important

Feature unavailable in Serverless Instances

Serverless instances don't support this feature at this time. To learn more, see Serverless Instance Limitations.

Atlas encrypts all cluster storage and snapshot volumes at rest by default. You can add another layer of security by using your cloud provider's KMS together with the MongoDB encrypted storage engine.

Configuring Encryption at Rest using your Key Management incurs additional charges for the Atlas project. To learn more, see Advanced Security.

You can use one or more of the following customer key management providers when configuring Encryption at Rest for the Atlas project:

After configuring at least one key management provider for the Atlas project, you can enable customer key management for each Atlas cluster for which they require encryption. The key management provider does not have to match the cluster cloud service provider.

Note

When you enable or disable customer key management, Atlas performs an initial sync to re-encrypt your cluster data.

Atlas cannot rotate customer-managed encryption keys. Refer to your key management provider's documentation for guidance on key rotation. When you set customer key management in a project, Atlas creates a 90-day key rotation alert.

If your KMS provider becomes unavailable, this doesn't disable your cluster while it still runs. If you decide to restart your cluster, the lack of a KMS provider disables your cluster.

Required Access

To configure Encryption at Rest, you must have Organization Owner or Project Owner access to Atlas.

Configure Atlas with Customer Key Management

Encryption at Rest using Key Management requires valid key management provider credentials and an encryption key. To provide these details and enable Customer Key Management:

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

Enter your key management provider account credentials and provide an encryption key.

4

Click Save.

5

Optional: Allow access to or from the Atlas control plane.

Important

At this point in time, inbound Atlas control plane IP addresses are not yet available. The inbound IP address list in your API response is empty.

To manually retrieve a list of inbound Atlas control plane IP addresses, see Required Inbound Access.

Depending on your Key Management Service configuration, you may have to add Atlas control plane IP addresses to enable Encryption at Rest for your project so that Atlas can communicate with your KMS. To enable communication between Atlas and KMS:

  1. Send a GET request to the returnAllControlPlaneIPAddresses endpoint. The API endpoint returns a list of inbound and outbound Atlas control plane IP addresses in CIDR categorized by cloud provider and region, similar to the following:

    {
      "controlPlane": {
        "inbound": {
          "aws": { // cloud provider
            "us-east-1": [ // region
              "3.92.113.229/32",
              "3.208.110.31/32",
              "107.22.44.69/32"
              ...,
            ],
            ...
          }
        },
        "outbound": {
          "aws": { // cloud provider
            "us-east-1": [ // region
              "3.92.113.229/32",
              "3.208.110.31/32",
              "107.22.44.69/32"
              ...,
            ],
            ...
          }
        }
      },
      "data_federation": {
        "inbound": {},
        "outbound" {}
      },
      "app_services": {
        "inbound": {},
        "outbound" {}
      },
      ...
    }

  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.

Enable Customer Key Management for an Atlas Cluster

After you Configure Atlas with Customer Key Management, 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:

1

Enable cluster encryption.

Toggle the Manage your own encryption keys setting to Yes on the cluster configuration form.

2

Review and apply your changes.

  1. Click Review Changes.

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

3

Optional: Add IP addresses from the new cluster nodes.

Depending on your Key Management configuration, you may have to add Atlas cluster node IP addresses to your cloud provider KMS access 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 new 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. You must modify your IP access list before the provisioning plan rolls back. The cluster attempts provisioning for up to three days before the provisioning plan rolls back from IP access restrictions.

    See the prerequisites for managing customer keys with AWS, Azure, and GCP for more information.

    Note

    If you need more time to update the IP access list, you can:

    • Provision the cluster without Encryption at Rest then enable it after you update the IP access list.

    • Configure a more inclusive IP access list on your cloud provider's Key Management Service, launch the cluster with Encryption at Rest, then modify the IP access list.

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.

Add Nodes to an Encrypted Atlas Cluster

1

Add nodes or shards to your replica set cluster or sharded cluster.

You can add electable nodes to M10+ clusters or increase the number of shards in your sharded cluster.

2

Optional: Add IP addresses from the new cluster nodes or shards.

Depending on your Key Management configuration, you may have to add Atlas cluster node IP addresses to your cloud provider KMS access 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 new cluster nodes or shards, similar to the following:

    {
      "groupId": "xxx", // ObjectId
      "services": {
        "clusters": [
          {
            "clusterName": "Cluster0",
            "inbound": [
              "3.92.113.229",
              "3.208.110.31",
              "107.22.44.69"
              ], // List<String>
            "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. You must modify your IP access list before the provisioning plan rolls back. The cluster attempts provisioning for up to three days before the provisioning plan rolls back from IP access restrictions.

    See the prerequisites for managing customer keys with AWS, Azure, and GCP for more information.

Validate your KMS Configuration

Atlas validates your KMS configuration:

Atlas shuts down all mongod and mongos processes on the next scheduled validity check if one of the following conditions exist:

  • your key management provider credentials become invalid

  • someone deletes or disables your encryption key

If Atlas can't connect to your key management provider, Atlas doesn't shut down your processes. The Encryption at Rest KMS network access denied alert is enabled by default for all new projects to communicate any KMS network access failures. You can configure your alert settings.

If Atlas shuts down your clusters, the following events occur:

  • Atlas sends an email to the Project Owner listing all affected clusters.

  • The Database Deployments page reflects that Atlas disabled your clusters due to invalid Encryption at Rest settings.

You can't read or write data on disabled clusters. You can submit updates to disabled clusters, such as disk and instance size changes. Atlas processes these changes once someone restores your encryption key. Atlas continues to perform maintenance and apply security patches. Disabled clusters retain all your data, so billing continues.

Note

Virtual Machine Power

While a cluster is disabled, Atlas does not stop the Virtual Machine (VM) the cluster is running on. Atlas may perform patches that reboot the server, but VM power is not cycled.

To regain access to your data:

The Try Again button is to the right of the Customer Master Key ID field in Atlas Advanced Security settings
click to enlarge

After updating your configuration, click Try Again to validate it. If you don't, Atlas validates on its next scheduled check. All mongod and mongos processes restart after Atlas determines your configuration to be valid.

Warning

If your key was deleted, restore that key to regain access to your clusters. You cannot change a key or disable Encryption at Rest using Customer Key Management without a valid key.

Restore a Deleted Key

To restore a deleted key, see your key management provider's documentation:

Encrypted Backups

Atlas encrypts all snapshot volumes. This secures your cluster data on disk. Using your cloud provider's KMS, you can:

  • Encrypt your snapshot storage volumes where you store your backups.

  • Encrypt the data files in your snapshots.

  • Restore snapshots with the key that was active at the time the snapshot was taken.

  • Encrypt PIT restore oplog data.

You cannot restore snapshots encrypted with keys that have become invalid.

You cannot enable Legacy Backups (Deprecated) on clusters encrypted with keys that you manage. You can specify a base snapshot schedule that backs up every 6 hours.

To learn more about customer key management and Cloud Backups, see Storage Engine and Cloud Backup Encryption and Restore from a Snapshot Using Encryption at Rest.

← Set Up Self-Managed X.509 Authentication
Manage Customer Keys with AWS KMS →

On this page