> For the complete MongoDB documentation index, see www.mongodb.com/docs/llms.txt # Manage Customer Keys with Google Cloud KMS **Note:** This feature is not available for any of the following deployments: - Free clusters - Flex clusters To learn more, see [Limits.](https://www.mongodb.com/docs/atlas/reference/limitations.md#std-label-limits) You can use a customer-managed key (CMK) from Google Cloud KMS to further encrypt your data at rest in Atlas. **Note:** The MongoDB Atlas Shared Responsibility Model defines the complementary duties of MongoDB and its customers in maintaining a secure and resilient data environment. Under this framework, MongoDB manages the security and operational integrity of the underlying platform, while customers are responsible for the configuration, management, and data policies of their specific deployments. For a detailed breakdown of ownership across security and operational excellence, see [Shared Responsibility Model.](https://www.mongodb.com/resources/products/fundamentals/shared-responsibility) Atlas uses your CMK (customer-managed key) from Google Cloud KMS to encrypt and decrypt MongoDB Master Keys, which are then used to encrypt cluster database files and [cloud providers snapshots](https://www.mongodb.com/docs/atlas/backup/cloud-backup/overview.md#std-label-backup-cloud-provider). To learn more about how Atlas uses CMK (customer-managed key)s for encryption, see [Enable Customer-Managed Keys with Google Cloud KMS.](https://www.mongodb.com/docs/atlas/security-gcp-kms.md#std-label-enable-cmk-gcp) When you use your own cloud provider KMS (Key Management Service), Atlas automatically rotates MongoDB Master Keys at least every 90 days. Your key rotation will begin during a [maintenance window](https://www.mongodb.com/docs/atlas/tutorial/cluster-maintenance-window.md#std-label-configure-maintenance-window), if you have one configured. Deferring maintenance (either manually or automatically) may cause the key to be rotated past the 90-day mark. Keys are rotated on a rolling basis and the process does not require the data to be rewritten. **Note: Atlas Infinite** Google Cloud KMS isn't available for [Atlas Infinite](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-Atlas-Infinite) during public preview. Atlas Infinite supports customer-managed keys only through [AWS KMS](https://www.mongodb.com/docs/atlas/security-aws-kms.md#std-label-security-aws-kms) during public preview. To learn how encryption at rest works for Atlas Infinite, see [Atlas Infinite Encryption.](https://www.mongodb.com/docs/atlas/security-encryption-at-rest-overview.md#std-label-atlas-infinite-encryption-at-rest) You must configure customer key management for the Atlas project before enabling it on clusters in that project. ## Enable Customer-Managed Keys with Google Cloud KMS Customer key management in Atlas follows a process called [envelope encryption](https://cloud.google.com/kms/docs/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 keys are encryption keys that you create, own, and manage in Google Cloud KMS. You create the CMK (customer-managed key) in Google Cloud KMS and connect it to Atlas at the [Project](https://www.mongodb.com/docs/atlas/organizations-projects.md#std-label-projects) level. To learn more about the CMK (customer-managed key)s used in Google Cloud KMS, see [Google Cloud Documentation](https://cloud.google.com/kms/docs/cmek). Atlas uses this key only to encrypt the MongoDB Master Keys. Each node in your Atlas cluster creates a MongoDB Master Key. MongoDB Master Keys are encryption keys that a MongoDB Server uses to encrypt the per-database encryption keys. Atlas saves an encrypted copy of the key locally. This key is encrypted with the CMK (customer-managed key) and encrypts the per-database encryption keys. 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 (customer-managed key) from Google Cloud KMS 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 (customer-managed key) from Google Cloud KMS and supplies this to the MongoDB Server. **Note:** If you revoke Atlas's access to the CMK (customer-managed key), Atlas shuts down the nodes in your cluster and you can't access your data until you restore access to the CMK (customer-managed key). ![Diagram of CMK workflow with Google Cloud KMS and Atlas](/images/gcp-kms-cmk-diagram.png) ## Required Access To configure customer key management, you must have [`Project Owner`](https://www.mongodb.com/docs/atlas/reference/user-roles.md#mongodb-authrole-Project-Owner) access to the project. Users with [`Organization Owner`](https://www.mongodb.com/docs/atlas/reference/user-roles.md#mongodb-authrole-Organization-Owner) access must add themselves to the project as a `Project Owner`. ### Prerequisites To enable customer-managed keys with Google Cloud KMS (Key Management Service) for a MongoDB project, you must have: - Use an M10 or larger cluster. * 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 (Key Management Service) configuration requires it, create [Access Levels from GCP](https://cloud.google.com/vpc-service-controls/docs/use-access-levels) for [Atlas IP addresses](https://www.mongodb.com/docs/atlas/setup-cluster-security.md#std-label-atlas-add-inbound-ips) and the public IP addresses or DNS hostnames of your cluster nodes so that Atlas can communicate with your KMS (Key Management Service). If the node IP addresses [change](https://www.mongodb.com/docs/atlas/reference/faq/networking.md#std-label-faq-public-ip-changes), you must update your configuration to avoid connectivity interruptions. **See also:** See the Google Cloud documentation to learn how to: - [Create a service account key.](https://cloud.google.com/docs/authentication/getting-started) - [Obtain a key version resource ID.](https://cloud.google.com/kms/docs/object-hierarchy#key_version) - [Grant roles to service accounts.](https://cloud.google.com/iam/docs/granting-roles-to-service-accounts) ### 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. In Atlas, go to the Advanced page for your project. If it's not already displayed, select the organization that contains your project from the Organizations menu in the navigation bar. If it's not already displayed, select your project from the Projects menu in the navigation bar. In the sidebar, click Database & Network Access under the Security heading. In the sidebar, click Advanced. The [Advanced](https://cloud.mongodb.com/go?l=https%3A%2F%2Fcloud.mongodb.com%2Fv2%2F%3Cproject%3E%23%2Fsecurity%2Fadvanced) page displays. 2. Toggle the button next to Encryption at Rest using your Key Management to On. 3. Select Google Cloud KMS. 4. Enter the Key Version Resource ID. Enter the key version resource ID for the Google Cloud KMS key that you want to use to encrypt your data at rest. Your key version resource ID is the fully-qualified resource name for a [CryptoKeyVersion.](https://cloud.google.com/kms/docs/reference/rest/v1/projects.locations.keyRings.cryptoKeys.cryptoKeyVersions#CryptoKeyVersion) **Important:** You must enter a valid ID before you can configure your authentication method. 5. Configure your authentication method. Atlas supports two authentication methods for GCP KMS: - **Service Account (Recommended)**: Use an Atlas-managed service account specific to your project to authenticate to GCP. - **Static Credentials**: Provide a customer-managed service account key. ### Service Account To grant access in a secure manner, Atlas uses a [service account](https://cloud.google.com/iam/docs/service-account-impersonation) specific to your Atlas project to authenticate to GCP. You can then assign policies to the service account to control access to your project's resources. **Note:** If you previously configured encryption at rest with static credentials and are now migrating to service account-based authentication, note that this migration is strictly one-way. Atlas does not support reverting back to the static credential authentication method. If you have an existing Atlas GCP service account with the required permissions already configured, select it from the Connect Service Account dropdown menu. Otherwise, complete the following steps: Click Authorize a new service account. The Encrypt Data with GCP KMS dialog box appears. If you have not yet set up a service account for your Atlas project, click the Set Up button to create your GCP resources. Atlas provisions the GCP [folder](https://cloud.google.com/resource-manager/docs/creating-managing-folders) and creates the service account. The folder is required in order to create service accounts. Skip this step if you already have a service account for your Atlas project. Select the Atlas service account from the dropdown menu or [create a new one.](https://www.mongodb.com/docs/atlas/configure-api-access.md#std-label-create-org-api-key) Run the [gcloud](https://cloud.google.com/sdk/docs/install) commands that appear to grant the service account the following required permissions: - Enable Encrypt/Decrypt operations ```sh gcloud kms keys add-iam-policy-binding \ \ --location \ --keyring \ --member \ --role="roles/cloudkms.cryptoKeyEncrypterDecrypter" ``` - Enable GetPublicKey operations ```sh gcloud kms keys add-iam-policy-binding \ \ --location \ --keyring \ --member \ --role="roles/cloudkms.viewer" ``` Click Validate & Finish to confirm. 6. Click Save. ### Enable Customer Key Management for an Atlas Cluster After you [Enable Customer-Managed Keys for a Project](https://www.mongodb.com/docs/atlas/security-gcp-kms.md#std-label-gcp-kms-configure-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`](https://www.mongodb.com/docs/atlas/reference/user-roles.md#mongodb-authrole-Project-Owner) role to enable customer key management for clusters in that project. For new clusters, toggle the [Manage your own encryption keys](https://www.mongodb.com/docs/atlas/cluster-additional-settings.md#std-label-create-cluster-enable-encryption) setting to Yes when you create the cluster. For existing clusters: 1. In Atlas, go to the Clusters page for your project. If it's not already displayed, select the organization that contains your desired project from the Organizations menu in the navigation bar. If it's not already displayed, select your desired project from the Projects menu in the navigation bar. In the sidebar, click Clusters under the Database heading. The [Clusters](https://cloud.mongodb.com/go?l=https%3A%2F%2Fcloud.mongodb.com%2Fv2%2F%3Cproject%3E%23%2Fclusters) page displays. 2. Modify the cluster's configuration. For the cluster that contains data that you want to encrypt, click the , then select Edit Configuration. 3. Enable cluster encryption. Expand the Additional Settings panel. Toggle the Manage your own encryption keys setting to Yes. Verify the status of the Require Private Networking setting for your cluster. If you configured Encryption at Rest Using CMK (customer-managed key) (Over Private Networking) for Atlas at the project level, the status is Active. If you haven't configured any private endpoint connection for your project, the status is Inactive. 4. Review and apply your changes. Click Review Changes. Review your changes, then click Apply Changes to update your cluster. ### Alerts Atlas automatically creates an [`encryption key rotation alert`](https://www.mongodb.com/docs/atlas/reference/alert-conditions.md#mongodb-alert-GCP-encryption-key-elapsed-time-since-last-rotation-is-above--n--days) 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.](https://www.mongodb.com/docs/atlas/security-gcp-kms.md#std-label-gcp-kms-rotate-key) ## Rotate your GCP Key Version Resource ID **Note:** This feature is not available for any of the following deployments: - Free clusters - Flex clusters To learn more, see [Limits.](https://www.mongodb.com/docs/atlas/reference/limitations.md#std-label-limits) ### MongoDB Master Key - MongoDB Responsibility When you use your own cloud provider KMS (Key Management Service), Atlas automatically rotates MongoDB Master Keys at least every 90 days. Your key rotation will begin during a [maintenance window](https://www.mongodb.com/docs/atlas/tutorial/cluster-maintenance-window.md#std-label-configure-maintenance-window), if you have one configured. Deferring maintenance (either manually or automatically) may cause the key to be rotated past the 90-day mark. Keys are rotated on a rolling basis and the process does not require the data to be rewritten. ### Your Google Cloud CMK (customer-managed key) - Your Responsibility Atlas does *not* automatically rotate the Key Version Resource ID used for Google Cloud key management. As a best practice, Atlas creates an [`alert`](https://www.mongodb.com/docs/atlas/reference/alert-conditions.md#mongodb-alert-AWS-encryption-key-elapsed-time-since-last-rotation-is-above--n--days) to remind you to rotate your GCP Key Version Resource ID every 90 days by default when you [enable Encryption at Rest](https://www.mongodb.com/docs/atlas/security-gcp-kms.md#std-label-security-gcp-kms) for the Atlas project. You can configure the time period of this alert. You can [rotate](https://cloud.google.com/kms/docs/rotate-key) your Google Cloud CMK (customer-managed key) yourself or configure your Google Cloud KMS (Key Management Service) instance to [automatically rotate](https://cloud.google.com/kms/docs/rotate-key#automatic) your CMK (customer-managed key). If you configure automatic Google Cloud CMK (customer-managed key) rotation, the default time period for rotation is approximately 365 days. If you have already set up an automatic CMK (customer-managed key) rotation in Google Cloud and don't want to receive the Atlas alert to rotate your CMK (customer-managed key) every 90 days, you can [modify](https://www.mongodb.com/docs/atlas/configure-alerts.md#std-label-configure-alerts) the default alert period to be greater than 365 days. ### Prerequisites You must create a new Service Account Key in the Google Cloud account associated with your Atlas project. ### Procedure The following procedure documents how to rotate your Atlas project Key Identifier by specifying a new Key Version Resource ID in Atlas. 1. In Atlas, go to the Advanced page for your project. If it's not already displayed, select the organization that contains your project from the Organizations menu in the navigation bar. If it's not already displayed, select your project from the Projects menu in the navigation bar. In the sidebar, click Database & Network Access under the Security heading. In the sidebar, click Advanced. The [Advanced](https://cloud.mongodb.com/go?l=https%3A%2F%2Fcloud.mongodb.com%2Fv2%2F%3Cproject%3E%23%2Fsecurity%2Fadvanced) page displays. 2. Click Edit . 3. Update the GCP Key details. Click Google Cloud KMS if the Google Cloud KMS tab is not already active. Expand Encryption Key Credentials if the Encryption Key Credentials dialog box is not already displayed. Enter the GCP Key Version Resource ID in the Key Identifier entry. Include the fully-qualified resource name for a [CryptoKeyVersion.](https://cloud.google.com/kms/docs/reference/rest/v1/projects.locations.keyRings.cryptoKeys.cryptoKeyVersions#CryptoKeyVersion) **Example:** ```sh 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. 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 Cluster](https://www.mongodb.com/docs/atlas/backup/cloud-backup/overview.md#std-label-backup-cloud-provider), do **not** delete or disable the original Key Version Resource ID until you ensure that no snapshots used that key for encryption. ### Alerts Atlas resets the [`encryption key rotation alert`](https://www.mongodb.com/docs/atlas/reference/alert-conditions.md#mongodb-alert-GCP-encryption-key-elapsed-time-since-last-rotation-is-above--n--days) timer at the completion of this procedure. ### Enable Customer-Managed Keys for Search Nodes By default, MongoDB and [search processes](https://www.mongodb.com/docs/search/query/query-ref.md#std-label-about-mongot) run on the same nodes. With this architecture, customer-managed encryption applies to your database data, but it does not apply to search indexes. When you enable [dedicated Search Nodes](https://www.mongodb.com/docs/search/deployment/deployment-options.md#std-label-what-is-search-node), search processes run on separate nodes. This allows you to enable [Search Node Data Encryption](https://www.mongodb.com/docs/atlas/security-kms-encryption.md#std-label-enable-search-node-encryption), so you can encrypt both database data and search indexes with the same customer-managed keys for comprehensive encryption coverage. Dedicated Search Nodes are not supported on Atlas Infinite clusters clusters during public preview. **Note:** Database nodes and Search Nodes use different encryption methods with the same customer-managed keys. Database nodes use the [WiredTiger Encrypted Storage Engine](https://www.mongodb.com/docs/manual/core/security-encryption-at-rest/#encrypted-storage-engine), while Search Nodes use encryption at the disk level. **Important:** This feature is available across KMS (Key Management Service) providers. ## Related Topics - To enable Encryption at Rest using your Key Management when deploying an Atlas cluster, see [Manage Your Own Encryption Keys.](https://www.mongodb.com/docs/atlas/cluster-additional-settings.md#std-label-create-cluster-enable-encryption) - To enable Encryption at Rest using your Key Management for an existing Atlas cluster, see [Enable Encryption at Rest.](https://www.mongodb.com/docs/atlas/scale-cluster.md#std-label-scale-cluster-enable-encryption) - To learn more about Encryption at Rest using your Key Management in Atlas, see [Encryption at Rest using Customer Key Management.](https://www.mongodb.com/docs/atlas/security-kms-encryption.md#std-label-security-kms-encryption) - To learn more about MongoDB Encryption at Rest, see [Encryption at Rest](https://www.mongodb.com/docs/manual/core/security-encryption-at-rest/) in the MongoDB server documentation. - To learn more about Encryption at Rest with Cloud Backups, see [Storage Engine and Cloud Backup Encryption.](https://www.mongodb.com/docs/atlas/backup/cloud-backup/cloud-backup-encryption.md#std-label-encrypted-cloud-provider-snapshot)