Note
This feature is not available for any of the following deployments:
M0Free clustersFlex clusters
To learn more, see Limits.
Atlas supports secretless authentication for using Azure Key Vault (AKV) 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 Service Principal in your Azure tenant, and Atlas authenticates to AKV using short-lived OAuth 2.0 access tokens that Azure Active Directory (Azure AD) issues.
This approach:
Eliminates the need to create, store, and rotate client secrets in Atlas.
Centralizes access control entirely within Azure using 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 AD and Azure Key Vault as the security boundary. Atlas doesn't store reusable customer-managed secrets and instead uses Azure-issued tokens at runtime. Access is enforced using least privilege permissions and you can remove 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 for a MongoDB project, you must have:
An M10 or larger cluster.
The Azure account, and the encryption key in your AKV.
To learn how to configure these Azure components, see the Azure Documentation.
Atlas uses these resources when enabling encryption at rest for a cluster in the Atlas project.
Permissions in Azure to:
Register an enterprise Service Principal in your tenant. This prerequisite requires Microsoft Entra ID permissions to add or manage Enterprise Applications, such as Application Administrator, Cloud Application Administrator, or Global Administrator.
To learn more, see Quickstart: Add an enterprise application.
Access to the Key Vault key using one of the following options:
Azure RBAC (at the Key Vault or key scope)
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 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:
getencryptdecrypt
You should scope permissions as narrowly as possible and grant them using one of the following options:
Azure RBAC (at the Key Vault or key scope)
To learn more, see Quickstart: Add an enterprise application.
Set Up EAR AKV Secretless Authentication
To configure Encryption at Rest (EAR) with secretless authentication, you must:
Create an Atlas-managed Azure Service Principal.
Grant the Service Principal access to your Key Vault key.
Configure EAR to use the Service Principal.
Create an Atlas-managed Azure Service Principal
Create an Azure Service Principal in your tenant for the
Atlas-owned 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 application identity:
atlasAzureAppId: 9efedfcc-2eca-4b27-a613-0cad1e114cb7
Create or locate the Atlas Service Principal.
If a Service Principal already exists for the Atlas application, run the following command to locate it:
az ad sp list --filter "appId eq '9efedfcc-2eca-4b27-a613-0cad1e114cb7'"
If it doesn't exist, run the following command to create it:
az ad sp create --id 9efedfcc-2eca-4b27-a613-0cad1e114cb7
From the output, copy the id field, which is the Service
Principal Object ID that Atlas requires.
Register the Service Principal with Atlas.
Use the Cloud Provider Access API:
Endpoint:
POST /api/atlas/v2/groups/{groupId}/cloudProviderAccess
Request body example:
{ "providerName": "AZURE", "tenantId": "<azure-tenant-id>", "servicePrincipalId": "<service-principal-object-id>", "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.
Grant AKV 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 RBAC
To grant access using Azure RBAC:
Assign the Reader role so Atlas can read Key Vault metadata.
Run the following command:
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"
Assign a cryptographic role such as Key Vault Crypto User.
Run the following command:
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:
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,
update your EAR configuration with the roleId that the
Cloud Provider Access API returned.
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 page displays.
Configure your authentication method.
Atlas supports two authentication methods for AKV:
Service Principal (Recommended): Use an Atlas-managed service principal specific to your project to authenticate to AKV (secretless authentication covered here).
Static Credentials: Provide customer-managed credentials. To learn more, see Manage Customer Keys with Azure Key Vault Over a Public Network or Manage Customer Keys with Azure Key Vault Over Private Endpoints.
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. |
Note
You can't modify the AKV configuration here after you enable and set up private endpoint connections to your AKV.
Enter the Encryption Key.
Key Identifier | Enter the full URL for the key created in the Key Vault. IMPORTANT: The key identifier must be provided in the full Azure general format: |
(Optional) Configure private endpoint connections to your AKV.
To learn more, see Enable and Set up Private Endpoint Connections for a Project
Verify the network settings.
If you configured Atlas using the Atlas Administration API to communicate with AKV using Azure Private Link to ensure that all traffic between Atlas and Key Vault takes place over 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 if you want Atlas to use private endpoint connections for your AKV.
Endpoint:
PATCH /api/atlas/v2/groups/{groupId}/encryptionAtRest
Request body example:
{ "azureKeyVault": { "enabled": true, "roleId": "<atlas-managed-roleId>", "subscriptionID": "<subscription-id>", "resourceGroupName": "<resource-group>", "keyVaultName": "<key-vault-name>", "keyIdentifier": "https://<vault>.vault.azure.net/keys/<key>/<version>", "azureEnvironment": "AZURE" } }
After this update, Atlas authenticates to AKV using short-lived 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.
Create an Atlas-managed Service Principal.
Grant Key Vault permissions.
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
PATCHrequest 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:
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:
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.