Role-based access control in Azure Cosmos DB

Azure Cosmos DB provides built-in role-based access control (RBAC) for common management scenarios in Azure Cosmos DB. An individual who has a profile in Azure Active Directory can assign these RBAC 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 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 Can read Azure Cosmos DB account data.
Cosmos Backup Operator Can submit restore request for an Azure Cosmos database or a container.
Cosmos DB Operator Can provision Azure Cosmos accounts, databases, and containers but cannot access the keys that are required to access the data.


RBAC support in Azure Cosmos DB applies to control plane operations only. Data plane operations are secured using master keys or resource tokens. To learn more, see Secure access to data in Azure Cosmos DB

Identity and access management (IAM)

The Access control (IAM) pane in the Azure portal is used to configure role-based access control on Azure Cosmos 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 (RBAC) using access control (IAM) in the Azure portal:

Access control (IAM) in the Azure portal - demonstrating database security

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 RBAC 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 Cosmos SDK

The Cosmos resource provider can be locked down to prevent any changes to resources including Cosmos account, databases, containers and throughput from any client connecting via account keys (i.e. applications connecting via Cosmos SDK). When set, changes to any resource must be from a user with the proper RBAC role and credentials. This capability is set with disableKeyBasedMetadataWriteAccess property value in the Cosmos resource provider. An example of an Azure Resource Manager template with this property setting is below.

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

Next steps