Azure Cosmos DB 中的 Azure 角色型存取控制Azure role-based access control in Azure Cosmos DB

適用於:適用於 MongoDB 的 SQL API Cassandra API Gremlin API Table API Azure Cosmos DB API

注意

本文說明 Azure Cosmos DB 中管理平面作業的角色型存取控制。This article is about role-based access control for management plane operations in Azure Cosmos DB. 如果您使用資料平面作業,請參閱針對套用至資料平面作業的角色型存取控制 AZURE COSMOS DB RBACIf you are using data plane operations, see Azure Cosmos DB RBAC for role-based access control applied to your data plane operations.

Azure Cosmos DB 為 Azure Cosmos DB 中常見的管理案例,提供內建的 Azure 角色型存取控制 (Azure RBAC) 。Azure Cosmos DB provides built-in Azure role-based access control (Azure 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 Backup 運算子Cosmos Backup Operator 可以針對已啟用定期備份的資料庫或容器,提交 Azure 入口網站的還原要求。Can submit a restore request for Azure portal for a periodic backup enabled database or a container. 可以修改 Azure 入口網站的備份間隔和保留期。Can modify the backup interval and retention on the Azure portal. 無法存取任何資料或使用資料總管。Cannot access any data or use Data Explorer.
CosmosRestoreOperatorCosmosRestoreOperator 可以針對具有連續備份模式 Azure Cosmos DB 帳戶執行還原動作。Can perform restore action for Azure Cosmos DB account with continuous backup mode.
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 中的 Azure RBAC 支援僅適用于控制平面作業。Azure 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 資源上的 azure 角色型存取控制。The Access control (IAM) pane in the Azure portal is used to configure Azure 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. 下列螢幕擷取畫面顯示在) 中使用存取控制 (IAM Azure 入口網站 Active Directory 整合 (Azure RBAC) :The following screenshot shows Active Directory integration (Azure 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 至資源的屬性 databaseAccountsTo 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 Resource Manager 範本的基本範例。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
        }
    }
}

重要

Redploying 此屬性時,請確定您包含帳戶和子資源的其他屬性。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