Security glossary for Azure Cosmos DB for NoSQL

APPLIES TO: NoSQL

This article includes a glossary of common terminology used in this security guide for Azure Cosmos DB for NoSQL.

Role-based access control

Role-based access control refers to a method to manage access to resources in Azure. This method is based on specific identities being assigned roles that manage what level of access they have to one or more resources. Role-based access control provides a flexible system of fine-grained access management that ensures identities only have the least privileged level of access they need to perform their task.

For more information, see role-based access control overview.

Identity/Principal

Identities refer to objects within Microsoft Entra that represents some entity that might need a level of access to your system. In the context of Azure and Microsoft Entra, identities could refer to one of the following types of entities:

For more information, see identity fundamentals.

Role

Roles are the primary units of enforcing access and permissions. You assign a role to an identity and the definition of the role dictates what level of access that identity can have. The scope of the assignment dictates what exactly the identity has access to.

Azure has a large set of built-in roles that you can use to grant access to various resources. Consider this example:

In this example, you're assigned the CosmosBackupOperator role for a specific resource group. This assignment gives you access to either perform the backup or restore actions on any Azure Cosmos DB account within that resource group.

For more information, see built-in Azure roles

Role definition

A role definition is a JSON object that contains the list of control plane and data plane actions that are allowed and aren't allowed. Consider this truncated example from the CosmosRestoreOperator built-in role:

{
  "roleName": "CosmosRestoreOperator",
  "type": "Microsoft.Authorization/roleDefinitions",
  ...
  "permissions": [
    {
      "actions": [
        "Microsoft.DocumentDB/locations/restorableDatabaseAccounts/restore/action",
        "Microsoft.DocumentDB/locations/restorableDatabaseAccounts/*/read",
        "Microsoft.DocumentDB/locations/restorableDatabaseAccounts/read"
      ],
      "notActions": [],
      "dataActions": [],
      "notDataActions": []
    }
  ],
  ...
}

In this definition, an identity assigned this role can perform a restore action. Once the restoration operation is complete, the identity then can read various resources to validate that the restore was successful. We can determine that it can read these resources because of the * (wildcard) operator for read.

For more information, see role definition concepts.

Role assignment

A role assignment grants an identity access to a specific Azure resource. Role assignments consist of the following components:

For more information, see role assignment concepts.

Actions

Actions define what specific permissions a role has for a target resource. Actions are strings that typically include the resource type and a descriptive name detailing what permissions the action grants. Here are a few common examples:

Actions can also contain * (wildcard) characters so you don't have to manually detail every specific subpermission. Here's a few examples of actions with wildcards:

Actions are separated into control plane and data plane. You must separately define actions on control plane resources and actions that can influence data. In a role definition, control plane actions use the actions property and data plane actions are within the dataActions property. You can also define actions that an identity can’t perform using the respective notActions and notDataActions properties.

For more information, see control and data actions.

Least privilege

The concept of "least privilege" refers to an operational best practice to ensure that all users only have the minimal level of access they need to perform their task or job. For example, an application that reads data from a database would only need read access to the data store. If that application had read and write access to the data store, a few things could happen including, but not limited to:

• The application could errantly destroy data
• An unauthorized user could get access to the application's credentials and modify data

Following the practice of least privilege ensures that any potential data breaches are limited in scope. This practice maximises operational security while allowing users to remain effective.

For more information, see recommended least privileged roles by task.

Control plane

Control plane access refers to the ability to manage resources for an Azure service without managing data. For example, Azure Cosmos DB control plane access could include the ability to:

• Read all account and resource metadata
• Read and regenerate account keys and connection strings
• Perform account backups and restore
• Start and track data transfer jobs
• Manage databases and containers
• Modify account properties

Data plane

Data plane access refers to the ability to read and write data within an Azure service without the ability to manage resources in the account. For exmaple, Azure Cosmos DB data plane access could include the ability to:

• Read some account and resource metadata
• Create, read, update, patch, and delete items
• Execute NoSQL queries
• Read from a container's change feed
• Execute stored procedures
• Manage conflicts in the conflict feed

Portable authentication

In development, it's common to write two sets of distinct authentication logic for local development and production instances. With the Azure SDK, you can write your logic using a single technique and expect the authentication code to work seamlessly in development and production.

The Azure Identity client library is available in multiple programming languages as part of the Azure SDK. Using this library, you can create a DefaultAzureCredential object that intelligently walks through multiple options, in order, to find the right credential based on your environment. These authentication options include (in order):

1. Client secret or certificate stored as an environment variable
2. Microsoft Entra Workload ID
3. User-assigned or system-assigned managed identity
4. Azure credentials derived from Visual Studio's settings
5. Credentials used in Visual Studio Code's Azure Account extension
6. Current credentials from Azure CLI
7. Current credentials from Azure PowerShell
8. Current credentials from Azure Developer CLI
9. An interactive session that launches the system's browser for sign in

Each modern Azure SDK library supports a constructor for their respective client objects or classes that accept a DefaultAzureCredential instance or its base type.

Unique identifier

Each identity in Microsoft Entra has a unique identifier. You sometimes see this unique identifier referred to as the id, objectId, or principalId. When creating role assignments, you need the unique identifier for the identity that you with to use with the assignment.

Scope

When you assign a role, you must decide what Azure resources or groups to grant access to. The scope of a role assignment defines the level at which an assignment is made.

For example:

• A single resource scope applies permissions to just that singular resource
• A scope set at the resource group level applies the permissions to all relevant resources within the group
• Scopes at the management group or subscription levels apply to all child groups and resources

When you assign a role in Azure role-based access control, it's ideal to set the scope of that assignment to include as little resources as required for your workload. For example, you can set the scope of an assignment to a resource group. That resource group scope includes all Azure Cosmos DB resources within the resource group:

/subscriptions/<subscription-id>/resourcegroups/<resource-group-name>

Alternatively, you can set the scope to a single Azure resource and make your assignment of permissions more granular and narrow. In this example, the provider and name of the Azure Cosmos DB resource are used to narrow the scope:

/subscriptions/<subscription-id>/resourcegroups/<resource-group-name>/providers/Microsoft.DocumentDB/databaseAccounts/<account-name>

For more information, see Azure role-based access control scope.

Scope (Azure Cosmos DB native)

In Azure Cosmos DB's native implementation of role-based access control, scope refers to the granularity of resources within an account for which you want permission applied.

At the highest level, you can scope a data plane role-based access control assignment to the entire account using the largest scope. This scope includes all databases and containers within the account:

/subscriptions/<subscription-id>/resourcegroups/<resource-group-name>/providers/Microsoft.DocumentDB/databaseAccounts/<account-name>/

Or, you can scope your data plane role assignment to a specific database:

/subscriptions/<subscription-id>/resourcegroups/<resource-group-name>/providers/Microsoft.DocumentDB/databaseAccounts/<account-name>/dbs/<database-name>

Finally, you can scope the assignment to a single container, the most granular scope:

/subscriptions/<subscription-id>/resourcegroups/<resource-group-name>/providers/Microsoft.DocumentDB/databaseAccounts/<account-name>/dbs/<database-name>/colls/<container-name>

Next step