Docs Menu

Docs HomeLaunch & Manage MongoDBMongoDB Atlas

Manage Customer Keys with Google Cloud KMS

On this page

  • Enable Customer-Managed Keys with Google Cloud KMS
  • Key Concepts
  • Required Access
  • Prerequisites
  • Enable Customer-Managed Keys for a Project
  • Enable Customer Key Management for an Atlas Cluster
  • Alerts
  • Rotate your GCP Key Version Resource ID
  • MongoDB Master Key - MongoDB Responsibility
  • Your Google Cloud CMK - Your Responsibility
  • Prerequisites
  • Procedure
  • Alerts
  • 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.

Atlas uses your Google Cloud Service Account Key to encrypt and decrypt your MongoDB master keys. These MongoDB master keys are used to encrypt cluster database files and cloud providers snapshots.

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

Atlas encrypts your data at rest using encrypted storage media. Using keys you manage with Google Cloud KMS, Atlas encrypts your data a second time when it writes it to the MongoDB encrypted storage engine. You use your Google Cloud SAK to encrypt the MongoDB master encryption keys.

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

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

MongoDB Master Key

MongoDB Master Key is an encryption key used by the MongoDB Server to encrypt the WiredTiger Storage Engine. The key isn't stored in the MongoDB database, but it's supplied externally through KMIP. When the MongoDB server starts, it obtains the master key from the KMIP or local file and then stores it in memory. This key is then used to decrypt the data stored in the WiredTiger storage engine.

Atlas maintains a layer that translates requests between MongoDB Server and a CMK that you created in Google Cloud. To translate the requests, Atlas uses the layer to request the CMK to create an encrypted data encryption key (DEK). This encrypted DEK is generated per Atlas deployment.

For example, for a three node M10+ replica set as shown in the following figure, there are three unique encrypted DEKs, one per node. Atlas stores the encrypted DEK on disk on each node in the Atlas cluster. When the cluster starts up, the Atlas layer decrypts the DEK using the customer provided encryption key and supplies this to the MongoDB Server.

Atlas and AWS KMS key transfer workflow
click to enlarge
Per Database Encryption Key in a MongoDB Cluster

MongoDB Server maintains a per database encryption key in the MongoDB cluster. In the preceding figure, there are three databases on the MongoDB cluster, each of which is encrypted with a unique database encryption key. Each of these keys are then encrypted with the MongoDB Master Key.

Data Encryption Key (in cloud provider terminology) or MongoDB Master Key

Atlas uses the customer provided encryption key to create an encrypted DEK. Atlas also uses a customer key management instance to decrypt this encrypted DEK and supply the resulting plaintext key to the MongoDB Server over the wire using TLS. When MongoDB Server uses this plaintext key, it refers to it as the MongoDB Master Key, whereas a cloud provider's customer key management instance might refer to it as a DEK. To learn more about DEKs, see Data encryption keys.

Customer Master Key (CMK)

Customer Master Keys are used to encrypt and decrypt a MongoDB Master Key (or DEK). The CMK exists only on the customer key management instance. To learn more about CMKs, see Customer-managed encryption keys.

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.

To enable customer-managed keys with Google Cloud KMS for a MongoDB project, you must have:

  • Your Google Cloud Service Account Key.

  • Your symmetric Encryption Key in Google Cloud KMS.

  • The Key Version Resource ID associated with your Google Cloud KMS Encryption Key.

  • A Google Cloud service account with credentials specified in your Service Account Key with sufficient permissions to:

    • Get the Google Cloud KMS Encryption Key version.

    • Encrypt data with the Google Cloud KMS Encryption Key version.

    • Decrypt data with the Google Cloud KMS Encryption Key.

    Note

    The key, not the key version, handles decryption.

  • If your Google Cloud KMS configuration requires it, use Accessible Services from GCP from Atlas IP addresses and the public IP addresses or DNS hostnames of your cluster nodes so that Atlas can communicate with your KMS. If the node IP addresses change, you must update your configuration to avoid connectivity interruptions.

Tip

See also:

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

1
  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
3
4

Your Service Account Key should be formatted as a JSON object. It contains the encryption credentials for your GCP service account.

5

Your key version resource ID is the fully-qualified resource name for a CryptoKeyVersion.

6

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

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

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

4
  1. Expand the Additional Settings panel.

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

5
  1. Click Review Changes.

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

Atlas automatically creates an encryption key rotation alert once you configure customer key management for a project. You can reset this alert at any time by rotating your GCP Key Version Resource ID.

Note

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

Atlas does not automatically rotate the Key Version Resource ID used for Google Cloud key management.

As a best practice, Atlas creates an alert to remind you to rotate your GCP Key Version Resource ID every 90 days by default when you enable Encryption at Rest for the Atlas project. You can configure the time period of this alert.

You can rotate your Google Cloud CMK yourself or configure your Google Cloud KMS instance to automatically rotate your CMK. If you configure automatic Google Cloud CMK rotation, the default time period for rotation is approximately 365 days.

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

You must create a new Service Account Key in the Google Cloud account associated with your Atlas project.

The following procedure documents how to rotate your Atlas project Key Identifier by specifying a new Key Version Resource ID in Atlas.

1
  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
3
  1. Click Google Cloud KMS if the Google Cloud KMS tab is not already active.

  2. Expand Encryption Key Credentials if the Encryption Key Credentials dialog is not already displayed.

  3. Enter the GCP Key Version Resource ID in the Key Identifier entry.

    Include the fully-qualified resource name for a CryptoKeyVersion.

    Example

    projects/my-project-0/locations/us-east4/keyRings/my-key-ring-0/cryptoKeys/my-key-0/cryptoKeyVersions/1

    The encryption key must belong to the Google Cloud Service Account Key configured for your Atlas project. Click the Service Account Key section to view the currently configured Service Account Key for the project.

  4. Click Update Credentials.

Atlas displays a banner in the Atlas console during the Key Identifier rotation process.

Warning

Do not delete or disable the original Key Version Resource ID until your changes have deployed.

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

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

←  Manage Customer Keys with Azure Key VaultSet Up Database Auditing →