Manage Customer Keys with AWS KMS

In Atlas, go to the Advanced page for your project.

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

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

3. In the sidebar, click Advanced under the Security heading.

   The Advanced page displays.

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

Click the Authorize a new IAM role link to authorize an AWS IAM role to Atlas to access your AWS KMS keys for encryption at rest.

To create a new AWS IAM role for accessing your AWS KMS keys for encryption at rest, follow the Create New Role with the AWS CLI procedure. If you have an existing AWS IAM role that you want to authorize, follow the Add Trust Relationships to an Existing Role procedure.

Add an access policy to your AWS IAM role via the AWS console or CLI. See Managing IAM policies for more information.

The access policy for encryption at rest looks similar to the following:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "kms:Decrypt",
        "kms:Encrypt",
        "kms:DescribeKey"
      ],
      "Resource": [
        "arn:aws:kms:us-east-1:123456789012:key/12x345y6-7z89-0a12-3456-xyz123456789"
      ]
    }
  ]
}

Repeat steps 1 and 2 to assign the role you authorized in step 3 to your project for accessing your encryption key.

Specify the following for accessing your encryption key and click Save.

1. Select the role to assign from the AWS IAM role dropdown list.

2. Specify your encryption key in the Customer Master Key ID field.

3. Select the AWS region for your encryption key.

Send a POST request to the cloudProviderAccess endpoint.

Use the API endpoint to create a new AWS IAM role. Atlas will use this role for authentication with your AWS account.

Keep the returned field values atlasAWSAccountArn and atlasAssumedRoleExternalId handy for use in the next step.

Modify your AWS IAM role trust policy.

1. Log in to your AWS Management Console.

2. Navigate to the Identity and Access Management (IAM) service.

3. Select Roles from the left-side navigation.

4. Click on the existing IAM role you wish to use for Atlas access from the list of roles.

5. Select the Trust Relationships tab.

6. Click the Edit trust relationship button.

7. Edit the Policy Document. Add a new Statement object with the following content.

   Note

   This policy statement allows MongoDB's AWS Principal to use the customer's KMS key for encryption and decryption operations. The Atlas Principal is not secret and is used across all Atlas customers. This is a highly-restricted, purpose-limited AWS account, with no resources in it other than the IAM user. The ExternalId in the policy statement is unique for each Atlas project, but it is not secret. The ExternalId is used to mitigate the possibility of cross-context (confused deputy) vulnerabilities. Atlas's use of a common principal to access all customers' keys is an access pattern recommended by Amazon, as described here.

   Note

   Replace the highlighted lines with values returned from the API call in step 1.

   {
     "Version": "2020-03-17",
     "Statement": [
       {
         "Effect": "Allow",
         "Principal": {
           "AWS": "<atlasAWSAccountArn>"
         },
         "Action:" "sts:AssumeRole",
         "Condition": {
           "StringEquals": {
             "sts:ExternalId": "<atlasAssumedRoleExternalId>"
           }
         }
       }
     ]
   }

8. Click the Update Trust Policy button.

Authorize the newly created IAM role.

Use the API endpoint to authorize and configure the new IAM Assumed Role ARN. If the API call is successful, you can use the roleId value when configuring Atlas services that use AWS.

Enable AWS KMS with Role Authorization on the Project

Send a PATCH request to the encryptionAtRest API endpoint to update the awsKms.roleId field with your authorized AWS IAM role ID.

curl --user "{public key}:{private key}" --digest \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --include \
  --request PATCH \
  "https://cloud.mongodb.com/api/atlas/v1.0/groups/{groupId}/encryptionAtRest?pretty=true&envelope=true" \
  --data '
   {
       "awsKms": {
           "enabled": true,
           "roleId": "<roleId>",
           "customerMasterKeyID": "<master-key-id>",
           "region": "<aws-region>"
       }
   }'

In Atlas, go to the Advanced page for your project.

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

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

3. In the sidebar, click Advanced under the Security heading.

   The Advanced page displays.

For the Encryption at Rest using your Key Management section, click Edit .

Read the information in the Grant Access to Keys with an AWS IAM Role section and click Configure.

Authorize and assign an AWS IAM role to Atlas to access your AWS KMS keys for encryption at rest.

To create a new AWS IAM role for accessing your AWS KMS keys for encryption at rest, follow the Create New Role with the AWS CLI procedure. If you have an existing AWS IAM role that you want to authorize, follow the Add Trust Relationships to an Existing Role procedure.