Use data plane role-based access control with Azure Cosmos DB for NoSQL
Article
APPLIES TO:
NoSQL
Diagram of the sequence of the deployment guide including these locations, in order: Overview, Concepts, Prepare, Role-based access control, Network, and Reference. The 'Role-based access control' location is currently highlighted.
Tip
Visit our new Samples Gallery for the latest samples for building new apps
This article walks through the steps to grant an identity access to manage data in an Azure Cosmos DB for NoSQL account.
Important
The steps in this article only cover data plane access to perform operations on individual items and run queries. To learn how to manage databases and containers for the control plane, see grant control plane role-based access.
If you prefer to run CLI reference commands locally, install the Azure CLI. If you're running on Windows or macOS, consider running Azure CLI in a Docker container. For more information, see How to run the Azure CLI in a Docker container.
If you're using a local installation, sign in to the Azure CLI by using the az login command. To finish the authentication process, follow the steps displayed in your terminal. For other sign-in options, see Sign in with the Azure CLI.
When you're prompted, install the Azure CLI extension on first use. For more information about extensions, see Use extensions with the Azure CLI.
Run az version to find the version and dependent libraries that are installed. To upgrade to the latest version, run az upgrade.
List all of the role definitions associated with your Azure Cosmos DB for NoSQL account using az cosmosdb sql role definition list. Review the output and locate the role definition named Cosmos DB Built-in Data Contributor. 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.
az cosmosdb sql role definition list \
--resource-group "<name-of-existing-resource-group>" \
--account-name "<name-of-existing-nosql-account>"
In this example, the id value would be /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/msdocs-identity-example/providers/Microsoft.DocumentDB/databaseAccounts/msdocs-identity-example-nosql/sqlRoleDefinitions/00000000-0000-0000-0000-000000000002. This example uses fictitious data and your identifier would be distinct from this example.
Use Get-AzCosmosDBSqlRoleDefinition to list all of the role definitions associated with your Azure Cosmos DB for NoSQL account. Review the output and locate the role definition named Cosmos DB Built-in Data Contributor. 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.
Id : /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/msdocs-identity-example/providers/Microsoft.DocumentDB/databaseAccounts/msdocs-identity-example-nosql/sqlRoleDefinitions/00000000-0000-0000-0000-000000000002
RoleName : Cosmos DB Built-in Data Contributor
Type : BuiltInRole
AssignableScopes : {/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/msdocs-identity-example/providers/Microsoft.DocumentDB/databaseAccountsmsdocs-identity-example-nosql}
Permissions.DataActions : {Microsoft.DocumentDB/databaseAccounts/readMetadata, Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/*, Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/items/*}
Permissions.NotDataActions :
Note
In this example, the Id value would be /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/msdocs-identity-example/providers/Microsoft.DocumentDB/databaseAccounts/msdocs-identity-example-nosql/sqlRoleDefinitions/00000000-0000-0000-0000-000000000002. This example uses fictitious data and your identifier would be distinct from this example. However, the identifier (00000000-0000-0000-0000-000000000002) is unique across all role definitions in your account.
Important
Creating a new data plane role definition requires these control plane permissions:
Azure Cosmos DB for NoSQL's native role-based access control doesn't support the notDataActions property. Any action that is not specified as an allowed dataAction is excluded automatically.
Create a new JSON file named role-definition.json. In this file, create a resource definition specifying the data actions listed here:
az cosmosdb sql role definition list \
--resource-group "<name-of-existing-resource-group>" \
--account-name "<name-of-existing-nosql-account>"
Review the output from the previous command. Locate the role definition you just created named Azure Cosmos DB for NOSQL Data Plane Owner. 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.
In this example, the id value would be /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/msdocs-identity-example/providers/Microsoft.DocumentDB/databaseAccounts/msdocs-identity-example-nosql/sqlRoleDefinitions/bbbbbbbb-1111-2222-3333-cccccccccccc. This example uses fictitious data and your identifier would be distinct from this example.
Create a new Bicep file to define your role definition. Name the file data-plane-role-definition.bicep. Add these dataActions to the definition:
Can perform any operation on items with containers
metadata description = 'Create RBAC definition for data plane access to Azure Cosmos DB for NoSQL.'
@description('Name of the Azure Cosmos DB for NoSQL account.')
param accountName string
@description('Name of the role definition.')
param roleDefinitionName string = 'Azure Cosmos DB for NoSQL Data Plane Owner'
resource account 'Microsoft.DocumentDB/databaseAccounts@2024-05-15' existing = {
name: accountName
}
resource definition 'Microsoft.DocumentDB/databaseAccounts/sqlRoleDefinitions@2024-05-15' = {
name: guid(account.id, roleDefinitionName)
parent: account
properties: {
roleName: roleDefinitionName
type: 'CustomRole'
assignableScopes: [
account.id
]
permissions: [
{
dataActions: [
'Microsoft.DocumentDB/databaseAccounts/readMetadata'
'Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/*'
'Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/items/*'
]
}
]
}
}
output definitionId string = definition.id
Create a new Bicep parameters file named data-plane-role-definition.bicepparam. In this parameters file, assign the name of your existing Azure Cosmos DB for NoSQL account to the accountName parameter.
using './data-plane-role-definition.bicep'
param accountName = '<name-of-existing-nosql-account>'
Review the output from the previous command. Locate the role definition you just created named Azure Cosmos DB for NOSQL Data Plane Owner. 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.
Id : /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/msdocs-identity-example/providers/Microsoft.DocumentDB/databaseAccounts/msdocs-identity-example-nosql/sqlRoleDefinitions/bbbbbbbb-1111-2222-3333-cccccccccccc
RoleName : Azure Cosmos DB for NoSQL Data Plane Owner
Type : CustomRole
AssignableScopes : {/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/msdocs-identity-example/providers/Microsoft.DocumentDB/databaseAccounts/msdocs-identity-example-nosql}
Permissions.DataActions : {Microsoft.DocumentDB/databaseAccounts/readMetadata, Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/items/*, Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/*}
Permissions.NotDataActions :
Note
In this example, the Id value would be /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/msdocs-identity-example/providers/Microsoft.DocumentDB/databaseAccounts/msdocs-identity-example-nosql/sqlRoleDefinitions/bbbbbbbb-1111-2222-3333-cccccccccccc. This example uses fictitious data and your identifier would be distinct from this example.
Assign role to identity
Now, assign the newly defined role to an identity so that your applications can access data in Azure Cosmos DB for NoSQL.
Important
Creating a new data plane role assignment requires these control plane permissions:
In this example, the id value would be /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/msdocs-identity-example/providers/Microsoft.DocumentDB/databaseAccounts/msdocs-identity-example-nosql. This example uses fictitious data and your identifier would be distinct from this example.
Assign the new role using az cosmosdb sql role assignment create. Use the previously recorded role definition identifiers to the --role-definition-id argument, and the unique identifier for your identity to the --principal-id argument. Finally, use your account's identifier for the --scope argument.
Use az cosmosdb sql role assignment list to list all role assignments for your Azure Cosmos DB for NoSQL account. Review the output to ensure your role assignment was created.
az cosmosdb sql role assignment list \
--resource-group "<name-of-existing-resource-group>" \
--account-name "<name-of-existing-nosql-account>"
Create a new Bicep file to define your role assignment. Name the file data-plane-role-assignment.bicep.
metadata description = 'Assign RBAC role for data plane access to Azure Cosmos DB for NoSQL.'
@description('Name of the Azure Cosmos DB for NoSQL account.')
param accountName string
@description('Id of the role definition to assign to the targeted principal in the context of the account.')
param roleDefinitionId string
@description('Id of the identity/principal to assign this role in the context of the account.')
param identityId string
resource account 'Microsoft.DocumentDB/databaseAccounts@2024-05-15' existing = {
name: accountName
}
resource assignment 'Microsoft.DocumentDB/databaseAccounts/sqlRoleAssignments@2024-05-15' = {
name: guid(roleDefinitionId, identityId, account.id)
parent: account
properties: {
principalId: identityId
roleDefinitionId: roleDefinitionId
scope: account.id
}
}
output assignmentId string = assignment.id
Create a new Bicep parameters file named data-plane-role-assignment.bicepparam. In this parameters file, assign the name of your existing Azure Cosmos DB for NoSQL account to the accountName parameter, the previously recorded role definition identifiers to the roleDefinitionId parameter, and the unique identifier for your identity to the identityId parameter.
Deploy the Bicep template using az deployment group create.
az deployment group create \
--resource-group "<name-of-existing-resource-group>" \
--parameters data-plane-role-assignment.bicepparam \
--template-file data-plane-role-assignment.bicep
Repeat these steps to grant access to the account from any other identities you would like to use.
Tip
You can repeat these steps for as many identities as you'd like. Typically, these steps are at least repeated to allow developers access to an account using their human identity and to allow applications access using a managed identity.
$parameters = @{
ResourceGroupName = "<name-of-existing-resource-group>"
Name = "<name-of-existing-nosql-account>"
}
Get-AzCosmosDBAccount @parameters | Select -Property Id
Observe the output of the previous command. Record the value of the Id property for this account as it is required to use in the next step.
Id
--
/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/msdocs-identity-example/providers/Microsoft.DocumentDB/databaseAccounts/msdocs-identity-example-nosql
Note
In this example, the Id value would be /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/msdocs-identity-example/providers/Microsoft.DocumentDB/databaseAccounts/msdocs-identity-example-nosql. This example uses fictitious data and your identifier would be distinct from this example.
Use New-AzCosmosDBSqlRoleAssignment to assign the new role. Use the previously recorded role definition identifiers to the RoleDefinitionId parameter, and the unique identifier for your identity to the PrincipalId parameter. Finally, use your account's identifier for the Scope parameter.
List all role assignments for your Azure Cosmos DB for NoSQL account using Get-AzCosmosDBSqlRoleAssignment. Review the output to ensure your role assignment was created.
using Azure.Core;
using Azure.Identity;
using Microsoft.Azure.Cosmos;
string endpoint = "<account-endpoint>";
TokenCredential credential = new DefaultAzureCredential();
CosmosClient client = new(endpoint, credential);