Azure Cosmos DB 中的角色型存取控制
適用於：
NoSQL MongoDB Cassandra Gremlin 表
注意
本文是關於 Azure Cosmos DB 中管理平面作業的角色型訪問控制。 如果您使用數據平面作業，則會使用主鍵、資源令牌或 Azure Cosmos DB RBAC 來保護數據。
若要深入瞭解適用於 NoSQL 的 API 中套用至數據平面作業的角色型訪問控制，請參閱 保護數據和Azure Cosmos DB RBAC 的存取權文章。 如需適用於 MongoDB 的 Azure Cosmos DB API，請參閱 適用於 MongoDB 的 API 中的數據平面 RBAC。
Azure Cosmos DB 針對 Azure Cosmos DB 中的常見管理案例，提供內建的 Azure 角色型存取控制 （Azure RBAC）。 在 Microsoft Entra ID 中擁有配置檔的個人可以將這些 Azure 角色指派給使用者、群組、服務主體或受控識別，以授與或拒絕 Azure Cosmos DB 資源上資源和作業的存取權。 角色指派的範圍僅限於控制平面存取，包括存取 Azure Cosmos DB 帳戶、資料庫、容器和供應專案（輸送量）。
內建角色
以下是 Azure Cosmos DB 支援的內建角色：
| 內建角色 | 說明 |
|---|---|
| DocumentDB 帳戶參與者 | 可管理 Azure Cosmos DB 帳戶。 |
| Cosmos DB 帳戶讀取者角色 | 可讀取 Azure Cosmos DB 帳戶資料。 |
| CosmosBackupOperator | 可以在 Azure 入口網站 中提交還原要求，以取得已啟用定期備份的資料庫或容器。 可以在 Azure 入口網站 中修改備份間隔和保留期。 無法存取任何數據或使用數據總管。 |
| CosmosRestoreOperator | 可針對連續備份模式的 Azure Cosmos DB 帳戶執行還原動作。 |
| Cosmos DB 運算符 | 可以布建 Azure Cosmos DB 帳戶、資料庫和容器。 無法存取任何數據或使用數據總管。 |
身分識別與存取權管理 (IAM)
Azure 入口網站 中的 [訪問控制 （IAM）] 窗格可用來設定 Azure Cosmos DB 資源上的 Azure 角色型存取控制。 角色會套用至 Active Directory 中的使用者、群組、服務主體和受控識別。 您可以針對個人和群組使用內建角色或自定義角色。 下列螢幕快照顯示使用存取控制的 Active Directory 整合 （Azure RBAC） Azure 入口網站：
自訂角色
除了內建角色之外，使用者也可以在 Azure 中建立 自定義角色 ，並將這些角色套用至其 Active Directory 租使用者內所有訂用帳戶的服務主體。 自訂角色可讓使用者使用一組自訂的資源提供者作業來建立 Azure 角色定義。 若要瞭解哪些作業可用來建置 Azure Cosmos DB 的自定義角色， 請參閱 Azure Cosmos DB 資源提供者作業
提示
需要存取 Azure Cosmos DB 記憶體儲存數據的自定義角色，或使用 Azure 入口網站 中的數據總管必須有Microsoft.DocumentDB/databaseAccounts/listKeys/*動作。
注意
自定義角色指派不一定會顯示在 Azure 入口網站 中。
警告
管理 RBAC 變更之後，帳戶密鑰不會自動輪替或撤銷。 這些金鑰可讓您存取數據平面作業。 從使用者移除密鑰的存取權時，也建議您輪替密鑰。 針對 RBAC 數據平面，一旦角色/宣告不再相符，Cosmos DB 後端將會拒絕要求。 如果使用者需要暫時存取數據平面作業，建議使用 Azure Cosmos DB RBAC 數據平面。
防止 Azure Cosmos DB SDK 的變更
您可以鎖定 Azure Cosmos DB 資源提供者，以防止使用帳戶密鑰從用戶端連線到資源的任何變更（也就是透過 Azure Cosmos DB SDK 連線的應用程式）。 對於想要對生產環境進行更高程度的控制和控管的使用者，可能會想要使用這項功能。 防止 SDK 的變更，也可啟用控制平面作業的資源鎖定和診斷記錄等功能。 從 Azure Cosmos DB SDK 連線的用戶端將無法變更 Azure Cosmos DB 帳戶、資料庫、容器和輸送量的任何屬性。 將數據讀取和寫入至 Azure Cosmos DB 容器本身的作業不會受到影響。
啟用此功能時，只能從具有正確 Azure 角色的使用者和 Microsoft Entra 認證，包括受控服務識別的使用者進行變更。
警告
啟用此功能可能會影響您的應用程式。 請先確定您已瞭解其啟用前的影響。
啟用前先檢查清單
此設定可防止任何 Azure Cosmos DB 資源從任何使用帳戶密鑰進行連線的客戶端變更，包括任何 Azure Cosmos DB SDK，以及透過帳戶密鑰連線的任何工具。 若要在啟用此功能之後防止應用程式發生問題或錯誤，請在啟用此功能之前，檢查應用程式是否執行下列任何動作，包括：
建立、刪除子資源，例如資料庫和容器。 這包括其他 API 的資源，例如 Cassandra、MongoDB、Gremlin 和數據表資源。
讀取或更新資料庫或容器層級資源的輸送量。
修改容器屬性，包括索引原則、TTL 和唯一索引鍵。
修改預存程序、觸發程序和使用者定義函式。
如果您的應用程式（或透過 Azure 入口網站 的用戶）執行上述任何動作，則必須透過ARM範本、PowerShell、Azure CLI、REST 或 Azure 管理連結庫進行移轉。 請注意，Azure 管理提供 多種語言。
透過ARM範本設定
若要使用 ARM 範本設定此屬性，請更新現有的範本或匯出您目前部署的新範本，然後將 包含 "disableKeyBasedMetadataWriteAccess": true 至資源的屬性 databaseAccounts 。 以下是具有此屬性設定的 Azure Resource Manager 範本基本範例。
{
{
"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
}
}
}
重要
使用這個屬性重新部署時，請務必包含帳戶和子資源的其他屬性。 請勿依原樣部署此範本，否則會重設您所有的帳戶屬性。
透過 Azure CLI 設定
若要使用 Azure CLI 來啟用，請使用下列命令：
az cosmosdb update --name [CosmosDBAccountName] --resource-group [ResourceGroupName] --disable-key-based-metadata-write-access true
透過PowerShell設定
若要使用 Azure PowerShell 來啟用，請使用下列命令：
Update-AzCosmosDBAccount -ResourceGroupName [ResourceGroupName] -Name [CosmosDBAccountName] -DisableKeyBasedMetadataWriteAccess true