Cosmos DB’s data plane access, often thought of as just "reading and writing data," is actually controlled by the same RBAC mechanisms you use for managing its control plane resources.
Let’s watch it in action. Imagine we have a Cosmos DB account, my-cosmos-account, with a database my-database and a container my-container. We want to grant a user, alice@example.com, read-only access to the data within my-container.
First, we need to identify the specific resource ID for the container. This looks like:
/subscriptions/YOUR_SUBSCRIPTION_ID/resourceGroups/my-resource-group/providers/Microsoft.DocumentDB/databaseAccounts/my-cosmos-account/databases/my-database/containers/my-container
Now, we can assign a role to Alice. The Cosmos DB Data Reader role is perfect for this. We’ll use the Azure CLI:
az role assignment create --assignee alice@example.com \
--role "Cosmos DB Data Reader" \
--scope "/subscriptions/YOUR_SUBSCRIPTION_ID/resourceGroups/my-resource-group/providers/Microsoft.DocumentDB/databaseAccounts/my-cosmos-account/databases/my-database/containers/my-container"
After this assignment, Alice can now authenticate to the Cosmos DB data plane (using either keys or Azure AD authentication) and perform GET and POST operations that read data from my-container. She won’t be able to create or delete containers, or even read container metadata like throughput settings, because her role assignment is scoped only to the container’s data plane operations.
The problem this solves is the traditional dichotomy where data access was often managed solely by account keys, which are highly privileged and difficult to rotate or restrict granularly. RBAC for data plane access allows for fine-grained permissions, integrating Cosmos DB access into your broader Azure AD identity and access management strategy.
Internally, when a request comes into the Cosmos DB data plane, Azure AD or the Cosmos DB service validates the incoming token against the RBAC assignments for the target resource. If the identity associated with the token has a role assignment that grants the specific action (e.g., Microsoft.DocumentDB/databaseAccounts/read or Microsoft.DocumentDB/databaseAccounts/items/read) at the scope of the requested resource (or a higher scope that inherits down), the operation is permitted.
The exact levers you control are the scope of the role assignment and the role itself. You can assign roles at the account, database, or container level. Roles range from Cosmos DB Data Reader (read-only items), Cosmos DB Data Contributor (read, create, update, delete items), to Cosmos DB Operator (manage containers and databases, but not data) and Cosmos DB Built-in Data Processor (read/write items and execute stored procedures).
What most people don’t realize is that even roles like "Cosmos DB Operator" which seem control-plane oriented, can be scoped down to a specific database or container. This means you can grant someone the ability to modify throughput or indexing policies on a single container without giving them access to the entire account’s data or other containers.
The next step is often understanding how to leverage managed identities for service-to-service authentication to Cosmos DB data plane resources.