Navigation

Enable and Configure Encryption at Rest for a Project

Note

Groups and projects are synonymous terms. Your {GROUP-ID} is the same as your project ID. For existing groups, your group/project ID remains the same. The resource and corresponding endpoints use the term groups.

Feature unavailable in Free and Shared Tier Clusters

This feature is not available for M0 (Free Tier), M2, and M5 clusters. To learn more about which features are unavailable, see Atlas M0 (Free Tier), M2, and M5 Limitations.

Overview

Enables, disables, and configures Encryption at Rest for an Atlas project with one of the following providers:

After configuring at least one Encryption at Rest provider for the Atlas project, Project Owners can enable Encryption at Rest for each Atlas cluster for which they require encryption. The Encryption at Rest provider does not have to match the cluster cloud service provider.

Atlas does not automatically rotate user-managed encryption keys. Defer to your preferred Encryption at Rest provider’s documentation and guidance for best practices on key rotation. Atlas automatically creates a 365-day key rotation alert when you configure Encryption at Rest using your Key Management in an Atlas project.

See Encryption at Rest for more information, including prerequisites and restrictions.

The Atlas API uses HTTP Digest Authentication. Provide your Atlas username and API key as the username and password when constructing the HTTP request.

For complete documentation on configuring API access for an Atlas project, see Configure Atlas API Access.

Base URL: https://cloud.mongodb.com/api/atlas/v1.0

Syntax

PATCH /groups/{GROUP-ID}/encryptionAtRest

Request Path Parameters

Path Element Required/Optional Description
GROUP-ID Required. The unique identifier for the project.

Request Query Parameters

The following query parameters are optional:

Name Type Description Default
pretty boolean Displays response in a prettyprint format. false
envelope boolean Specifies whether or not to wrap the response in an envelope. false

Request Body Parameters

The required request body parameters depend on whether Encryption at Rest is currently enabled:

  • If Encryption at Rest is not enabled, all of the parameters for the desired encryption provider are required.
    • If you want to use AWS KMS, all the fields in the awsKms document are required.
    • If you want to use Azure Key Vault, all the fields in the azureKeyVault document are required.
    • If you want to use Google Cloud KMS, all the fields in the googleCloudKms document are required.
  • If Encryption at Rest is enabled, administrators can update the configuration by passing only the changed fields for the awsKms, azureKeyVault, or googleCloudKms document to this endpoint.

AWS KMS Request Body Parameters

Name Type Description
awsKms object Specifies AWS KMS configuration details and whether Encryption at Rest is enabled for an Atlas project.
awsKms.accessKeyID string The IAM access key ID with permissions to access the customer master key specified by customerMasterKeyID.
awsKms.customerMasterKeyID string The AWS customer master key used to encrypt and decrypt the MongoDB master keys.
awsKms.enabled boolean Specifies whether Encryption at Rest is enabled for an Atlas project. To disable Encryption at Rest, pass only this parameter with a value of false. When you disable Encryption at Rest, Atlas also removes the configuration details.
awsKms.region string

The AWS region in which the AWS customer master key exists:

  • CA_CENTRAL_1
  • US_EAST_1
  • US_EAST_2
  • US_WEST_1
  • US_WEST_2
  • SA_EAST_1
  • AP_NORTHEAST_1
  • AP_NORTHEAST_2
  • AP_SOUTH_1
  • AP_SOUTHEAST_1
  • AP_SOUTHEAST_2
  • EU_CENTRAL_1
  • EU_WEST_1
  • EU_WEST_2
  • EU_WEST_3
awsKms.secretAccessKey string The IAM secret access key with permissions to access the customer master key specified by customerMasterKeyID.

Azure Key Vault Request Body Parameters

Name Type Description
azureKeyVault object Specifies Azure Key Vault configuration details and whether Encryption at Rest is enabled for an Atlas project.
azureKeyVault.azureEnvironment string

The Azure environment where the Azure account credentials reside. Valid values are the following:

  • AZURE
  • AZURE_CHINA
  • AZURE_GERMANY
azureKeyVault.clientID string The client ID, also known as the application ID, for an Azure application associated with the Azure AD tenant.
azureKeyVault.enabled boolean Specifies whether Encryption at Rest is enabled for an Atlas project. To disable Encryption at Rest, pass only this parameter with a value of false. When you disable Encryption at Rest, Atlas also removes the configuration details.
azureKeyVault.keyIdentifier string The unique identifier of a key in an Azure Key Vault.
azureKeyVault.keyVaultName string The name of an Azure Key Vault containing your key.
azureKeyVault.resourceGroupName string The name of the Azure Resource group that contains an Azure Key Vault.
azureKeyVault.secret string The secret associated with the Azure Key Vault specified by azureKeyVault.tenantID.
azureKeyVault.subscriptionID string The unique identifier associated with an Azure subscription.
azureKeyVault.tenantID string The unique identifier for an Azure AD tenant within an Azure subscription.

Google Cloud KMS Request Body Parameters

Name Type Description
googleCloudKms object Specifies GCP KMS configuration details and whether Encryption at Rest is enabled for an Atlas project.
googleCloudKms.enabled boolean Specifies whether Encryption at Rest is enabled for an Atlas project. To disable Encryption at Rest, pass only this parameter with a value of false. When you disable Encryption at Rest, Atlas also removes the configuration details.
googleCloudKms.serviceAccountKey string

String-formatted JSON object containing GCP KMS credentials from your GCP account.

Note

Your Service Account Key is a JSON object, but it must be formatted as a string for API call purposes.

For more information, see the GCP documentation.

googleCloudKms.keyVersionResourceID string The Key Version Resource ID from your GCP account.

Response

AWS KMS Response

Name Type Description
awsKms object Specifies whether Encryption at Rest is enabled for an Atlas project and the AWS KMS configuration details.
awsKms.accessKeyID string The IAM access key ID with permissions to access the customer master key specified by customerMasterKeyID.
awsKms.customerMasterKeyID string The AWS customer master key used to encrypt and decrypt the MongoDB master keys.
awsKms.enabled boolean Specifies whether Encryption at Rest is enabled for an Atlas project.
awsKms.region string The AWS region in which the AWS customer master key exists.

Azure Key Vault Response

Name Type Description
azureKeyVault object Specifies Azure Key Vault configuration details and whether Encryption at Rest is enabled for an Atlas project.
azureKeyVault.azureEnvironment string The Azure environment where the Azure account credentials reside.
azureKeyVault.clientID string The client ID, also known as the application ID, for an Azure application associated with the Azure AD tenant.
azureKeyVault.enabled boolean Specifies whether Encryption at Rest is enabled for an Atlas project and the Azure Key Vault configuration details.
azureKeyVault.keyIdentifier string The unique identifier of a key in an Azure Key Vault.
azureKeyVault.keyVaultName string The name of an Azure Key Vault containing your key.
azureKeyVault.resourceGroupName string The name of the Azure Resource group that contains an Azure Key Vault.
azureKeyVault.subscriptionID string The unique identifier associated with an Azure subscription.
azureKeyVault.tenantID string Unique identifier for an Azure AD tenant within an Azure subscription.

Google Cloud KMS Response

Name Type Description
googleCloudKms.enabled boolean Specifies whether Encryption at Rest is enabled for an Atlas project using Google Cloud KMS.
googleCloudKms.keyVersionResourceID string Key Version Resource ID for your Google Cloud KMS.

Examples

AWS KMS Examples

Example Request: Enable Encryption at Rest with AWS KMS

The following example enables and configures Encryption at Rest for an Atlas project using AWS KMS:

curl -X PATCH -i -u "username:apiKey" --digest \
 --header "Accept: application/json" \
 --header "Content-Type: application/json" \
 "https://cloud.mongodb.com/api/atlas/v1.0/groups/{GROUP-ID}/encryptionAtRest?pretty=true" \
 --data '
 {
   "awsKms": {
     "enabled": true,
     "accessKeyID" : "AKIAIOSFODNN7EXAMPLE",
     "secretAccessKey": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
     "customerMasterKeyID" : "030gce02-586d-48d2-a966-05ea954fde0g",
     "region" : "US_EAST_1"
   }
 }'

Example Response: Enable Encryption at Rest with AWS KMS

{
  "awsKms" : {
    "accessKeyID" : "AKIAIOSFODNN7EXAMPLE",
    "customerMasterKeyID" : "030gce02-586d-48d2-a966-05ea954fde0g",
    "enabled" : true,
    "region" : "US_EAST_1"
  },
  "azureKeyVault" : {
    "clientID" : null,
    "enabled" : false,
    "keyIdentifier" : null,
    "keyVaultName" : null,
    "resourceGroupName" : null,
    "subscriptionID" : null,
    "tenantID" : null
  }
}

Azure Key Vault Examples

Example Request: Enable Encryption at Rest with Azure Key Vault

The following example enables and configures Encryption at Rest for an Atlas project using Azure Key Vault:

curl -X PATCH --digest -i -u "{username}:{apiKey}" --header "Content-Type: application/json" \
 "https://cloud.mongodb.com/api/atlas/v1.0/groups/6cbbae2187d9d675e009g35f/encryptionAtRest?pretty=true" \
 --data '
 {
   "azureKeyVault" : {
     "enabled" : true,
     "clientID" : "g54f9e2-89e3-40fd-8188-EXAMPLEID",
     "azureEnvironment" : "AZURE",
     "subscriptionID" : "0ec944e3-g725-44f9-a147-EXAMPLEID",
     "resourceGroupName" : "ExampleRGName",
     "keyVaultName" : "EXAMPLEKeyVault",
     "keyIdentifier" : "https://EXAMPLEKeyVault.vault.azure.net/keys/EXAMPLEKey/d891821e3d364e9eb88fbd3d11807b86",
     "secret" : "EXAMPLESECRET",
     "tenantID" : "e8e4b6ba-ff32-4c88-a9af-EXAMPLEID"
   }
 }'

Example Response: Enable Encryption at Rest with Azure Key Vault

{
  "awsKms" : {
    "accessKeyID" : null,
    "customerMasterKeyID" : null,
    "enabled" : false,
    "region" : null
  },
  "azureKeyVault" : {
    "enabled" : true,
    "clientID" : "g54f9e2-89e3-40fd-8188-EXAMPLEID",
    "azureEnvironment" : "AZURE",
    "subscriptionID" : "0ec944e3-g725-44f9-a147-EXAMPLEID",
    "resourceGroupName" : "ExampleRGName",
    "keyVaultName" : "EXAMPLEKeyVault",
    "keyIdentifier" : "https://EXAMPLEKeyVault.vault.azure.net/keys/EXAMPLEKey/d891821e3d364e9eb88fbd3d11807b86",
    "tenantID" : "e8e4b6ba-ff32-4c88-a9af-dc17efegdf63"
  }
}

Google Cloud KMS Examples

Example Request: Enable Encryption at Rest with GCP KMS

The following example enables and configures Encryption at Rest for an Atlas project using Google Cloud Platform KMS.

Note

The serviceAccountKey JSON object must be formatted as a string for API call purposes.

curl -X PATCH --digest -i -u "{username}:{apiKey}" --header "Content-Type: application/json" \
 "https://cloud.mongodb.com/api/atlas/v1.0/groups/6cbbae2187d675e009g35f/encryptionAtRest?pretty=true" \
 --data '
 {
   "googleCloudKms" : {
     "enabled" : true,
     "serviceAccountKey":
        "{\"type\": \"service_account\",\"project_id\": \"my-project-common-0\",\"private_key_id\": \"e120598ea4f88249469fcdd75a9a785c1bb3\",\"private_key\": \"-----BEGIN PRIVATE KEY-----\\nMIIEuwIBA(truncated)SfecnS0mT94D9\\n-----END PRIVATE KEY-----\\n\",\"client_email\": \"my-email-kms-0@my-project-common-0.iam.gserviceaccount.com\",\"client_id\": \"10180967717292066\",\"auth_uri\": \"https://accounts.google.com/o/oauth2/auth\",\"token_uri\": \"https://accounts.google.com/o/oauth2/token\",\"auth_provider_x509_cert_url\": \"https://www.googleapis.com/oauth2/v1/certs\",\"client_x509_cert_url\": \"https://www.googleapis.com/robot/v1/metadata/x509/my-email-kms-0%40my-project-common-0.iam.gserviceaccount.com\"}",
     "keyVersionResourceID": "projects/my-project-common-0/locations/us-east4/keyRings/my-key-ring-0/cryptoKeys/my-key-0/cryptoKeyVersions/1"
    }
  }'

Example Response: Enable Encryption at Rest with GCP KMS

{
  "awsKms" : {
    "accessKeyID" : null,
    "customerMasterKeyID" : null,
    "enabled" : false,
    "region" : null
  },
  "azureKeyVault" : {
    "clientID" : null,
    "enabled" : false,
    "keyIdentifier" : null,
    "keyVaultName" : null,
    "resourceGroupName" : null,
    "subscriptionID" : null,
    "tenantID" : null
  },
  "googleCloudKms" : {
    "enabled": true,
    "keyVersionResourceID" : "projects/my-project-common-0/locations/us-east4/keyRings/my-key-ring-0/cryptoKeys/my-key-0/cryptoKeyVersions/1"
  }
}

Example Request: Disable Encryption at Rest

The following example disables Encryption at Rest for an Atlas project:

curl -X PATCH -i -u "username:apiKey" --digest --header "Content-Type: application/json" \
 "https://cloud.mongodb.com/api/atlas/v1.0/groups/{GROUP-ID}/encryptionAtRest?pretty=true" \
 --data '
 {
   "awsKms": {
     "enabled" : false
   }
 }'

Example Response: Disable Encryption at Rest

{
  "awsKms" : {
    "accessKeyID" : null,
    "customerMasterKeyID" : null,
    "enabled" : false,
    "region" : null
  },
  "azureKeyVault" : {
    "clientID" : null,
    "enabled" : false,
    "keyIdentifier" : null,
    "keyVaultName" : null,
    "resourceGroupName" : null,
    "subscriptionID" : null,
    "tenantID" : null
  },
  "googleCloudKms" : {
    "enabled": false,
    "keyVersionResourceID" : null
  }
}