Edit

Share via

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

  • Applies to: ✅ MongoDB

Azure Cosmos DB for MongoDB provides a built-in role-based access control system for data plane operations. Use role-based access control to authorize data requests with fine-grained, role-based permissions. This guide shows you how to enable role-based access control, create roles and users, and authenticate with supported drivers.

Prerequisites

  • An Azure subscription
  • An Azure Cosmos DB for MongoDB account (version 3.6 or higher)
  • Latest version of Azure CLI

Enable role-based access control

Enable role-based access control on your Azure Cosmos DB for MongoDB account.

  1. Sign in to Azure CLI.

    az login

  2. Enable the role-based access control capability on your database account.

    az cosmosdb create \
    --resource-group "<resource-group-name>" \
    --name "<account-name>" \
    --kind "MongoDB" \
    --capabilities "EnableMongoRoleBasedAccessControl"

    Tip

    You can also enable role-based access control from the Features tab in the Azure portal.

  3. Create a database for users to connect to in the Azure portal.

Create roles and users

Define custom roles and users to control access to your database account.

  1. Create a role definition.

    az cosmosdb mongodb role definition create \
    --resource-group "<resource-group-name>" \
    --account-name "<account-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\":[]}

    Tip

    Alternatively, use a JSON file:

    az cosmosdb mongodb role definition create \
   --resource-group "<resource-group-name>" \
   --account-name "<account-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": []
}

  2. Create a user definition with a role assignment.

    az cosmosdb mongodb user definition create \
    --resource-group "<resource-group-name>" \
    --account-name "<account-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\"}]}

    Tip

    Alternatively, use a JSON file:

    az cosmosdb mongodb role definition create \
   --resource-group "<resource-group-name>" \
   --account-name "<account-name>" \
   --body @role.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"
  }]
}

Authenticate with drivers

Connect to your database using supported drivers and role-based access control credentials.

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>"
)

Perform common operations

Now, perform some common operations for role-based access control features in Azure Cosmos DB for MongoDB.

  1. Use the following command to display all role definitions.

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

  2. Verify the existence of a role by its ID.

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

  3. Remove a role definition using its ID.

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

  4. Display all user definitions.

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

  5. Verify the existence of a user by its ID.

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

  6. Remove a user definition using its ID.

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

Related content