Use Role-Based Access Control for CosmosDB Data Plane Access

Risk Level: Medium (should be achieved)

Ensure that your Microsoft Azure Cosmos DB accounts are configured to use Microsoft Entra ID for authentication rather than access keys. Microsoft Entra Authentication is a password-free mechanism that integrates with Microsoft Entra ID and incorporates Role-Based Access Control (RBAC) functionality.

Security

Using access keys for authentication can result in serious security vulnerabilities due to the potential leakage of secrets to source control systems and their exposure to the public. To ensure optimal security, it is strongly recommended to use Microsoft Entra ID with managed identities to authorize access to Azure CosmosDB data plane. This method offers superior security and ease of use compared to access key authorization. Enabling and configuring Microsoft Entra Authentication allows connections via a user, service principal, or managed identity. Implementing Role-Based Access Control (RBAC) ensures that individuals are granted appropriate access to the necessary resources.

Note:

Disabling key-based authentication prevents your Cosmos DB account from being used without the more secure Microsoft Entra ID authentication method. To ensure that key-based authentication is disabled for your Azure Cosmos DB accounts, see Disable Key-Based Authentication for Azure Cosmos DB Accounts.
Ensure that your Azure Cosmos DB accounts are configured with system-assigned and/or user-assigned managed identities for secure authorization and authentication with other Azure cloud services and resources. For more details, see Use Managed Identities for Azure Cosmos DB Accounts.

Audit

To determine if Role-Based Access Control (RBAC) is configured for Azure CosmosDB data plane access, perform the following operations:

Getting the RBAC configuration for Azure Cosmos DB accounts using Microsoft Azure Portal is not currently supported.

Using Azure CLI

01 Run account list command (Windows/macOS/Linux) with custom output filters to list the IDs of the cloud subscriptions available in your Azure cloud account:

az account list
	--query '[*].id'

02 The command output should return the requested subscription identifiers (IDs):

[
	"abcdabcd-1234-abcd-1234-abcdabcdabcd",
	"abcd1234-abcd-1234-abcd-abcd1234abcd"
]

03 Run account set command (Windows/macOS/Linux) with the ID of the Azure cloud subscription that you want to examine as the identifier parameter to set the selected subscription to be the current active subscription (the command does not produce an output):

az account set
	--subscription abcdabcd-1234-abcd-1234-abcdabcdabcd

04 Run cosmosdb list command (Windows/macOS/Linux) with custom query filters to list the name and the associated resource group for each Azure Cosmos DB account available in the selected subscription:

az cosmosdb list
	--output table
	--query '[*].{name:name, resourceGroup:resourceGroup}'

05 The command output should return the requested Cosmos DB account names:

Name                          ResourceGroup
---------------------------   ------------------------------
cc-project5-cosmos-database   cloud-shell-storage-westeurope
cc-cosmos-prod-dba-account    cloud-shell-storage-westeurope

06 Run cosmosdb sql role definition list command (Windows/macOS/Linux) to list all the SQL role definitions associated with your Azure Cosmos DB account:

az cosmosdb sql role definition list
	--resource-group cloud-shell-storage-westeurope
	--account-name cc-project5-cosmos-database
	--query '[*].[roleName,id]'

07 The command output should return each role definition (role name and role definition ID) available for your Cosmos DB account:

[
	[
		"Cosmos DB Built-in Data Reader",
		"/subscriptions/abcdabcd-1234-abcd-1234-abcdabcdabcd/resourceGroups/cloud-shell-storage-westeurope/providers/Microsoft.DocumentDB/databaseAccounts/cc-project5-cosmos-database/sqlRoleDefinitions/00000000-0000-0000-0000-000000000001"
	],
	[
		"Cosmos DB Built-in Data Contributor",
		"/subscriptions/abcdabcd-1234-abcd-1234-abcdabcdabcd/resourceGroups/cloud-shell-storage-westeurope/providers/Microsoft.DocumentDB/databaseAccounts/cc-project5-cosmos-database/sqlRoleDefinitions/00000000-0000-0000-0000-000000000002"
	]
]

08 Run cosmosdb sql role assignment list command (Windows/macOS/Linux) with the ID of the Azure Cosmos DB account that you want to examine as the identifier parameter, to list all the role assignments for the selected Cosmos DB account:

az cosmosdb sql role assignment list
	--account-name cc-project5-cosmos-database
	--resource-group cloud-shell-storage-westeurope
	--query '[*].roleDefinitionId'

09 The command output should return the role definition ID for each role assignment configured for your Cosmos DB account:

[]

If the cosmosdb sql role assignment list command output returns an empty array, i.e., [], there are no role assignments configured for your Azure Cosmos DB account. If the command output returns one or more role definition IDs but none of the IDs match the role definition IDs for "Cosmos DB Built-in Data Reader" and "Cosmos DB Built-in Data Contributor" roles listed in step no. 7, Role-Based Access Control (RBAC) is not configured for secure data plane access for the selected Azure Cosmos DB account.

10 Repeat steps no. 6 - 9 for each Azure Cosmos DB account available within the selected Azure subscription.

11 Repeat steps no. 3 – 10 for each Azure subscription created in your Microsoft Azure cloud account.

Remediation / Resolution

To ensure that Role-Based Access Control (RBAC) is configured for secure CosmosDB data plane access, perform the following operations:

Configuring Role-Based Access Control (RBAC) for Azure Cosmos DB accounts using Microsoft Azure Portal is not currently supported.

Using Azure CLI

01 Run account list command (Windows/macOS/Linux) with custom output filters to list the IDs of the cloud subscriptions available in your Azure cloud account:

az account list
	--query '[*].id'

02 The command output should return the requested subscription identifiers (IDs):

[
	"abcdabcd-1234-abcd-1234-abcdabcdabcd",
	"abcd1234-abcd-1234-abcd-abcd1234abcd"
]

az account set
	--subscription abcdabcd-1234-abcd-1234-abcdabcdabcd

az cosmosdb list
	--output table
	--query '[*].{name:name, resourceGroup:resourceGroup}'

05 The command output should return the requested Cosmos DB account names:

Name                          ResourceGroup
---------------------------   ------------------------------
cc-project5-cosmos-database   cloud-shell-storage-westeurope
cc-cosmos-prod-dba-account    cloud-shell-storage-westeurope

06 Run cosmosdb show command (Windows/macOS/Linux) with the name of the Azure Cosmos DB account that you want to examine as the identifier parameter and custom output filters to describe the ID of the selected Cosmos DB account:

az cosmosdb show
	--resource-group cloud-shell-storage-westeurope
	--account-name cc-project5-cosmos-database
	--query 'id'

07 The command output should return the full ID for your Cosmos DB account:

"/subscriptions/abcdabcd-1234-abcd-1234-abcdabcdabcd/resourceGroups/cloud-shell-storage-westeurope/providers/Microsoft.DocumentDB/databaseAccounts/cc-project5-cosmos-database"

08 Microsoft Azure Cosmos DB uses two built-in roles: Cosmos DB Built-in Data Reader and Cosmos DB Built-in Data Contributor. The Cosmos DB Built-in Data Reader role contains actions for reading metadata on Cosmos DB accounts, reading items in a container, executing queries, and reading the change feed. To create an SQL role assignment for the Cosmos DB Built-in Data Reader role under your Azure Cosmos DB account, run cosmosdb sql role assignment create command (OSX/Linux/UNIX). For --role-definition-name, specify the name of the required built-in role (i.e., Cosmos DB Built-in Data Contributor). For --principal-id, specify the ID of the identity that needs access to manage data in your Azure Cosmos DB account. For --scope, specify the full ID of the Cosmos DB account, identified in step 7:

az cosmosdb sql role assignment create
	--resource-group cloud-shell-storage-westeurope
	--account-name cc-project5-cosmos-database
	--role-definition-name "Cosmos DB Built-in Data Contributor"
	--principal-id "abcd1234-abcd-1234-abcd-abcd1234abcd"
	--scope "/subscriptions/abcdabcd-1234-abcd-1234-abcdabcdabcd/resourceGroups/cloud-shell-storage-westeurope/providers/Microsoft.DocumentDB/databaseAccounts/cc-project5-cosmos-database"

09 The command output should return the information available for the newly created role assignment:

{
	"id": "/subscriptions/abcdabcd-1234-abcd-1234-abcdabcdabcd/resourceGroups/cloud-shell-storage-westeurope/providers/Microsoft.DocumentDB/databaseAccounts/cc-project5-cosmos-database/sqlRoleAssignments/c21cc3d9-be45-4426-9622-c448b3db752c",
	"name": "c21cc3d9-be45-4426-9622-c448b3db752c",
	"principalId": "abcd1234-abcd-1234-abcd-abcd1234abcd",
	"resourceGroup": "cloud-shell-storage-westeurope",
	"roleDefinitionId": "/subscriptions/abcdabcd-1234-abcd-1234-abcdabcdabcd/resourceGroups/cloud-shell-storage-westeurope/providers/Microsoft.DocumentDB/databaseAccounts/cc-project5-cosmos-database/sqlRoleDefinitions/00000000-0000-0000-0000-000000000002",
	"scope": "/subscriptions/abcdabcd-1234-abcd-1234-abcdabcdabcd/resourceGroups/cloud-shell-storage-westeurope/providers/Microsoft.DocumentDB/databaseAccounts/cc-project5-cosmos-database",
	"type": "Microsoft.DocumentDB/databaseAccounts/sqlRoleAssignments"
}

10 The Cosmos DB Built-in Data Contributor role contains actions for reading metadata on Cosmos DB accounts, reading and writing with containers, and reading and writing with items. To create an SQL role assignment for the Cosmos DB Built-in Data Contributor role under your Azure Cosmos DB account, run cosmosdb sql role assignment create command (OSX/Linux/UNIX), as shown in the example listed below:

az cosmosdb sql role assignment create
	--resource-group cloud-shell-storage-westeurope
	--account-name cc-project5-cosmos-database
	--role-definition-name "Cosmos DB Built-in Data Reader"
	--principal-id "abcd1234-abcd-1234-abcd-abcd1234abcd"
	--scope "/subscriptions/abcdabcd-1234-abcd-1234-abcdabcdabcd/resourceGroups/cloud-shell-storage-westeurope/providers/Microsoft.DocumentDB/databaseAccounts/cc-project5-cosmos-database"

11 The command output should return the information available for the new role assignment:

{
	"id": "/subscriptions/abcdabcd-1234-abcd-1234-abcdabcdabcd/resourceGroups/cloud-shell-storage-westeurope/providers/Microsoft.DocumentDB/databaseAccounts/cc-project5-cosmos-database/sqlRoleAssignments/35b36284-edf1-4c8d-a2a5-f5002eeb4ae7",
	"name": "35b36284-edf1-4c8d-a2a5-f5002eeb4ae7",
	"principalId": "abcd1234-abcd-1234-abcd-abcd1234abcd",
	"resourceGroup": "cloud-shell-storage-westeurope",
	"roleDefinitionId": "/subscriptions/abcdabcd-1234-abcd-1234-abcdabcdabcd/resourceGroups/cloud-shell-storage-westeurope/providers/Microsoft.DocumentDB/databaseAccounts/cc-project5-cosmos-database/sqlRoleDefinitions/00000000-0000-0000-0000-000000000001",
	"scope": "/subscriptions/abcdabcd-1234-abcd-1234-abcdabcdabcd/resourceGroups/cloud-shell-storage-westeurope/providers/Microsoft.DocumentDB/databaseAccounts/cc-project5-cosmos-database",
	"type": "Microsoft.DocumentDB/databaseAccounts/sqlRoleAssignments"
}

12 Repeat steps no. 6 - 11 for each Azure Cosmos DB account that you want to configure, available in the selected subscription.

13 Repeat steps no. 3 – 12 for each Azure subscription created in your Microsoft Azure cloud account.

References

Azure Official Documentation
Security in Azure Cosmos DB
Use data plane role-based access control with Azure Cosmos DB for NoSQL

Azure Command Line Interface (CLI) Documentation
az account list
az account set
az cosmosdb list
az cosmosdb show
az cosmosdb sql role definition list
az cosmosdb sql role assignment list
az cosmosdb sql role assignment create

Publication date May 28, 2025

Audit

Using Azure CLI

Remediation / Resolution

Using Azure CLI

References

Related CosmosDB rules