Connect to Azure DocumentDB using role-based access control and Microsoft Entra ID

Open a new terminal.

Sign in to Azure CLI.

Use az group show to get the metadata for your current resource group.

az group show \
    --name "<name-of-existing-resource-group>"

Observe the output of the previous command. Record the value of the id property for this resource group as it is required to use in the next step.

{
  "id": "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/msdocs-identity-example",
  "location": "westus",
  "name": "msdocs-identity-example",
  "type": "Microsoft.Resources/resourceGroups"
}

Create a new JSON file named role-definition.json. In the file, create this resource definition specifying the values listed here. For the AssignableScopes list, add the id property of the resource group recorded in the previous step.

{
  "Name": "Azure DocumentDB RBAC Owner",
  "IsCustom": true,
  "Description": "Can perform all Azure role-based access control actions for Azure DocumentDB clusters.",
  "Actions": [
    "Microsoft.DocumentDb/mongoClusters/*"
  ],
  "AssignableScopes": [
    "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/msdocs-identity-example"
  ]
}

Create a new role definition using az role definition create. Use the role-definition.json file as the input for the --role-definition argument.

az role definition create \
    --role-definition role-definition.json

Review the output from the definition creation command. The output contains the unique identifier of the role definition in the id property. Record this value as it is required to use in the assignment step later in this guide.

{
  "assignableScopes": [
    "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/msdocs-identity-example"
  ],
  "description": "Can perform all Azure role-based access control actions for Azure DocumentDB clusters.",
  "id": "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/msdocs-identity-example/providers/Microsoft.Authorization/roleDefinitions/a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1",
  "name": "e4e4e4e4-ffff-aaaa-bbbb-c5c5c5c5c5c5",
  "permissions": [
    {
      "actions": [
        "Microsoft.DocumentDb/*"
      ]
    }
  ],
  "roleName": "Azure DocumentDB RBAC Owner",
  "roleType": "CustomRole"
}

Open a new terminal.

Sign in to Azure CLI.

Create a new Bicep file to define your role definition. Name the file control-plane-role-definition.bicep. Add these actions to the definition:

metadata description = 'Create RBAC definition for Azure role-based access control access to Azure DocumentDB.'

@description('Name of the role definition.')
param roleDefinitionName string = 'Azure DocumentDB RBAC Owner'

@description('Description of the role definition.')
param roleDefinitionDescription string = 'Can perform all Azure role-based access control actions for Azure DocumentDB clusters.'

resource definition 'Microsoft.Authorization/roleDefinitions@2022-04-01' = {
  name: guid(subscription().id, resourceGroup().id, roleDefinitionName)
  scope: resourceGroup()
  properties: {
    roleName: roleDefinitionName
    description: roleDefinitionDescription
    type: 'CustomRole'
    permissions: [
      {
        actions: [
          'Microsoft.DocumentDb/mongoClusters/*'
        ]
      }
    ]
    assignableScopes: [
      resourceGroup().id
    ]
  }
}

output definitionId string = definition.id

Deploy the Bicep template using az deployment group create. Specify the name of the Bicep template and Azure resource group.

az deployment group create \
    --resource-group "<name-of-existing-resource-group>" \
    --template-file control-plane-role-definition.bicep

Review the output from the deployment. The output contains the unique identifier of the role definition in the properties.outputs.definitionId.value property. Record this value as it is required to use in the assignment step later in this guide.

{
  "properties": {
    "outputs": {
      "definitionId": {
        "type": "String",
        "value": "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/msdocs-identity-example/providers/Microsoft.Authorization/roleDefinitions/a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1"
      }
    }
  }
}

Create a new Bicep file to define your role assignment. Name the file control-plane-role-assignment.bicep.

metadata description = 'Assign RBAC role for Azure role-based access control access to Azure DocumentDB.'

@description('Id of the role definition to assign to the targeted principal in the context of the cluster.')
param roleDefinitionId string

@description('Id of the identity/principal to assign this role in the context of the cluster.')
param identityId string

resource assignment 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
  name: guid(subscription().id, resourceGroup().id, roleDefinitionId, identityId)
  scope: resourceGroup()
  properties: {
    roleDefinitionId: roleDefinitionId
    principalId: identityId
  }
}

Create a new Bicep parameters file named control-plane-role-assignment.bicepparam. In this parameters file; assign the previously recorded role definition identifiers to the roleDefinitionId parameter, and the unique identifier for your identity to the identityId parameter.

using './control-plane-role-assignment.bicep'

param roleDefinitionId = '<id-of-new-role-definition>'
param identityId = '<id-of-existing-identity>'

Deploy this Bicep template using az deployment group create.

az deployment group create \
    --resource-group "<name-of-existing-resource-group>" \
    --parameters control-plane-role-assignment.bicepparam \
    --template-file control-plane-role-assignment.bicep

Sign in to the Azure portal (https://portal.azure.com).

Enter Resource group in the global search bar.

Within Services, select Resource groups.

In the Resource groups pane, select your existing resource group.

Within the pane for the resource group, select Access control (IAM) in the service menu.

In the Access control (IAM) pane, select Add. Then select Add custom role.

Within the Basics pane, configure the following options, and then select Next:

In the Permissions pane, select Add permissions. Then, search for DocumentDB in the permissions dialog. Finally, select the Microsoft.DocumentDB/mongoClusters option.

In the permissions dialog, select all Actions for Microsoft.DocumentDB/mongoClusters. Then, select Add to return to the *Permissions pane.

Back in the Permissions pane, observe the list of permissions. Then, select Review + create.

In the Review + create pane, review the specified options for the new role definition. Finally, select Create.

Wait for the portal to finish creating the role definition.

In the Access control (IAM) pane, select Add and then Add role assignment.

In the Role pane, search for Azure DocumentDB and then select the Azure DocumentDB RBAC Owner role created earlier in this guide. Then, select Next.

In the Members pane, select the Select members option. In the members dialog, select the identity you wish to grant this level of access for your Azure DocumentDB clusters and then use the Select option to confirm your choice.

Back in the Members pane, review the selected member[s] and then select Review + assign.

In the Review + assign pane, review the specified options for the new role assignment. Finally, select Review + assign.

Wait for the portal to finish creating the role assignment.

Open a new terminal.

Sign in to Azure CLI.

Check your target Azure subscription.

az account show

Create a new Terraform file to define your role definition. Name the file control-plane-role-definition.tf. Add these actions to the definition:

variable "role_definition_name" {
  type        = string
  description = "Name of the role definition."
  default     = "Azure DocumentDB RBAC Owner"
}

variable "role_definition_description" {
  type        = string
  description = "Description of the role definition."
  default     = "Can perform all Azure role-based access control actions for Azure DocumentDB clusters."
}

terraform {
  required_providers {
    azurerm = {
      source  = "hashicorp/azurerm"
      version = "~> 4.0"
    }
  }
}

provider "azurerm" {
  features {}
}

data "azurerm_client_config" "current" {}

data "azurerm_resource_group" "existing" {
  name = "<name-of-existing-resource-group>"
}

resource "azurerm_role_definition" "control_plane" {
  name               = var.role_definition_name
  scope              = data.azurerm_resource_group.existing.id
  description        = var.role_definition_description

  permissions {
    actions = [
      "Microsoft.DocumentDb/mongoClusters/*"
    ]
  }

  assignable_scopes = [
    data.azurerm_resource_group.existing.id
  ]
}

output "definition_id" {
  value = azurerm_role_definition.control_plane.id
}

Initialize the Terraform deployment.

terraform init --upgrade

Create an execution plan for the role definition and save it to a file named role-definition.tfplan.

ARM_SUBSCRIPTION_ID=$(az account show --query id --output tsv) terraform plan --out "role-definition.tfplan"

Apply the execution plan to deploy the role definition to Azure.

ARM_SUBSCRIPTION_ID=$(az account show --query id --output tsv) terraform apply "role-definition.tfplan"

Review the output from the deployment. The output contains the unique identifier of the role definition in the definition_id property. Record this value as it is required to use in the assignment step later in this guide.

Create a new Terraform file to define your role assignment. Name the file control-plane-role-assignment.tf.

variable "role_definition_id" {
  type        = string
  description = "Id of the role definition to assign to the targeted principal in the context of the cluster."
}

variable "identity_id" {
  type        = string
  description = "Id of the identity/principal to assign this role in the context of the cluster."
}

terraform {
  required_providers {
    azurerm = {
      source  = "hashicorp/azurerm"
      version = "~> 4.0"
    }
  }
}

provider "azurerm" {
  features {}
}

data "azurerm_resource_group" "existing" {
  name = "<name-of-existing-resource-group>"
}

resource "azurerm_role_assignment" "control_plane" {
  scope              = data.azurerm_resource_group.existing.id
  role_definition_id = var.role_definition_id
  principal_id       = var.identity_id
}

Create a new Terraform variables file named control-plane-role-assignment.tfvars. In this variables file; assign the previously recorded role definition identifiers to the role_definition_id variable, and the unique identifier for your identity to the identity_id variable.

role_definition_id = "<id-of-new-role-definition>"
identity_id        = "<id-of-existing-identity>"

Initialize and apply this Terraform configuration.

terraform init --upgrade

ARM_SUBSCRIPTION_ID=$(az account show --query id --output tsv) terraform plan --var-file="control-plane-role-assignment.tfvars" --out "role-assignment.tfplan"

ARM_SUBSCRIPTION_ID=$(az account show --query id --output tsv) terraform apply "role-assignment.tfplan"

Get the details for the currently logged-in account using az ad signed-in-user.

az ad signed-in-user show

The command outputs a JSON response containing various fields.

{
  "@odata.context": "<https://graph.microsoft.com/v1.0/$metadata#users/$entity>",
  "businessPhones": [],
  "displayName": "Kai Carter",
  "givenName": "Kai",
  "id": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
  "jobTitle": "Senior Sales Representative",
  "mail": "<kai@adventure-works.com>",
  "mobilePhone": null,
  "officeLocation": "Redmond",
  "preferredLanguage": null,
  "surname": "Carter",
  "userPrincipalName": "<kai@adventure-works.com>"
}

Enable Microsoft Entra ID authentication on the cluster by updating the cluster resource to include MicrosoftEntraID in the authConfig.allowedModes array:

az resource patch \
    --resource-group "<resource-group>" \
    --name "<cluster-name>" \
    --resource-type "Microsoft.DocumentDB/mongoClusters" \
    --properties '{"authConfig":{"allowedModes":["MicrosoftEntraID","NativeAuth"]}}' \
    --latest-include-preview

Verify the change was applied by reading the authConfig property on the cluster using az resource show.

az resource show \
    --resource-group "<resource-group>" \
    --name "<cluster-name>" \
    --resource-type "Microsoft.DocumentDB/mongoClusters" \
    --query "properties.authConfig" \
    --latest-include-preview

(Optional) Get the unique identifier for the Microsoft Entra principal you plan to register on the cluster. You can obtain it with the Azure CLI using one of the following commands:

• Current signed-in identity

  az ad signed-in-user show      
  

• Another human identity using friendly name

  az ad user show \
    --id "<user-alias-and-domain>"
  

• Service principal using app identifier

  az ad sp show \
    --id "<application-id>"
  

• Managed identity using resource group and name

  az identity show \
    --resource-group "<resource-group>" \
    --name "<managed-identity-name>"      
  

Create a small Bicep template that updates the cluster authConfig to include Microsoft Entra ID (save as enable-entra-id.bicep):

param clusterName string
param location string = resourceGroup().location

resource cluster 'Microsoft.DocumentDB/mongoClusters@2025-09-01' = {
  name: clusterName
  location: location
  properties: {
    authConfig: {
      allowedModes: [
        'MicrosoftEntraID'
        'NativeAuth'
      ]
    }
  }
}

Deploy the template to update the cluster:

az deployment group create \
    --resource-group "<resource-group>" \
    --template-file enable-entra-id.bicep \
    --parameters clusterName="<cluster-name>"

Verify the authConfig property on the cluster by using az resource show.

az resource show \
    --resource-group "<resource-group>" \
    --name "<cluster-name>" \
    --resource-type "Microsoft.DocumentDB/mongoClusters" \
    --query "properties.authConfig" \
    --latest-include-preview

On the Home pane of the Azure portal, locate and select the Microsoft Entra ID option.

Within the Overview pane for the Microsoft Entra ID tenant, select Users inside the Manage section of the service menu.

In the list of users, select the identity (user) that you want to get more details about.

On the details pane for the specific user, observe the value of the Object ID property.

Navigate to the existing Azure DocumentDB cluster resource.

In the cluster menu, under Settings, select Authentication.

In the Authentication methods section, select Native DocumentDB and Microsoft Entra ID to enable Microsoft Entra ID authentication alongside native authentication.

Select Save to persist the change.

The Authentication methods section should now list both NativeAuth and MicrosoftEntraID as enabled methods.

(Optional) Get the unique identifier for the Microsoft Entra principal you plan to register on the cluster. You can obtain it with the Azure CLI using one of the following commands:

• Current signed-in identity

  az ad signed-in-user show      
  

• Another human identity using friendly name

  az ad user show \
    --id "<user-alias-and-domain>"
  

• Service principal using app identifier

  az ad sp show \
    --id "<application-id>"
  

• Managed identity using resource group and name

  az identity show \
    --resource-group "<resource-group>" \
    --name "<managed-identity-name>"      
  

Create a Terraform configuration file to enable Microsoft Entra ID authentication on your existing cluster. Save the file as enable-entra-id.tf:

variable "cluster_name" {
  type        = string
  description = "Name of the existing cluster"
}

variable "resource_group_name" {
  type        = string
  description = "Name of the existing resource group"
}

terraform {
  required_providers {
    azurerm = {
      source  = "hashicorp/azurerm"
      version = "~> 4.0"
    }
  }
}

provider "azurerm" {
  features {}
}

data "azurerm_resource_group" "existing" {
  name = var.resource_group_name
}

data "azurerm_mongo_cluster" "existing" {
  name                = var.cluster_name
  resource_group_name = data.azurerm_resource_group.existing.name
}

resource "azurerm_mongo_cluster" "enable_entra" {
  name                   = data.azurerm_mongo_cluster.existing.name
  resource_group_name    = data.azurerm_resource_group.existing.name
  location               = data.azurerm_mongo_cluster.existing.location
  administrator_username = data.azurerm_mongo_cluster.existing.administrator_username
  administrator_password = data.azurerm_mongo_cluster.existing.administrator_password
  shard_count            = data.azurerm_mongo_cluster.existing.shard_count
  compute_tier           = data.azurerm_mongo_cluster.existing.compute_tier
  high_availability_mode = data.azurerm_mongo_cluster.existing.high_availability_mode
  storage_size_in_gb     = data.azurerm_mongo_cluster.existing.storage_size_in_gb
  version                = data.azurerm_mongo_cluster.existing.version

  # Enable both Microsoft Entra ID and Native authentication
  authentication_enabled = true
}

Create a variables file named enable-entra-id.tfvars with your cluster details:

cluster_name        = "<cluster-name>"
resource_group_name = "<resource-group>"

Initialize and apply the Terraform configuration to enable Microsoft Entra ID authentication:

terraform init --upgrade

ARM_SUBSCRIPTION_ID=$(az account show --query id --output tsv) terraform plan --var-file="enable-entra-id.tfvars" --out "enable-entra.tfplan"

ARM_SUBSCRIPTION_ID=$(az account show --query id --output tsv) terraform apply "enable-entra.tfplan"

Verify the authConfig property on the cluster by using az resource show.

az resource show \
    --resource-group "<resource-group>" \
    --name "<cluster-name>" \
    --resource-type "Microsoft.DocumentDB/mongoClusters" \
    --query "properties.authConfig" \
    --latest-include-preview

Get the unique identifier (object ID) of the Microsoft Entra principal you want to grant access to using one of the following commands:

• Current signed-in identity

  az ad signed-in-user show      
  

• Another human identity using friendly name

  az ad user show \
    --id "<user-alias-and-domain>"
  

• Service principal using app identifier

  az ad sp show \
    --id "<application-id>"
  

• Managed identity using resource group and name

  az identity show \
    --resource-group "<resource-group>" \
    --name "<managed-identity-name>"      
  

Register the principal on the cluster and map it to MongoDB database roles. The following example registers a principal as a readWrite user on the sales database:

az resource create \
    --resource-group "<resource-group>" \
    --name "<cluster-name>/users/<principal-id>" \
    --resource-type "Microsoft.DocumentDB/mongoClusters/users" \
    --location "<cluster-region>" \
    --properties '{"identityProvider":{"type":"MicrosoftEntraID","properties":{"principalType":"User"}},"roles":[{"db":"sales","role":"readWrite"}]}' \
    --latest-include-preview

• Replace principalType with servicePrincipal for app/service principals or ManagedIdentity for managed identities.
• To grant administrative privileges, use {"db":"admin","role":"root"} in the roles array.

List all registered principals and their mapped roles (cluster-level view):

az rest \
    --method "GET" \
    --url "https://management.azure.com/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.DocumentDB/mongoClusters/<cluster-name>/users?api-version=2025-09-01"

• The response contains an array of user resources, each with identityProvider metadata and a roles array showing mapped database roles.

Get details for a specific registered principal (replace <principal-id>):

az resource show \
    --resource-group "<resource-group>" \
    --name "<cluster-name>/users/<principal-id>" \
    --resource-type "Microsoft.DocumentDB/mongoClusters/users" \
    --latest-include-preview

Remove a registered principal (revoke data-plane access):

az resource delete \
    --resource-group "<resource-group>" \
    --name "<cluster-name>/users/<principal-id>" \
    --resource-type "Microsoft.DocumentDB/mongoClusters/users" \
    --latest-include-preview

Create a Bicep file (for example register-principal.bicep) to register the principal and map database roles:

param clusterName string
param principalId string
param location string = resourceGroup().location
param principalType string = 'User'
param roles array = [
  {
    db: 'sales'
    role: 'readWrite'
  }
]

resource user 'Microsoft.DocumentDB/mongoClusters/users@2025-09-01' = {
  name: '${clusterName}/users/${principalId}'
  location: location
  properties: {
    identityProvider: {
      type: 'Microsoft.EntraID'
      properties: {
        principalType: principalType
      }
    }
    roles: roles
  }
}

Deploy the Bicep template to register the principal:

az deployment group create \
    --resource-group "<resource-group>" \
    --template-file register-principal.bicep \
    --parameters clusterName="<cluster-name>" principalId="<principal-id>"

List all registered principals for the cluster using the REST API (useful after Bicep deployment):

az rest \
    --method GET \
    --url "https://management.azure.com/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.DocumentDB/mongoClusters/<cluster-name>/users?api-version=2025-09-01"

Get details for a specific registered principal created by Bicep (replace <principal-id>):

az resource show \
    --resource-group "<resource-group>" \
    --name "<cluster-name>/users/<principal-id>" \
    --resource-type "Microsoft.DocumentDB/mongoClusters/users" \
    --latest-include-preview

Remove the principal by deleting the resource (or deploy a template without the user resource):

az resource delete \
    --resource-group "<resource-group>" \
    --name "<cluster-name>/users/<principal-id>" \
    --resource-type "Microsoft.DocumentDB/mongoClusters/users" \
    --latest-include-preview

Open the target Azure DocumentDB cluster in the Azure portal.

Under Settings, select Authentication.

In the Microsoft Entra ID authentication section, the portal lists the registered Microsoft Entra principals by object ID. Use this view to:

• Scan the list for expected object identifiers.
• Inspect the details for a single principal by selecting a listed entry (or use the portal's search feature).
• Use the Remove action next to an entry to immediately revoke that principal's data-plane access.

To get friendly names for object identifiers shown in the portal list, use the Users page within the Microsoft Entra ID section. Then, search by object ID or friendly name.

Get the unique identifier (object ID) of the Microsoft Entra principal you want to grant access to using one of the following commands:

• Current signed-in identity

  az ad signed-in-user show      
  

• Another human identity using friendly name

  az ad user show \
    --id "<user-alias-and-domain>"
  

• Service principal using app identifier

  az ad sp show \
    --id "<application-id>"
  

• Managed identity using resource group and name

  az identity show \
    --resource-group "<resource-group>" \
    --name "<managed-identity-name>"      
  

Create a Terraform file (for example register-principal.tf) to register the principal and map database roles using the AzAPI provider:

variable "cluster_name" {
  type        = string
  description = "Name of the existing cluster"
}

variable "resource_group_name" {
  type        = string
  description = "Name of the existing resource group"
}

variable "principal_id" {
  type        = string
  description = "Object ID of the Microsoft Entra principal"
}

variable "principal_type" {
  type        = string
  description = "Type of principal: User, ServicePrincipal, or ManagedIdentity"
  default     = "User"
}

variable "roles" {
  type = list(object({
    db   = string
    role = string
  }))
  description = "Database roles to assign"
  default = [
    {
      db   = "sales"
      role = "readWrite"
    }
  ]
}

terraform {
  required_providers {
    azapi = {
      source  = "azure/azapi"
      version = "~> 2.0"
    }
    azurerm = {
      source  = "hashicorp/azurerm"
      version = "~> 4.0"
    }
  }
}

provider "azurerm" {
  features {}
}

provider "azapi" {}

data "azurerm_resource_group" "existing" {
  name = var.resource_group_name
}

data "azurerm_mongo_cluster" "existing" {
  name                = var.cluster_name
  resource_group_name = var.resource_group_name
}

resource "azapi_resource" "mongo_cluster_user" {
  type      = "Microsoft.DocumentDB/mongoClusters/users@2025-09-01"
  name      = var.principal_id
  parent_id = data.azurerm_mongo_cluster.existing.id
  location  = data.azurerm_resource_group.existing.location

  body = {
    properties = {
      identityProvider = {
        type = "MicrosoftEntraID"
        properties = {
          principalType = var.principal_type
        }
      }
      roles = var.roles
    }
  }
}

Create a variables file named register-principal.tfvars:

cluster_name        = "<cluster-name>"
resource_group_name = "<resource-group>"
principal_id        = "<principal-id>"
principal_type      = "User"
roles = [
  {
    db   = "sales"
    role = "readWrite"
  }
]

Initialize and apply the Terraform configuration to register the principal:

terraform init --upgrade

ARM_SUBSCRIPTION_ID=$(az account show --query id --output tsv) terraform plan --var-file="register-principal.tfvars" --out "register-principal.tfplan"

ARM_SUBSCRIPTION_ID=$(az account show --query id --output tsv) terraform apply "register-principal.tfplan"

List all registered principals for the cluster using the REST API (useful after Terraform deployment):

az rest \
    --method GET \
    --url "https://management.azure.com/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.DocumentDB/mongoClusters/<cluster-name>/users?api-version=2025-09-01"

Get details for a specific registered principal created by Terraform (replace <principal-id>):

az resource show \
    --resource-group "<resource-group>" \
    --name "<cluster-name>/users/<principal-id>" \
    --resource-type "Microsoft.DocumentDB/mongoClusters/users" \
    --latest-include-preview

Remove the principal by destroying the Terraform resource:

ARM_SUBSCRIPTION_ID=$(az account show --query id --output tsv) terraform destroy --var-file="register-principal.tfvars"

Navigate to the Azure DocumentDB cluster.

Select the Connection strings navigation menu option.

Copy or record the value from the Connection string field.