> For the complete MongoDB documentation index, see www.mongodb.com/docs/llms.txt # Manage Customer Keys with Azure Key Vault **Note:** This feature is not available for any of the following deployments: - Free clusters - Flex clusters To learn more, see [Limits.](https://www.mongodb.com/docs/atlas/reference/limitations.md#std-label-limits) You can use a customer-managed key (CMK) from Azure Key Vault (AKV) to further encrypt your data at rest in Atlas. You can also configure all traffic to your AKV (Azure Key Vault) to use Azure Private Link. **Note:** The MongoDB Atlas Shared Responsibility Model defines the complementary duties of MongoDB and its customers in maintaining a secure and resilient data environment. Under this framework, MongoDB manages the security and operational integrity of the underlying platform, while customers are responsible for the configuration, management, and data policies of their specific deployments. For a detailed breakdown of ownership across security and operational excellence, see [Shared Responsibility Model.](https://www.mongodb.com/resources/products/fundamentals/shared-responsibility) Atlas uses your Azure Key Vault CMK (customer-managed key) to encrypt and decrypt your MongoDB Master Keys. These MongoDB Master Keys are used to encrypt cluster database files and [cloud providers snapshots](https://www.mongodb.com/docs/atlas/backup/cloud-backup/overview.md#std-label-backup-cloud-provider). To learn more about how Atlas uses CMK (customer-managed key)s for encryption, see [About Customer-Managed Keys with Azure Key Vault.](https://www.mongodb.com/docs/atlas/security-azure-kms.md#std-label-enable-cmk-akv) When you use your own cloud provider KMS (Key Management Service), Atlas automatically rotates MongoDB Master Keys at least every 90 days. Your key rotation will begin during a [maintenance window](https://www.mongodb.com/docs/atlas/tutorial/cluster-maintenance-window.md#std-label-configure-maintenance-window), if you have one configured. Deferring maintenance (either manually or automatically) may cause the key to be rotated past the 90-day mark. Keys are rotated on a rolling basis and the process does not require the data to be rewritten. **Important:** Azure (Microsoft Azure) limits Client Secret lifetime for CMK (customer-managed key)s to two years. Atlas can't access a CMK (customer-managed key) once the Client Secret expires. Therefore, rotate your Client Secrets before its expiration to prevent loss of cluster availability. To learn about a secretless option, see [Manage Customer Keys with Azure Key Vault (Secretless).](https://www.mongodb.com/docs/atlas/security/azure-kms-secretless.md#std-label-security-azure-kms-secretless) This page covers configuring customer key management using AKV (Azure Key Vault) on your Atlas project. You can also use the Atlas Administration API to automatically set up Azure Private Link in your AKV (Azure Key Vault) to ensure that all traffic between Atlas and AKV (Azure Key Vault) take place over Azure (Microsoft Azure)s private network interfaces. **Note: Atlas Infinite** Azure Key Vault isn't available for [Atlas Infinite](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-Atlas-Infinite) during public preview. Atlas Infinite supports customer-managed keys only through [AWS KMS](https://www.mongodb.com/docs/atlas/security-aws-kms.md#std-label-security-aws-kms) during public preview. To learn how encryption at rest works for Atlas Infinite, see [Atlas Infinite Encryption.](https://www.mongodb.com/docs/atlas/security-encryption-at-rest-overview.md#std-label-atlas-infinite-encryption-at-rest) You must configure customer key management for the Atlas project before enabling it on clusters in that project. ## About Customer-Managed Keys with Azure Key Vault Customer key management in Atlas follows a process called [envelope encryption](https://learn.microsoft.com/en-us/azure/security/fundamentals/encryption-atrest#envelope-encryption-with-a-key-hierarchy). This process creates multiple layers of encryption by encrypting one key with another key. To enable customer key management, Atlas uses the following encryption keys: Customer-managed keys are encryption keys that you create, own, and manage in Azure Key Vault. You create the CMK (customer-managed key) in Azure Key Vault and connect it to Atlas at the [Project](https://www.mongodb.com/docs/atlas/organizations-projects.md#std-label-projects) level. To learn more about the CMK (customer-managed key)s used in Azure Key Vault, see [Azure Documentation](https://learn.microsoft.com/en-us/azure/storage/common/customer-managed-keys-overview). Atlas uses this key only to encrypt the MongoDB Master Keys. Each node in your Atlas cluster creates a MongoDB Master Key. MongoDB Master Keys are encryption keys that a MongoDB Server uses to encrypt the per-database encryption keys. Atlas saves an encrypted copy of the key locally. This key is encrypted with the CMK (customer-managed key) and encrypts the per-database encryption keys. Each node in your Atlas cluster also creates an encryption key per database in your cluster. Atlas uses these keys to read and write data via WiredTiger, which also encrypts and stores these keys. This key is encrypted with the MongoDB Master Key. ### Example Consider the following encryption hierarchy for a three-node replica set. Atlas uses the CMK (customer-managed key) from Azure Key Vault to encrypt a unique MongoDB Master Key for each node in the cluster. Each node also contains three databases, each of which is encrypted with a unique per-database encryption key. When the cluster starts up, Atlas decrypts the MongoDB Master Key by using the CMK (customer-managed key) from Azure Key Vault and supplies this to the MongoDB Server. **Note:** If you revoke Atlas's access to the CMK (customer-managed key), Atlas shuts down the nodes in your cluster and you can't access your data until you restore access to the CMK (customer-managed key). ![Diagram of CMK workflow with AKV and Atlas](/images/azure-kms-cmk-diagram.png) ## What You Need to Know After configuring Atlas to use your AKV (Azure Key Vault) CMK (customer-managed key), learn more [About Rotating Your Azure Key Identifier](https://www.mongodb.com/docs/atlas/security-azure-kms.md#std-label-azure-kms-rotate-key) and [About Azure Key Vault Failover During an Outage.](https://www.mongodb.com/docs/atlas/security-azure-kms.md#std-label-akv-failover) ### About Rotating Your Azure Key Identifier **Note:** This feature is not available for any of the following deployments: - Free clusters - Flex clusters To learn more, see [Limits.](https://www.mongodb.com/docs/atlas/reference/limitations.md#std-label-limits) #### MongoDB Master Key - MongoDB Responsibility When you use your own cloud provider KMS (Key Management Service), Atlas automatically rotates MongoDB Master Keys at least every 90 days. Your key rotation will begin during a [maintenance window](https://www.mongodb.com/docs/atlas/tutorial/cluster-maintenance-window.md#std-label-configure-maintenance-window), if you have one configured. Deferring maintenance (either manually or automatically) may cause the key to be rotated past the 90-day mark. Keys are rotated on a rolling basis and the process does not require the data to be rewritten. #### Rotate your Azure Key ID - Your Responsibility Atlas does *not* automatically rotate the Key Identifier used for Azure Key Vault. Atlas automatically creates an [`encryption key rotation alert`](https://www.mongodb.com/docs/atlas/reference/alert-conditions.md#mongodb-alert-Azure-encryption-key-elapsed-time-since-last-rotation-is-above--n--days) to remind you to rotate your Azure Key Identifier every 90 days by default when you [enable Encryption at Rest](https://www.mongodb.com/docs/atlas/security-azure-kms.md#std-label-security-azure-kms) for an Atlas project. You can [rotate](https://learn.microsoft.com/en-us/azure/container-registry/tutorial-rotate-revoke-customer-managed-keys) CMK (customer-managed key) stored in Azure Key Vault yourself or configure your Azure Key Vault to automatically rotate your keys. If you configure [automatic rotation](https://learn.microsoft.com/en-us/azure/virtual-machines/disk-encryption#automatic-key-rotation-of-customer-managed-keys) in Azure Key Vault, the default time period for rotation is approximately 365 days. If you have already set up an automatic rotation in Azure Key Vault and don't want to receive the Atlas alert to rotate your Azure Key Identifier every 90 days, you can [modify](https://www.mongodb.com/docs/atlas/configure-alerts.md#std-label-configure-alerts) the default alert period to be greater than 365 days. ### About Azure Key Vault Failover During an Outage During a regional outage, your AKV (Azure Key Vault) region might become unavailable. If this happens, Azure (Microsoft Azure) automatically routes incoming Key Vault requests to a pre-assigned secondary region. To learn more, see [Azure Key Vault Failover](https://docs.microsoft.com/en-us/azure/key-vault/general/disaster-recovery-guidance#failover) and [Regional Pairings.](https://docs.microsoft.com/en-us/azure/reliability/cross-region-replication-azure#azure-cross-region-replication-pairings-for-all-geographies) If both regions are down, you can manually migrate your key to a region outside of the regional pairing. To learn more, see [Move a Key Vault across Regions.](https://docs.microsoft.com/en-us/azure/key-vault/general/move-region) **Note:** If you've enabled [Encryption at Rest using Customer Key Management](https://www.mongodb.com/docs/atlas/security-kms-encryption.md#std-label-security-kms-encryption), you can perform encrypt and decrypt operations while at least one node is still available during the outage. Atlas won't shut down your clusters. For certain regions, Azure (Microsoft Azure) doesn't support automatic failover. To learn more, see [Azure documentation.](https://docs.microsoft.com/en-us/azure/key-vault/general/disaster-recovery-guidance) ## Required Access To configure customer key management, you must have [`Project Owner`](https://www.mongodb.com/docs/atlas/reference/user-roles.md#mongodb-authrole-Project-Owner) access to the project. Users with [`Organization Owner`](https://www.mongodb.com/docs/atlas/reference/user-roles.md#mongodb-authrole-Organization-Owner) access must add themselves to the project as a `Project Owner`. You must grant Atlas access to your AKV (Azure Key Vault) using a Permission Model. You can grant access by using a Key Vault Access Policy or Azure (Microsoft Azure) RBAC (Role Based Access Control). Before you grant data-plane permissions, you must first assign the **Reader** role to your service principal. This is required for both permission models (RBAC and Access Policy): ### Tab PowerShell ```powershell New-AzRoleAssignment ` -ObjectId "" ` -RoleDefinitionName "Reader" ` -Scope "/subscriptions//resourceGroups//providers/Microsoft.KeyVault/vaults/" ``` After you assign the **Reader** role, grant data-plane permissions using one of the following permission models: ### Vault Access Policy If you use access policies, do the following in the Azure (Microsoft Azure) UI to grant Atlas access to your AKV (Azure Key Vault). 1. Follow the Azure (Microsoft Azure) [documentation](https://learn.microsoft.com/en-us/azure/role-based-access-control/role-assignments-portal) to grant the `Microsoft.KeyVault/vaults/read` permission to your application in the Access Control (IAM) settings: - When you add a role assignment, select the Key Vault Reader role. - When you select the members, choose the application. 2. In the Access Policies page, create an access policy with the following Key Permissions: | Grant this permission... | To... | | --- | --- | | Get | Read the metadata about the key stored in your AKV (Azure Key Vault). | | Encrypt | Use the keys in your AKV (Azure Key Vault) to encrypt data. | | Decrypt | Use the keys in your AKV (Azure Key Vault) to decrypt data that has been previously encrypted with those keys. | 3. Add the same app as the principal and configure the access policy. 4. Follow the [Azure documentation](https://docs.microsoft.com/en-us/azure/key-vault/keys/quick-create-portal#add-a-key-to-key-vault) to create a new RSA key. Open the key version details and copy the Key Identifier URI, which you need to configure Atlas in the next steps. ## Next Steps You can use a customer-managed key (CMK) from Azure Key Vault (AKV) over a public network or over Azure (Microsoft Azure) Private Endpoints. To learn more, see the following: - [Manage Customer Keys with Azure Key Vault Over Private Endpoints](https://www.mongodb.com/docs/atlas/security/azure-kms-over-private-endpoint.md#std-label-security-azure-kms-pvt-endpoint) - [Manage Customer Keys with Azure Key Vault: Public Network](https://www.mongodb.com/docs/atlas/security/azure-kms-over-public-network.md#std-label-security-azure-kms-public-network) If you use Azure (Microsoft Azure) Private Endpoints, to learn how Azure (Microsoft Azure) resource locks can block private endpoint creation and deletion, see [Azure Resource Locks.](https://www.mongodb.com/docs/atlas/security/azure-kms-over-private-endpoint.md#std-label-azure-kms-pvt-endpoint-resource-locks) **Note:** If you've enabled [Encryption at Rest using Customer Key Management](https://www.mongodb.com/docs/atlas/security-kms-encryption.md#std-label-security-kms-encryption), you can perform encrypt and decrypt operations while at least one node is still available during the outage. ### Enable Customer-Managed Keys for Search Nodes By default, MongoDB and [search processes](https://www.mongodb.com/docs/search/query/query-ref.md#std-label-about-mongot) run on the same nodes. With this architecture, customer-managed encryption applies to your database data, but it does not apply to search indexes. When you enable [dedicated Search Nodes](https://www.mongodb.com/docs/search/deployment/deployment-options.md#std-label-what-is-search-node), search processes run on separate nodes. This allows you to enable [Search Node Data Encryption](https://www.mongodb.com/docs/atlas/security-kms-encryption.md#std-label-enable-search-node-encryption), so you can encrypt both database data and search indexes with the same customer-managed keys for comprehensive encryption coverage. Dedicated Search Nodes are not supported on Atlas Infinite clusters clusters during public preview. **Note:** Database nodes and Search Nodes use different encryption methods with the same customer-managed keys. Database nodes use the [WiredTiger Encrypted Storage Engine](https://www.mongodb.com/docs/manual/core/security-encryption-at-rest/#encrypted-storage-engine), while Search Nodes use encryption at the disk level. **Important:** This feature is available across KMS (Key Management Service) providers.