Azure role-based access control in Azure Cosmos DB

APPLIES TO: NoSQL MongoDB Cassandra Gremlin Table

To learn more about role-based access control applied to data plane operations in the API for NoSQL, see Secure access to data and Azure Cosmos DB RBAC articles. For the Azure Cosmos DB API for MongoDB, see Data Plane RBAC in the API for MongoDB.

Azure Cosmos DB provides built-in Azure role-based access control (Azure RBAC) for common management scenarios in Azure Cosmos DB. An individual who has a profile in Microsoft Entra ID can assign these Azure roles to users, groups, service principals, or managed identities to grant or deny access to resources and operations on Azure Cosmos DB resources. Role assignments are scoped to control-plane access only, which includes access to Azure Cosmos DB accounts, databases, containers, and offers (throughput).

Built-in roles

The following are the built-in roles supported by Azure Cosmos DB:

Built-in role	Description
DocumentDB Account Contributor	Can manage Azure Cosmos DB accounts.
Cosmos DB Account Reader Role	Can read Azure Cosmos DB account data.
CosmosBackupOperator	Can submit a restore request in the Azure portal for a periodic backup enabled database or a container. Can modify the backup interval and retention in the Azure portal. Cannot access any data or use Data Explorer.
CosmosRestoreOperator	Can perform a restore action for an Azure Cosmos DB account with continuous backup mode.
Cosmos DB Operator	Can provision Azure Cosmos DB accounts, databases, and containers. Cannot access any data or use Data Explorer.

Identity and access management (IAM)

The Access control (IAM) pane in the Azure portal is used to configure Azure role-based access control on Azure Cosmos DB resources. The roles are applied to users, groups, service principals, and managed identities in Active Directory. You can use built-in roles or custom roles for individuals and groups. The following screenshot shows Active Directory integration (Azure RBAC) using access control (IAM) in the Azure portal:

Custom roles

In addition to the built-in roles, users may also create custom roles in Azure and apply these roles to service principals across all subscriptions within their Active Directory tenant. Custom roles provide users a way to create Azure role definitions with a custom set of resource provider operations. To learn which operations are available for building custom roles for Azure Cosmos DB see, Azure Cosmos DB resource provider operations

Preventing changes from the Azure Cosmos DB SDKs

The Azure Cosmos DB resource provider can be locked down to prevent any changes to resources from a client connecting using the account keys (that is applications connecting via the Azure Cosmos DB SDK). This feature may be desirable for users who want higher degrees of control and governance for production environments. Preventing changes from the SDK also enables features such as resource locks and diagnostic logs for control plane operations. The clients connecting from Azure Cosmos DB SDK will be prevented from changing any property for the Azure Cosmos DB accounts, databases, containers, and throughput. The operations involving reading and writing data to Azure Cosmos DB containers themselves are not impacted.

When this feature is enabled, changes to any resource can only be made from a user with the right Azure role and Microsoft Entra credentials including Managed Service Identities.

Check list before enabling

This setting will prevent any changes to any Azure Cosmos DB resource from any client connecting using account keys including any Azure Cosmos DB SDK, any tools that connect via account keys. To prevent issues or errors from applications after enabling this feature, check if applications perform any of the following actions before enabling this feature, including:

• Creating, deleting child resources such as databases and containers. This includes resources for other APIs such as Cassandra, MongoDB, Gremlin, and table resources.

• Reading or updating throughput on database or container level resources.

• Modifying container properties including index policy, TTL and unique keys.

• Modifying stored procedures, triggers or user-defined functions.

If your applications (or users via Azure portal) perform any of these actions they will need to be migrated to execute via ARM Templates, PowerShell, Azure CLI, REST, or Azure Management Library. Note that Azure Management is available in multiple languages.

Set via ARM Template

To set this property using an ARM template, update your existing template or export a new template for your current deployment, then include the "disableKeyBasedMetadataWriteAccess": true to the properties for the databaseAccounts resources. Below is a basic example of an Azure Resource Manager template with this property setting.

{
    {
      "type": "Microsoft.DocumentDB/databaseAccounts",
      "name": "[variables('accountName')]",
      "apiVersion": "2020-04-01",
      "location": "[parameters('location')]",
      "kind": "GlobalDocumentDB",
      "properties": {
        "consistencyPolicy": "[variables('consistencyPolicy')[parameters('defaultConsistencyLevel')]]",
        "locations": "[variables('locations')]",
        "databaseAccountOfferType": "Standard",
        "disableKeyBasedMetadataWriteAccess": true
        }
    }
}

Set via Azure CLI

To enable using Azure CLI, use the command below:

az cosmosdb update  --name [CosmosDBAccountName] --resource-group [ResourceGroupName]  --disable-key-based-metadata-write-access true

Set via PowerShell

To enable using Azure PowerShell, use the command below:

Update-AzCosmosDBAccount -ResourceGroupName [ResourceGroupName] -Name [CosmosDBAccountName] -DisableKeyBasedMetadataWriteAccess true

Next steps

• What is Azure role-based access control (Azure RBAC)
• Azure custom roles
• Azure Cosmos DB resource provider operations
• Configure role-based access control for your Azure Cosmos DB for MongoDB