> For the complete MongoDB documentation index, see www.mongodb.com/docs/llms.txt # Manage Customer Keys with Azure Key Vault (Secretless) **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) Atlas supports secretless authentication for using Azure (Microsoft Azure) Key Vault (AKV (Azure Key Vault)) with Encryption at Rest (EAR). With this model, you don't need to provide Atlas with long-lived static credentials (Tenant ID, Client ID, and Client Secret). Instead, you authorize an Atlas-managed Azure (Microsoft Azure) Service Principal in your Azure (Microsoft Azure) tenant, and Atlas authenticates to AKV (Azure Key Vault) using short-lived OAuth 2.0 access tokens that Azure (Microsoft Azure) Active Directory (Azure (Microsoft Azure) AD) issues. **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) This approach: - Eliminates the need to create, store, and rotate client secrets in Atlas. - Centralizes access control entirely within Azure (Microsoft Azure) using Azure (Microsoft Azure) RBAC or Key Vault access policies. - Preserves existing EAR behavior for your clusters and applications. Only the authentication mechanism changes Secretless EAR relies on Azure (Microsoft Azure) AD and Azure (Microsoft Azure) Key Vault as the security boundary. Atlas doesn't store reusable customer-managed secrets and instead uses Azure (Microsoft Azure)-issued tokens at runtime. Access is enforced using least privilege permissions and you can remove Azure (Microsoft Azure) permissions to revoke them immediately. Atlas uses direct role assignment to an Atlas-managed Service Principal for a simpler, secure authentication model. ## Prerequisites To enable customer-managed keys with AKV (Azure Key Vault) for a MongoDB project, you must have: - An M10 or larger cluster. - The Azure (Microsoft Azure) account, and the encryption key in your AKV (Azure Key Vault). To learn how to configure these Azure components, see the [Azure Documentation.](https://docs.microsoft.com/en-us/azure/index) Atlas uses these resources when enabling encryption at rest for a cluster in the Atlas project. - Permissions in Azure (Microsoft Azure) to: - Register an enterprise Service Principal in your tenant. This prerequisite requires a Microsoft Entra ID role that can add or manage Enterprise Applications. The following built-in roles grant this permission: - Application Developer (least privileged) - Application Administrator - Cloud Application Administrator - Hybrid Identity Administrator - Global Administrator To learn more, see [Quickstart: Add an enterprise application.](https://learn.microsoft.com/en-us/entra/identity/enterprise-apps/add-application-portal) - Access to the Key Vault key using one of the following options: - [Azure RBAC](https://www.mongodb.com/docs/atlas/security/azure-kms-secretless.md#std-label-access-azure-rbac) (at the Key Vault or key scope) - [Key Vault access policies](https://www.mongodb.com/docs/atlas/security/azure-kms-secretless.md#std-label-access-azure-policies) - Project Owner access in Atlas for the project for which you want to enable Encryption at Rest. ## Considerations To use a customer-managed key stored in AKV (Azure Key Vault) for EAR, the Atlas-managed Service Principal must have permission to perform cryptographic operations on the specific Key Vault key. The required key permissions include: - `get` - `encrypt` - `decrypt` You should scope permissions as narrowly as possible and grant them using one of the following options: - [Azure RBAC](https://www.mongodb.com/docs/atlas/security/azure-kms-secretless.md#std-label-access-azure-rbac) (at the Key Vault or key scope) - [Key Vault access policies](https://www.mongodb.com/docs/atlas/security/azure-kms-secretless.md#std-label-access-azure-policies) To learn more, see [Quickstart: Add an enterprise application.](https://learn.microsoft.com/en-us/entra/identity/enterprise-apps/add-application-portal) ## Set Up EAR AKV (Azure Key Vault) Secretless Authentication To configure Encryption at Rest (EAR) with secretless authentication, you must: 1. Create an Atlas-managed Azure (Microsoft Azure) Service Principal. 2. Grant the Service Principal access to your Key Vault key. 3. Configure EAR to use the Service Principal. ### Create an Atlas-managed Azure (Microsoft Azure) Service Principal Create an Azure (Microsoft Azure) Service Principal in your tenant for the Atlas-owned Azure (Microsoft Azure) application and register it with Atlas using the Cloud Provider Access API. Atlas returns a `roleId` that you use when you enable EAR. Atlas uses the following Azure (Microsoft Azure) application identity: ```sh atlasAzureAppId: 9efedfcc-2eca-4b27-a613-0cad1e114cb7 ``` 1. Get your Azure (Microsoft Azure) tenant ID. Run the following command to retrieve the tenant ID for the resource in which the Service Principal will exist: ```sh az account show --query tenantId -o tsv ``` 2. Create or locate the Atlas Service Principal. If a Service Principal already exists for the Atlas application, run the following command to locate it: ```sh az ad sp list --filter "appId eq '9efedfcc-2eca-4b27-a613-0cad1e114cb7'" ``` If it doesn't exist, run the following command to create it: ```sh az ad sp create --id 9efedfcc-2eca-4b27-a613-0cad1e114cb7 ``` If this command returns a permission-denied error, confirm that your Microsoft Entra ID account has one of the roles listed in the [Prerequisites.](https://www.mongodb.com/docs/atlas/security/azure-kms-secretless.md#std-label-azure-kms-secretless-prereqs) From the output, copy the `id` field, which is the Service Principal Object ID that Atlas requires. 3. Register the Service Principal with Atlas. Use the [Cloud Provider Access API:](https://www.mongodb.com/docs/atlas/reference/api-resources-spec/v2/#operation/createCloudProviderAccessRole) **Endpoint:** ```sh POST /api/atlas/v2/groups/{groupId}/cloudProviderAccess ``` **Request body example:** ```sh { "providerName": "AZURE", "tenantId": "", "servicePrincipalId": "", "atlasAzureAppId": "9efedfcc-2eca-4b27-a613-0cad1e114cb7" } ``` Atlas provisions and manages the Service Principal and returns an `id` value, which is the `roleId` required when you [configure EAR.](https://www.mongodb.com/docs/atlas/security/azure-kms-secretless.md#std-label-config-ear-secretless) ### Grant AKV (Azure Key Vault) Permissions Authorize the Atlas-managed Service Principal to perform cryptographic operations on the Key Vault key used for EAR. You can grant access using either Azure RBAC or Key Vault access policies. #### Grant Access Using Azure (Microsoft Azure) RBAC To grant access using Azure (Microsoft Azure) RBAC: 1. Assign the Reader role so Atlas can read Key Vault metadata. Run the following command: ```sh az role assignment create \ --assignee-object-id "$SERVICE_PRINCIPAL_OBJECT_ID" \ --assignee-principal-type ServicePrincipal \ --role "Reader" \ --scope "/subscriptions/$SUBSCRIPTION_ID/resourceGroups/$RESOURCE_GROUP/providers/Microsoft.KeyVault/vaults/$KEY_VAULT_NAME" ``` 2. Assign a cryptographic role such as Key Vault Crypto User. Run the following command: ```sh az role assignment create \ --assignee-object-id "$SERVICE_PRINCIPAL_OBJECT_ID" \ --assignee-principal-type ServicePrincipal \ --role "Key Vault Crypto User" \ --scope "/subscriptions/$SUBSCRIPTION_ID/resourceGroups/$RESOURCE_GROUP/providers/Microsoft.KeyVault/vaults/$KEY_VAULT_NAME" ``` **Note:** You can also use a custom role, as long as it grants equivalent key permissions. #### Grant Access Using Key Vault Access Policies If your Key Vault uses access policies, run the following command to grant key permissions directly: ```sh az keyvault set-policy \ --subscription "$SUBSCRIPTION_ID" \ --resource-group "$RESOURCE_GROUP" \ --name "$KEY_VAULT_NAME" \ --object-id "$SERVICE_PRINCIPAL_OBJECT_ID" \ --key-permissions get encrypt decrypt wrapKey unwrapKey ``` ### Configure Encryption at Rest to Use Secretless Authentication After you register and authorize the Service Principal in Azure (Microsoft Azure), update your EAR configuration with the `roleId` that the [Cloud Provider Access API](https://www.mongodb.com/docs/atlas/reference/api-resources-spec/v2/#operation/createCloudProviderAccessRole) returned. ### Atlas UI 1. 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 Database & Network Access under the Security heading. In the sidebar, click Advanced. The [Advanced](https://cloud.mongodb.com/go?l=https%3A%2F%2Fcloud.mongodb.com%2Fv2%2F%3Cproject%3E%23%2Fsecurity%2Fadvanced) page displays. 2. Toggle the button next to Encryption at Rest using your Key Management to On. 3. Select Azure Key Vault. 4. Configure your authentication method. Atlas supports two authentication methods for AKV (Azure Key Vault): - **Service Principal (Recommended)**: Use an Atlas-managed service principal specific to your project to authenticate to AKV (Azure Key Vault) (secretless authentication covered here). - **Static Credentials**: Provide customer-managed credentials. To learn more, see [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) or [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) 5. Enter the Key Vault Configuration. | Subscription ID | Enter the Subscription ID of the Key Vault. | | --- | --- | | Resource Group Name | Enter the Resource Group name of an Azure Resource Group containing the Key Vault. | | Key Vault Name | Enter the name of the Key Vault. Ensure that the Key Vault has the necessary Access Policies. To learn more, see [Required Access.](https://www.mongodb.com/docs/atlas/security-azure-kms.md#std-label-azure-ear-required-access) | **Note:** You can't modify the AKV (Azure Key Vault) configuration here after you [enable and set up private endpoint connections](https://www.mongodb.com/docs/atlas/security/azure-kms-over-private-endpoint.md#std-label-azure-kms-enable-pvt-endpoint) to your AKV (Azure Key Vault). 6. Enter the Encryption Key. | Key Identifier | Enter the full URL (Uniform Resource Locator) for the key created in the Key Vault. IMPORTANT: The key identifier must be provided in the full [Azure general format:](https://docs.microsoft.com/en-us/azure/key-vault/general/about-keys-secrets-certificates) `https://{keyvault-name}.vault.azure.net/{object-type}/{object-name}` You may append `/{object-version}`. However, we recommend you omit the version to enable automatic resolution to the latest version. | | --- | --- | 7. (Optional) Configure private endpoint connections to your AKV (Azure Key Vault). To learn more, see [Enable and Set up Private Endpoint Connections for a Project](https://www.mongodb.com/docs/atlas/security/azure-kms-over-private-endpoint.md#std-label-azure-kms-enable-pvt-endpoint) 8. Verify the network settings. If you configured Atlas using the Atlas Administration API to communicate with AKV (Azure Key Vault) using Azure Private Link to ensure that all traffic between Atlas and Key Vault takes place over Azure (Microsoft Azure)'s private network interfaces, Atlas sets the Require Private Networking status to Active. If the status is Inactive, you can, optionally, complete the steps to [Enable and Set up Private Endpoint Connections for a Project](https://www.mongodb.com/docs/atlas/security/azure-kms-over-private-endpoint.md#std-label-azure-kms-enable-pvt-endpoint) if you want Atlas to use private endpoint connections for your AKV (Azure Key Vault). 9. Click Save. Atlas displays a banner in the Atlas console during the encryption process. After this update, Atlas authenticates to AKV (Azure Key Vault) using short-lived Azure (Microsoft Azure) AD tokens instead of static credentials. ## Migrate from Static Credentials If your project already uses static credentials (`tenantId`, `clientId`, `secret`), you can migrate without cluster downtime. 1. Create an Atlas-managed Service Principal. 2. Grant Key Vault permissions. 3. Patch the EAR configuration with the new `roleId`. If validation fails, Atlas continues using static credentials. If validation succeeds, Atlas removes the stored static credentials, and the `roleId` becomes the source of truth for authentication. If your cluster uses Private Networking, Atlas validates Key Vault access asynchronously from the data nodes. - Validation is not completed immediately when the `PATCH` request is accepted. - Data nodes validate Key Vault access after the configuration is applied. Before you patch EAR with `roleId`, ensure all Key Vault permissions are correctly configured. Misconfigured access can result in validation failures on data nodes, which may eventually disrupt EAR operations and lead to cluster shutdown. Before you patch EAR, verify that your Service Principal has the required Key Vault permissions. ### Verify Azure RBAC Role Assignments Run the following command: ```sh az role assignment list \ --assignee "$SERVICE_PRINCIPAL_OBJECT_ID" \ --scope "/subscriptions/$SUBSCRIPTION_ID/resourceGroups/$RESOURCE_GROUP/providers/Microsoft.KeyVault/vaults/$KEY_VAULT_NAME" ``` Confirm the assigned role grants key permissions such as `get`, `encrypt`, and `decrypt`. ### Verify Key Vault Access Policies Run the following command: ```sh az keyvault show \ --name "$KEY_VAULT_NAME" \ --resource-group "$RESOURCE_GROUP" \ --query "properties.accessPolicies" ``` Confirm the Service Principal is listed and includes the required key permissions.