Docs Menu
Docs Home
/
MongoDB Atlas
/ / /

Manage Customer Keys with AWS Over Private Endpoints

On this page

  • Considerations
  • Use Case
  • Benefits
  • Limitations
  • Prerequisites
  • Procedures
  • Enable Role-Based Access for Your Encryption Key for a Project
  • Switch to Role-Based Access for Your Encryption Key for a Project
  • Enable and Set up Private Endpoint Connections for a Project
  • Enable Customer Key Management for an Atlas Cluster
  • Disable Customer-Managed Keys for a Project
  • Create New Endpoints for a Project
  • Reject or Remove Private Endpoint Connection
  • View Private Endpoints and their Statuses
  • Disable Private Endpoint Connections for a Project
  • Related Topics

In addition to encrypting your data at rest in Atlas with the customer-managed keys (CMK) that you create, own, and manage in your AWS KMS, you can add another layer of security by configuring all traffic to your AWS KMS to use AWS PrivateLink.

This page describes how to set up AWS PrivateLink in your AWS KMS to ensure that all traffic between Atlas and your AWS KMS takes place over AWS's private network interfaces.

Before you enable Encryption at Rest using AWS KMS over PrivateLink, review the following use cases, benefits, limitations, and prerequisites.

Suppose your Atlas deployment is on a single cloud service provider. You now have a requirement that all access to your AWS KMS occurs over your cloud provider's private networking infrastructure. This page walks you through the steps to enable private endpoint connections for your Atlas project.

You can configure Encryption at Rest with AWS KMS over private networking. This configuration allows all traffic to your AWS KMS to pass through a set of private endpoints and avoids exposing your AWS KMS to the public internet or public IP addresses. This configuration also eliminates the need to maintain allowed IP addresses while enhancing data security by keeping all AWS KMS traffic within AWS's private network.

  • Atlas supports Encryption at Rest using AWS KMS over private networking only for single-cloud deployments.

  • Atlas supports Encryption at Rest using AWS KMS over private networking only for projects in the ACTIVE state.

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

  • Use an M10 or larger cluster.

  • Have an AWS IAM role with sufficient privileges. Atlas must have permission to perform the following actions with your key:

    • DescribeKey

    • Encrypt

    • Decrypt

    Note

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

    • Add a key policy statement under the AWS KMS key 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 AWS KMS key (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 AWS KMS key ID field.

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

    Atlas uses the same IAM role and AWS KMS key 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. You must include the IP addresses in your managed IAM role policy by configuring IP address condition operators in your policy document. If the node IP addresses change, you must update your configuration to avoid connectivity interruptions.

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

2
3

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.

4

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.

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"
]
}
]
}
5
6
  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.

1

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.

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

3

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.

4

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

Example

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>"
}
}'

After you enable role-based access for your encryption key for your project, enable private endpoint connections for your project by following Enable and Set up Private Endpoint Connections for a Project.

AWS requires the use of IAM roles instead of IAM users for managing access to AWS KMS encryption keys within Atlas. If you initially configured your project to use IAM user credentials to access AWS KMS keys, switch to role-based access using the following procedure.

Important

If you switch your encryption keys to role-based access, you can't undo the role-based access configuration and revert to credentials-based access for encryption keys on that project.

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

2
3
4

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.

To update your encryption key management with the Atlas Administration API, use the same steps outlined in the above procedure.

To enable private networking and set up a private endpoint in your AWS KMS, you must do the following:

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

2

On the Advanced page, in the Encryption at Rest using your Key Management section, do the following steps:

  1. Expand Network Settings for your AWS KMS if it's collapsed.

  2. Toggle on the button next to Require Private Networking.

  3. Click Set up.

    The Set Up Private Networking for AWS page displays.

3
  1. Sign into your AWS KMS dashboard.

  2. In the Atlas UI, click Copy to save your customer master key ID.

  3. In your AWS KMS dashboard, replicate your key in all desired regions. To learn more, see the AWS documentation.

  4. In the Atlas UI, click Continue

4
  1. Select the AWS regions from the dropdown.

  2. Click Continue.

Atlas automatically creates private endpoints in these regions to allow you to connect by using private networking.

Atlas can take up to three minutes to reflect the current status of your private endpoint. The private endpoint can have one of the following statuses:

ACTIVE

Indicates that the private endpoint is approved and Atlas can or is using it.

FAILED

Indicates that the private endpoint creation failed.

5
1

Send a PATCH request to the encryptionAtRest endpoint and set the requirePrivateNetworking flag value to true.

To learn more about the required parameters, see Update Configuration for Encryption at Rest using Customer-Managed Keys for One Project.

Example

curl --user "{PUBLIC-KEY}:{PRIVATE-KEY}" --digest \
--header "Accept: application/vnd.atlas.2024-11-13+json" \
--header "Content-Type: application/vnd.atlas.2024-11-13+json" \
--include \
--request PATCH "https://cloud.mongodb.com/api/atlas/v2/groups/{groupId}/encryptionAtRest/" \
--data '
{
"awsKms": {
"accessKeyID": "019dd98d94b4bb778e7552e4",
"customerMasterKeyID": "string",
"enabled": true,
"region": "US_EAST_1",
"roleId": "32b6e34b3d91647abb20e7b8",
"secretAccessKey": "string",
"requirePrivateNetworking": true
}
}'
2

Use the Atlas Administration API to create a private endpoint to communicate with your AWS KMS.

Send a POST request to the encryptionAtRest endpoint with the AWS region that you want Atlas to create the private endpoint in. You must send a separate request for each region that you want Atlas to create a private endpoint in.

Example

curl --user "{PUBLIC-KEY}:{PRIVATE-KEY}" --digest \
--header "Accept: application/vnd.atlas.2024-11-13+json" \
--header "Content-Type: application/vnd.atlas.2024-11-13+json" \
--include \
--request POST "https://cloud.mongodb.com/api/atlas/v2/groups/{groupId}/encryptionAtRest/AWS/privateEndpoints" \
--data '
{
"regionName": "US_EAST_1"
}'

After you create the private endpoint, the following restrictions apply:

  • Atlas creates all new clusters only in the regions with approved private endpoints.

  • Atlas deploys additional nodes for existing clusters only in the regions with approved private endpoints.

3

To check the status of the private endpoint, send a GET request to the encryptionAtRest endpoint.

Example

curl --user "{PUBLIC-KEY}:{PRIVATE-KEY}" --digest \
--header "Accept: application/vnd.atlas.2024-11-13+json" \
--header "Content-Type: application/vnd.atlas.2024-11-13+json" \
--include \
--request GET "https://cloud.mongodb.com/api/atlas/v2/groups/{groupId}/encryptionAtRest/AWS/privateEndpoints"
{
"links": [
{
"href": "https://cloud.mongodb.com/api/atlas",
"rel": "self"
}
],
"results": [
{
"cloudProvider": "AWS",
"id": "24-hexadecimal-digit-string",
"privateEndpointConnectionName": "string",
"regionName": "US_EAST_1",
"status": "INITIATING",
}
],
"totalCount": 1
}

Atlas can take up to three minutes to reflect the current status of your private endpoint. The private endpoint can have one of the following statuses:

ACTIVE

Indicates that the private endpoint is approved and Atlas can or is using it.

FAILED

Indicates that the private endpoint creation failed.

After you enable customer key management for your project and set up private endpoints, enable customer key management for each Atlas cluster in your project by following Enable Customer Key Management for an Atlas Cluster.

After you Enable Role-Based Access for 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's not already displayed, select the organization that contains your desired project from the Organizations menu in the navigation bar.

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

  3. If it's not already displayed, click Clusters in the sidebar.

    The Clusters page displays.

2

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

3
  1. Expand the Additional Settings panel.

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

  3. Verify the status of the Require Private Networking setting for your cluster.

    If you configured Encryption at Rest Using CMK (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
  1. Click Review Changes.

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

To disable CMK for a project, you must first remove all private endpoints associated with the project, regardless of their state. Atlas displays an error if you attempt to disable CMK for a project that is associated with active private endpoints.

After you remove all private endpoints for a project, you must disable customer key management on each cluster in the project before you disable the feature for the project.

Warning

Do not disable or delete any AWS KMS keys that any cluster in your Atlas project uses before you have disabled customer key management within the Atlas project. If Atlas can't access an AWS KMS key, any data that the key encrypted becomes inaccessible.

After you enable and set up private endpoint connections for your project, you can add additional endpoints at anytime from the Atlas UI and the Atlas Administration API.

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

2

On the Advanced page, in the Encryption at Rest using your Key Management section, perform the following actions:

  1. Expand Network Settings for your AWS KMS if it's collapsed.

  2. Click Manage.

    The Private Endpoints for AWS KMS page displays the regions, endpoint name, status of the private endpoints for your Atlas clusters, and the actions you can take on the private endpoints.

3
4
  1. Select the AWS regions from the dropdown.

  2. Click Continue.

Atlas automatically creates private endpoints in these regions to allow you to connect by using private networking.

Atlas can take up to three minutes to reflect the current status of your private endpoint. The private endpoint can have one of the following statuses:

ACTIVE

Indicates that the private endpoint is approved and Atlas can or is using it.

FAILED

Indicates that the private endpoint creation failed.

5
1

Use the Atlas Administration API to create a private endpoint to communicate with your AWS KMS.

Send a POST request to the encryptionAtRest endpoint with the AWS region in which you want Atlas to create the private endpoint. You must send a separate request for each region in which you want Atlas to create a private endpoint.

Example

curl --user "{PUBLIC-KEY}:{PRIVATE-KEY}" --digest \
--header "Accept: application/vnd.atlas.2024-11-13+json" \
--header "Content-Type: application/vnd.atlas.2024-11-13+json" \
--include \
--request POST "https://cloud.mongodb.com/api/atlas/v2/groups/{groupId}/encryptionAtRest/AWS/privateEndpoints" \
--data '
{
"regionName": "US_EAST_1"
}'

After you create the private endpoint, the following restrictions apply:

  • Atlas creates all new clusters only in the regions with approved private endpoints.

  • Atlas deploys additional nodes for existing clusters only in the regions with approved private endpoints.

2

To check the status of the private endpoint, send a GET request to the encryptionAtRest endpoint.

Example

curl --user "{PUBLIC-KEY}:{PRIVATE-KEY}" --digest \
--header "Accept: application/vnd.atlas.2024-11-13+json" \
--header "Content-Type: application/vnd.atlas.2024-11-13+json" \
--include \
--request GET "https://cloud.mongodb.com/api/atlas/v2/groups/{groupId}/encryptionAtRest/AWS/privateEndpoints"
{
"links": [
{
"href": "https://cloud.mongodb.com/api/atlas",
"rel": "self"
}
],
"results": [
{
"cloudProvider": "AWS",
"id": "24-hexadecimal-digit-string",
"privateEndpointConnectionName": "string",
"regionName": "US_EAST_1",
"status": "INITIATING",
}
],
"totalCount": 1
}

Atlas can take up to three minutes to reflect the current status of your private endpoint. The private endpoint can have one of the following statuses:

ACTIVE

Indicates that the private endpoint is approved and Atlas can or is using it.

FAILED

Indicates that the private endpoint creation failed.

You can remove private endpoint connections from the Atlas UI and the Atlas Administration API.

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

2

On the Advanced page, in the Encryption at Rest using your Key Management section, perform the following actions:

  1. Expand Network Settings for your AWS KMS if it's collapsed.

  2. Click Manage.

    The Private Endpoints for AWS KMS page displays the regions, endpoint name, status of the private endpoints for your Atlas clusters, and the actions you can take on the private endpoints.

3
  1. Click the icon in the Actions column for the private endpoint that you want to remove.

  2. Click Delete to confirm deletion of the private endpoint.

To successfully remove a private endpoint, send a DELETE request to the Atlas Administration API endpoint and specify the ID of the project and of the private endpoint that you want to delete. You can retrieve the ID of the private endpoint that you want to delete by sending a GET request to the Atlas Administration API Return One Private Endpoint Service for One Provider endpoint.

Example

curl --user "{PUBLIC-KEY}:{PRIVATE-KEY}" --digest \
--header "Accept: application/vnd.atlas.2024-10-23+json" \\ or a different version of the Atlas Admin API
--header "Content-Type: application/json" \
--include \
--request DELETE "https://cloud.mongodb.com/api/atlas/v2/groups/{groupId}/encryptionAtRest/AWS/ privateEndpoints/{endpointId}" \
--data '
{
"cloudProvider": "AWS",
"regions": [
"string"
]
}'

When you use the Atlas Administration API to delete a private endpoint, the private endpoint transitions to the DELETING status while Atlas deletes the private endpoint.

If you remove or reject an active private endpoint from the AWS UI, Atlas automatically attempts to recreate a new private endpoint in the same region.

While Atlas attempts to create a new private endpoint, the status of the private endpoint that you rejected or removed transitions to PENDING_RECREATION and the new endpoint that Atlas attempts to create is in INITIATING state. You must approve the new private endpoint after it is created.

You can view the private endpoints in the various regions and their statuses from the Atlas UI and the Atlas Administration API.

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

2

On the Advanced page, in the Encryption at Rest using your Key Management section, perform the following actions:

  1. Expand Network Settings for your AWS KMS if it's collapsed.

  2. Click Manage.

    The Private Endpoints for AWS KMS page displays the regions, endpoint name, status of the private endpoints for your Atlas clusters, and the actions you can take on the private endpoints.

You can view the private endpoint and their statuses from the Atlas Administration API by sending a GET request to the Atlas Administration API encryptionAtRest get all endpoint or get one endpoint, for which you must specify the ID of the private endpoint in the path.

Example

Return All Private Endpoints for One Project

curl --user "{PUBLIC-KEY}:{PRIVATE-KEY}" --digest \
--header "Accept: application/vnd.atlas.2024-10-23+json" \\ or a different version of the Atlas Admin API
--header "Content-Type: application/json" \
--include \
--request GET "https://cloud.mongodb.com/api/atlas/v2/groups/{groupId}/encryptionAtRest/AWS/privateEndpoints/"

Each private endpoint can be in one of the following statuses:

ACTIVE

Indicates that the private endpoint is approved and Atlas can or is using it.

FAILED

Indicates that the private endpoint creation failed.

To disable private endpoint connections for a project, you must first remove all private endpoints, associated with the project, regardless of their state. Atlas doesn't disable private endpoint connections for a project if the project is associated with active private endpoints.

After you remove all private endpoints for a project, you can disable private endpoint connections for the project by using the Atlas UI and the Atlas Administration API.

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

2
  1. Under Encryption at Rest using your Key Management, select AWS KMS.

  2. Under Network Settings, toggle the button next to Require Private Networking to Off.

  3. Click Save.

To disable a private endpoint connection, send a PATCH request to the endpoint with the requirePrivateNetworking boolean flag value set to false.

Example

{
"awsKms": {
"accessKeyID": "019dd98d94b4bb778e7552e4",
"customerMasterKeyID": "string",
"enabled": true,
"region": "US_EAST_1",
"roleId": "32b6e34b3d91647abb20e7b8",
"secretAccessKey": "string"
"requirePrivateNetworking": false
}
}

Back

Configure Access Over Public Network