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.
Considerations
Before you enable Encryption at Rest using AWS KMS over PrivateLink, review the following use cases, benefits, limitations, and prerequisites.
Use Case
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.
Benefits
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.
Limitations
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.
Prerequisites
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:
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.
Procedures
Enable Role-Based Access for Your Encryption Key for a Project
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 Advanced under the Security heading.
The Advanced page displays.
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.
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" ] } ] }
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.
Log in to your AWS Management Console.
Navigate to the Identity and Access Management (IAM) service.
Select Roles from the left-side navigation.
Click on the existing IAM role you wish to use for Atlas access from the list of roles.
Select the Trust Relationships tab.
Click the Edit trust relationship button.
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. TheExternalId
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>" } } } ] } 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.
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.
Switch to Role-Based Access for Your Encryption Key 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.
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 Advanced under the Security heading.
The Advanced page displays.
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.
To update your encryption key management with the Atlas Administration API, use the same steps outlined in the above procedure.
Enable and Set up Private Endpoint Connections for a Project
To enable private networking and set up a private endpoint in your AWS KMS, you must do the following:
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 Advanced under the Security heading.
The Advanced page displays.
Go to the Private Endpoints for AWS KMS page.
On the Advanced page, in the Encryption at Rest using your Key Management section, do the following steps:
Expand Network Settings for your AWS KMS if it's collapsed.
Toggle on the button next to Require Private Networking.
Click Set up.
The Set Up Private Networking for AWS page displays.
Replicate your encryption key in each region.
Sign into your AWS KMS dashboard.
In the Atlas UI, click Copy to save your customer master key ID.
In your AWS KMS dashboard, replicate your key in all desired regions. To learn more, see the AWS documentation.
In the Atlas UI, click Continue
Specify the AWS regions where you want to create private endpoints.
Select the AWS regions from the dropdown.
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. |
Enable private networking.
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 } }'
Create a private endpoint.
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.
Check the status of your request.
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.
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:
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.
If it's not already displayed, click Clusters in the sidebar.
The Clusters page displays.
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 (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.
Disable Customer-Managed Keys for a Project
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.
Create New Endpoints for a Project
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.
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 Advanced under the Security heading.
The Advanced page displays.
Go to the Private Endpoints for AWS KMS page.
On the Advanced page, in the Encryption at Rest using your Key Management section, perform the following actions:
Expand Network Settings for your AWS KMS if it's collapsed.
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.
Specify the regions where you want to create private endpoints.
Select the AWS regions from the dropdown.
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. |
Create a private endpoint.
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.
Check the status of your request.
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. |
Reject or Remove Private Endpoint Connection
You can remove private endpoint connections from the Atlas UI and the Atlas Administration API.
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 Advanced under the Security heading.
The Advanced page displays.
Go to the Private Endpoints for AWS KMS page.
On the Advanced page, in the Encryption at Rest using your Key Management section, perform the following actions:
Expand Network Settings for your AWS KMS if it's collapsed.
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.
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.
View Private Endpoints and their Statuses
You can view the private endpoints in the various regions and their statuses from the Atlas UI and the Atlas Administration API.
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 Advanced under the Security heading.
The Advanced page displays.
Go to the Private Endpoints for AWS KMS page.
On the Advanced page, in the Encryption at Rest using your Key Management section, perform the following actions:
Expand Network Settings for your AWS KMS if it's collapsed.
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. |
Disable Private Endpoint Connections for a Project
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.
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 Advanced under the Security heading.
The Advanced page displays.
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 } }
Related Topics
To enable Encryption at Rest using your Key Management when deploying an Atlas cluster, see Manage Your Own Encryption Keys.
To enable Encryption at Rest using your Key Management for an existing Atlas cluster, see Enable Encryption at Rest.
To learn more about Encryption at Rest using your Key Management in Atlas, see Encryption at Rest using Customer Key Management.
To learn more about MongoDB Encryption at Rest, see 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.