Azure Cosmos DB 中基于角色的访问控制Role-based access control in Azure Cosmos DB

适用于: SQL API Cassandra API Gremlin API 表 API Azure Cosmos DB API for MongoDB

Azure Cosmos DB 为 Azure Cosmos DB 中的常见管理方案提供内置的基于角色的访问控制 (RBAC)。Azure Cosmos DB provides built-in role-based access control (RBAC) for common management scenarios in Azure Cosmos DB. 在 Azure Active Directory 中创建了配置文件的个人可将这些 Azure 角色分配给用户、组、服务主体或托管标识,以授予或拒绝对 Azure Cosmos DB 中的资源和操作的访问权限。An individual who has a profile in Azure Active Directory can assign these Azure roles to users, groups, service principals, or managed identities to grant or deny access to resources and operations on Azure Cosmos DB resources. 角色分配范围仅限控制平面访问,包括对 Azure Cosmos 帐户、数据库、容器和套餐(吞吐量)的访问。Role assignments are scoped to control-plane access only, which includes access to Azure Cosmos accounts, databases, containers, and offers (throughput).

内置角色Built-in roles

下面是 Azure Cosmos DB 支持的内置角色:The following are the built-in roles supported by Azure Cosmos DB:

内置角色Built-in role 说明Description
DocumentDB 帐户参与者DocumentDB Account Contributor 可管理 Azure Cosmos DB 帐户。Can manage Azure Cosmos DB accounts.
Cosmos DB 帐户读取者Cosmos DB Account Reader 可以读取 Azure Cosmos DB 帐户数据。Can read Azure Cosmos DB account data.
Cosmos 备份操作员Cosmos Backup Operator 可以提交对 Azure Cosmos 数据库或容器的还原请求Can submit restore request for an Azure Cosmos database or a container. 无法访问任何数据或使用数据资源管理器。Cannot access any data or use Data Explorer.
Cosmos DB 操作员Cosmos DB Operator 可预配 Azure Cosmos 帐户、数据库和容器。Can provision Azure Cosmos accounts, databases, and containers. 无法访问任何数据或使用数据资源管理器。Cannot access any data or use Data Explorer.

重要

Azure Cosmos DB 中的 RBAC 仅支持适用于控制平面操作。RBAC support in Azure Cosmos DB applies to control plane operations only. 使用主密钥或资源令牌保护数据平面操作。Data plane operations are secured using primary keys or resource tokens. 有关详细信息,请参阅保护对 Azure Cosmos DB 中数据的访问To learn more, see Secure access to data in Azure Cosmos DB

标识和访问管理 (IAM)Identity and access management (IAM)

Azure 门户中的“访问控制(IAM)”窗格用于针对 Azure Cosmos 资源配置基于角色的访问控制。The Access control (IAM) pane in the Azure portal is used to configure role-based access control on Azure Cosmos resources. 角色将应用到 Active Directory 中的用户、组、服务主体和托管标识。The roles are applied to users, groups, service principals, and managed identities in Active Directory. 对于个人和组,可使用内置角色或自定义角色。You can use built-in roles or custom roles for individuals and groups. 以下屏幕截图显示在 Azure 门户中使用访问控制 (IAM) 的 Active Directory 集成 (RBAC):The following screenshot shows Active Directory integration (RBAC) using access control (IAM) in the Azure portal:

Azure 门户中的访问控制 (IAM) - 演示数据库安全性

自定义角色Custom roles

除内置角色以外,用户还可以在 Azure 中创建自定义角色,并将这些角色应用到其 Active Directory 租户内的所有订阅中的服务主体。In addition to the built-in roles, users may also create custom roles in Azure and apply these roles to service principals across all subscriptions within their Active Directory tenant. 自定义角色可让用户使用一组自定义的资源提供程序操作来创建 Azure 角色定义。Custom roles provide users a way to create Azure role definitions with a custom set of resource provider operations. 若要了解可以使用哪些操作来为 Azure Cosmos DB 生成自定义角色,请参阅 Azure Cosmos DB 资源提供程序操作To learn which operations are available for building custom roles for Azure Cosmos DB see, Azure Cosmos DB resource provider operations

提示

如果自定义角色需要访问存储在 Cosmos DB 中的数据或要在 Azure 门户中使用数据资源管理器,则这些角色必须具有 Microsoft.DocumentDB/databaseAccounts/listKeys/* 操作。Custom roles that need to access data stored within Cosmos DB or use Data Explorer in the Azure portal must have Microsoft.DocumentDB/databaseAccounts/listKeys/* action.

阻止从 Azure Cosmos DB SDK 进行更改Preventing changes from the Azure Cosmos DB SDKs

可以锁定 Azure Cosmos DB 资源提供程序,以防止从使用帐户密钥连接的客户端(即通过 Azure Cosmos SDK 连接的应用程序)对资源做出任何更改。The Azure Cosmos DB resource provider can be locked down to prevent any changes to resources from a client connecting using the account keys (that is applications connecting via the Azure Cosmos SDK). 其中也包括从 Azure 门户做出的更改。This also includes changes made from the Azure portal. 对于需要更高程度的控制和生产环境管理的用户,此功能可能是理想的。This feature may be desirable for users who want higher degrees of control and governance for production environments. 阻止从 SDK 进行更改还会启用资源锁和控制平面操作诊断日志等功能。Preventing changes from the SDK also enables features such as resource locks and diagnostic logs for control plane operations. 将阻止通过 Azure Cosmos DB SDK 连接的客户端更改 Azure Cosmos 帐户、数据库、容器和吞吐量的任何属性。The clients connecting from Azure Cosmos DB SDK will be prevented from changing any property for the Azure Cosmos accounts, databases, containers, and throughput. 涉及对 Cosmos 容器本身进行数据读取和写入的操作不会受到影响。The operations involving reading and writing data to Cosmos containers themselves are not impacted.

此功能启用时,对任何资源的更改都只能由具有正确 Azure 角色和 Azure Active Directory 凭据(包括托管服务标识)的用户来进行。When this feature is enabled, changes to any resource can only be made from a user with the right Azure role and Azure Active Directory credentials including Managed Service Identities.

警告

启用此功能可能对应用程序造成影响。Enabling this feature can have impact on your application. 确保在启用前了解此影响。Make sure that you understand the impact before enabling it.

启用前的核对清单Check list before enabling

此设置将阻止从使用帐户密钥连接的任何客户端(包括任何 Cosmos DB SDK)、通过帐户密钥连接的任何工具或 Azure 门户对任何 Cosmos 资源做出任何更改。This setting will prevent any changes to any Cosmos resource from any client connecting using account keys including any Cosmos DB SDK, any tools that connect via account keys, or from the Azure portal. 若要防止在启用此功能后应用程序出现问题或错误,请在启用此功能前检查应用程序或 Azure 门户用户是否执行以下任何操作,包括:To prevent issues or errors from applications after enabling this feature, check if applications or Azure portal users perform any of the following actions before enabling this feature, including:

  • 更改 Cosmos 帐户,包括更改任何属性或者添加或删除区域。Any change to the Cosmos account including any properties or adding or removing regions.

  • 创建、删除子资源(例如数据库和容器)。Creating, deleting child resources such as databases and containers. 其中包括用于其他 API 的资源,例如 Cassandra、MongoDB、Gremlin 和表资源。This includes resources for other APIs such as Cassandra, MongoDB, Gremlin, and table resources.

  • 更新数据库或容器级别资源的吞吐量。Updating throughput on database or container level resources.

  • 修改容器属性,包括索引策略、TTL 和唯一键。Modifying container properties including index policy, TTL and unique keys.

  • 修改存储过程、触发器或用户定义的函数。Modifying stored procedures, triggers or user-defined functions.

如果应用程序(或者用户通过 Azure 门户)执行这些操作中的任何一种,则需要将它们迁移,以通过 ARM 模板PowerShellAzure CLI、REST 或 Azure 管理库来执行。If your applications (or users via Azure portal) perform any of these actions they will need to be migrated to execute via ARM Templates, PowerShell, Azure CLI, REST, or Azure Management Library. 请注意,可使用多种语言进行 Azure 管理。Note that Azure Management is available in multiple languages.

通过 ARM 模板进行设置Set via ARM Template

若要使用 ARM 模板设置此属性,请更新现有模板或为当前部署导出新模板,然后,将 "disableKeyBasedMetadataWriteAccess": true 包含到 databaseAccounts 资源的属性。To set this property using an ARM template, update your existing template or export a new template for your current deployment, then include the "disableKeyBasedMetadataWriteAccess": true to the properties for the databaseAccounts resources. 下面是具有此属性设置的 Azure 资源管理器模板的基本示例。Below is a basic example of an Azure Resource Manager template with this property setting.

{
    {
      "type": "Microsoft.DocumentDB/databaseAccounts",
      "name": "[variables('accountName')]",
      "apiVersion": "2020-04-01",
      "location": "[parameters('location')]",
      "kind": "GlobalDocumentDB",
      "properties": {
        "consistencyPolicy": "[variables('consistencyPolicy')[parameters('defaultConsistencyLevel')]]",
        "locations": "[variables('locations')]",
        "databaseAccountOfferType": "Standard",
        "disableKeyBasedMetadataWriteAccess": true
        }
    }
}

重要

在使用此属性进行部署时,请确保包含用于帐户和子资源的其他属性。Make sure you include the other properties for your account and child resources when redploying with this property. 请勿按原样部署此模板,否则它将重置所有的帐户属性。Do not deploy this template as is or it will reset all of your account properties.

通过 Azure CLI 进行设置Set via Azure CLI

若要启用 Azure CLI,请使用以下命令:To enable using Azure CLI, use the command below:

az cosmosdb update  --name [CosmosDBAccountName] --resource-group [ResourceGroupName]  --disable-key-based-metadata-write-access true

通过 PowerShell 进行设置Set via PowerShell

若要启用 Azure PowerShell,请使用以下命令:To enable using Azure PowerShell, use the command below:

Update-AzCosmosDBAccount -ResourceGroupName [ResourceGroupName] -Name [CosmosDBAccountName] -DisableKeyBasedMetadataWriteAccess true

后续步骤Next steps