Docs Menu

Customer Key Management with AWS KMS

On this page

  • Prerequisites
  • Enable Role-Based Access to Your Encryption Key for a Project
  • Switch to Role-Based Access to Your Encryption Key for a Project
  • Enable Customer Key Management for an Atlas Cluster
Note

Starting with the 26 January 2021 Release, you must use AWS IAM roles instead of IAM users to manage access to your AWS KMS encryption keys for customer key management.

When you move from AWS IAM users to roles, ensure that your new role has access to your old AWS customer master key.

Important
Serverless Instances are in Preview

Serverless instances are in preview and do not support this feature at this time. To learn more, see Serverless Instance Limitations.

You can configure your Atlas project to use an AWS IAM role for accessing your AWS KMS keys for encryption at rest. You can either use an existing role or create a new role when you enable encryption at rest for your project.

This page covers configuring customer key management on your Atlas project for role-based access.

If you have not yet enabled encryption at rest for your new or existing Atlas project, follow the Enable Role-Based Access to Your Encryption Key for a Project procedure to enable encryption at rest for your Atlas project. If you have an Atlas project for which you have already enabled encryption at rest and configured credentials-based access to your encryption keys, follow the Switch to Role-Based Access to Your Encryption Key for a Project procedure to switch to role-based access to your encryption keys.

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

Tip

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

  • Have a symmetric AWS customer master key (CMK). To learn how to create a key, see Creating Keys in the AWS documentation.
  • Have an AWS IAM role with sufficient privileges. Atlas must have permission to perform the following actions with your key:

    Note

    If you wish to use the AWS CMK with an AWS IAM role from a different AWS account instead of that of the IAM role which created the AWS CMK, ensure you have sufficient privileges:

    • Add a key policy statement under the AWS CMK to include the external AWS account.
    • Add an IAM inline policy for the IAM role in the external AWS account.

    For a comprehensive discussion of IAM roles and customer master keys, see the AWS documentation.

    After confirming the above privileges, you can follow the usual steps to configure the KMS settings in Atlas, with the following exception:

    • You must provide the full ARN for the CMK (e.g. arn:aws:kms:eu-west-2:111122223333:key/12345678-1234-1234-1234-12345678) instead of the master key ID (e.g. 12345678-1234-1234-1234-12345678) in the CMK ID field.

    To learn how to create an IAM role, see IAM Roles in the AWS documentation.

    Atlas uses the same IAM role and CMK settings for all clusters in a project for which Encryption at Rest is enabled.

  • If your AWS KMS configuration requires it, allow access 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.
Important

If you switch your Atlas project from credentials-based access to role-based access to your encryption keys, you cannot undo the role-based access configuration and revert to credentials-based access for that project.

After you Enable Role-Based Access to Your Encryption Key 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 Databases in the sidebar.
2

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

3
  1. Expand the Additional Settings panel.
  2. Toggle the Manage your own encryption keys setting to Yes.
4
  1. Click Review Changes.
  2. Review your changes, then click Apply Changes to update your cluster.
Give Feedback
MongoDB logo
© 2021 MongoDB, Inc.

About

  • Careers
  • Legal Notices
  • Privacy Notices
  • Security Information
  • Trust Center
© 2021 MongoDB, Inc.