Configure role-based access control in Azure Cosmos DB for MongoDB

APPLIES TO: MongoDB

This article is about role-based access control for data plane operations in Azure Cosmos DB for MongoDB.

If you're using management plane operations, see role-based access control applied to your management plane operations article.

Azure Cosmos DB for MongoDB exposes a built-in role-based access control (RBAC) system that lets you authorize your data requests with a fine-grained, role-based permission model. Users and roles reside within a database and are managed using the Azure CLI, Azure PowerShell, or Azure Resource Manager (ARM).

A resource is a collection or database to which we're applying access control rules.

Privileges are actions that can be performed on a specific resource. For example, "read access to collection xyz". Privileges are assigned to a specific role.

A role has one or more privileges. Roles are assigned to users (zero or more) to enable them to perform the actions defined in those privileges. Roles are stored within a single database.

Another column called userId has been added to the MongoRequests table in the Azure portal's diagnostics feature. This column identifies which user performed which data plan operation. The value in this column is empty when RBAC isn't enabled.

• find
• insert
• remove
• update

• changeStream

• createCollection
• createIndex
• dropCollection
• killCursors
• killAnyCursor

• dropDatabase
• dropIndex
• reIndex

• collStats
• dbStats
• listDatabases
• listCollections
• listIndexes

These roles already exist on every database and don't need to be created.

We recommend using the cmd when using Windows.

1. Make sure you have latest CLI version(not extension) installed locally. try az upgrade command.
2. Connect to your subscription.

az cloud set -n  AzureCloud
az login
az account set --subscription <your subscription ID>

3. Enable the RBAC capability on your existing API for MongoDB database account. You need to add the capability "EnableMongoRoleBasedAccessControl" to your database account. RBAC can also be enabled via the features tab in the Azure portal instead. If you prefer a new database account instead, create a new database account with the RBAC capability set to true.

az cosmosdb create -n <account_name> -g <azure_resource_group> --kind MongoDB --capabilities EnableMongoRoleBasedAccessControl

4. Create a database for users to connect to in the Azure portal.
5. Create an RBAC user with built-in read role.

az cosmosdb mongodb user definition create --account-name <YOUR_DB_ACCOUNT> --resource-group <YOUR_RG> --body {\"Id\":\"<YOUR_DB_NAME>.<YOUR_USERNAME>\",\"UserName\":\"<YOUR_USERNAME>\",\"Password\":\"<YOUR_PASSWORD>\",\"DatabaseName\":\"<YOUR_DB_NAME>\",\"CustomData\":\"Some_Random_Info\",\"Mechanisms\":\"SCRAM-SHA-256\",\"Roles\":[{\"Role\":\"read\",\"Db\":\"<YOUR_DB_NAME>\"}]}

from pymongo import MongoClient
client = MongoClient("mongodb://<YOUR_HOSTNAME>:10255/?ssl=true&replicaSet=globaldb&retrywrites=false&maxIdleTimeMS=120000", username="<YOUR_USER>", password="<YOUR_PASSWORD>", authSource='<YOUR_DATABASE>', authMechanism='SCRAM-SHA-256', appName="<YOUR appName FROM CONNECTION STRING IN AZURE PORTAL>")

connectionString = "mongodb://" + "<YOUR_USER>" + ":" + "<YOUR_PASSWORD>" + "@" + "<YOUR_HOSTNAME>" + ":10255/" + "<YOUR_DATABASE>" +"?ssl=true&retrywrites=false&replicaSet=globaldb&authmechanism=SCRAM-SHA-256&appname=@" + "<YOUR appName FROM CONNECTION STRING IN AZURE PORTAL>" + "@";
var client = await mongodb.MongoClient.connect(connectionString, { useNewUrlParser: true, useUnifiedTopology: true });

connectionString = "mongodb://" + "<YOUR_USER>" + ":" + "<YOUR_PASSWORD>" + "@" + "<YOUR_HOSTNAME>" + ":10255/" + "<YOUR_DATABASE>" +"?ssl=true&retrywrites=false&replicaSet=globaldb&authmechanism=SCRAM-SHA-256&appname=@" + "<YOUR appName FROM CONNECTION STRING IN AZURE PORTAL>" + "@";
MongoClientURI uri = new MongoClientURI(connectionString);
MongoClient client = new MongoClient(uri);

mongosh --authenticationDatabase <YOUR_DB> --authenticationMechanism SCRAM-SHA-256 "mongodb://<YOUR_USERNAME>:<YOUR_PASSWORD>@<YOUR_HOST>:10255/?ssl=true&replicaSet=globaldb&retrywrites=false&maxIdleTimeMS=120000"

connectionString = "mongodb://" + "<YOUR_USER>" + ":" + "<YOUR_PASSWORD>" + "@" + "<YOUR_HOSTNAME>" + ":10255/" + "?ssl=true&retrywrites=false&replicaSet=globaldb&authmechanism=SCRAM-SHA-256&appname=@" + "<YOUR appName FROM CONNECTION STRING IN AZURE PORTAL>" + "@"
+"&authSource=" +"<YOUR_DATABASE>";

The RBAC management commands will only work with newer versions of the Azure CLI installed. See the Quickstart above on how to get started.

az cosmosdb mongodb role definition create --account-name <account-name> --resource-group <resource-group-name> --body {\"Id\":\"test.My_Read_Only_Role101\",\"RoleName\":\"My_Read_Only_Role101\",\"Type\":\"CustomRole\",\"DatabaseName\":\"test\",\"Privileges\":[{\"Resource\":{\"Db\":\"test\",\"Collection\":\"test\"},\"Actions\":[\"insert\",\"find\"]}],\"Roles\":[]}

az cosmosdb mongodb role definition create --account-name <account-name> --resource-group <resource-group-name> --body role.json

{
	"Id": "test.My_Read_Only_Role101",
	"RoleName": "My_Read_Only_Role101",
	"Type": "CustomRole",
	"DatabaseName": "test",
	"Privileges": [{
		"Resource": {
			"Db": "test",
			"Collection": "test"
		},
		"Actions": ["insert", "find"]
	}],
	"Roles": []
}

az cosmosdb mongodb role definition update --account-name <account-name> --resource-group <resource-group-name> --body {\"Id\":\"test.My_Read_Only_Role101\",\"RoleName\":\"My_Read_Only_Role101\",\"Type\":\"CustomRole\",\"DatabaseName\":\"test\",\"Privileges\":[{\"Resource\":{\"Db\":\"test\",\"Collection\":\"test\"},\"Actions\":[\"insert\",\"find\"]}],\"Roles\":[]}

az cosmosdb mongodb role definition update --account-name <account-name> --resource-group <resource-group-name> --body role.json

{
	"Id": "test.My_Read_Only_Role101",
	"RoleName": "My_Read_Only_Role101",
	"Type": "CustomRole",
	"DatabaseName": "test",
	"Privileges": [{
		"Resource": {
			"Db": "test",
			"Collection": "test"
		},
		"Actions": ["insert", "find"]
	}],
	"Roles": []
}

az cosmosdb mongodb role definition list --account-name <account-name> --resource-group <resource-group-name>

az cosmosdb mongodb role definition exists --account-name <account-name> --resource-group <resource-group-name> --id test.My_Read_Only_Role

az cosmosdb mongodb role definition delete --account-name <account-name> --resource-group <resource-group-name> --id test.My_Read_Only_Role

az cosmosdb mongodb user definition create --account-name <account-name> --resource-group <resource-group-name> --body {\"Id\":\"test.myName\",\"UserName\":\"myName\",\"Password\":\"pass\",\"DatabaseName\":\"test\",\"CustomData\":\"Some_Random_Info\",\"Mechanisms\":\"SCRAM-SHA-256\",\"Roles\":[{\"Role\":\"My_Read_Only_Role101\",\"Db\":\"test\"}]}

az cosmosdb mongodb user definition create --account-name <account-name> --resource-group <resource-group-name> --body user.json

{
	"Id": "test.myName",
	"UserName": "myName",
	"Password": "pass",
	"DatabaseName": "test",
	"CustomData": "Some_Random_Info",
	"Mechanisms": "SCRAM-SHA-256",
	"Roles": [{
		"Role": "My_Read_Only_Role101",
		"Db": "test"
	}]
}

To update the user's password, send the new password in the password field.

az cosmosdb mongodb user definition update --account-name <account-name> --resource-group <resource-group-name> --body {\"Id\":\"test.myName\",\"UserName\":\"myName\",\"Password\":\"pass\",\"DatabaseName\":\"test\",\"CustomData\":\"Some_Random_Info\",\"Mechanisms\":\"SCRAM-SHA-256\",\"Roles\":[{\"Role\":\"My_Read_Only_Role101\",\"Db\":\"test\"}]}

az cosmosdb mongodb user definition update --account-name <account-name> --resource-group <resource-group-name> --body user.json

{
	"Id": "test.myName",
	"UserName": "myName",
	"Password": "pass",
	"DatabaseName": "test",
	"CustomData": "Some_Random_Info",
	"Mechanisms": "SCRAM-SHA-256",
	"Roles": [{
		"Role": "My_Read_Only_Role101",
		"Db": "test"
	}]
}

az cosmosdb mongodb user definition list --account-name <account-name> --resource-group <resource-group-name>

az cosmosdb mongodb user definition exists --account-name <account-name> --resource-group <resource-group-name> --id test.myName

az cosmosdb mongodb user definition delete --account-name <account-name> --resource-group <resource-group-name> --id test.myName

• The number of users and roles you can create must equal less than 10,000.
• The commands listCollections, listDatabases, killCursors, and currentOp are excluded from RBAC.
• Users and Roles across databases aren't supported.
• A user's password can only be set/reset by through the Azure CLI / Azure PowerShell.
• Configuring Users and Roles is only supported through Azure CLI / PowerShell.
• Disabling primary/secondary key authentication isn't supported. We recommend rotating your keys to prevent access when enabling RBAC.
• RBAC policies for Cosmos DB for Mongo DB RU won't be automatically reinstated following a restore operation. You'll be required to reconfigure these policies after the restoration process is complete.

Azure portal support for role management isn't available. However, RBAC can be enabled via the features tab in the Azure portal.

Update the user definition with the new password.

Versions 3.6 and higher support RBAC.

• Learn more about RBAC for Azure Cosmos DB management.