使用 Azure Azure Active Directory DB 帳戶Cosmos角色型存取控制

適用于 :SQL API

注意

本文說明 Azure 和 DB 中資料平面作業的以角色為基礎的存取控制Cosmos控制項。 如果您使用的是管理平面作業,請參閱將角色型 存取控制 應用程式至管理平面作業一文。

Azure Cosmos DB 會向 RBAC (內建角色型存取控制) ,讓您:

  • 使用身分識別驗證Azure Active Directory (Azure AD) 要求。
  • 使用精細、角色型的許可權模型來授權您的資料要求。

概念

Azure Cosmos DB 資料平面 RBAC 建立在 Azure RBAC 等其他 RBAC 系統中常見的概念上

  • 許可權 模型 是由一組動作 所組成;這些動作會分別與一或多個資料庫作業相連接。 一些動作範例包括讀取專案、撰寫專案或執行查詢。

  • Azure Cosmos DB 使用者建立包含允許動作清單的角色定義。

  • 角色定義會透過角色指派Azure AD特定角色身分。 角色指派也會定義角色定義適用的範圍;目前,有三個範圍:

    • Azure Cosmos DB 帳戶,
    • Azure Cosmos DB 資料庫,
    • Azure Cosmos DB 容器。

    RBAC 概念

許可權模型

重要

此許可權模型僅涵蓋涉及讀取和寫入資料的資料庫作業。 它 不包含 管理資源上的任何管理作業,例如:

  • 建立/取代/刪除資料庫
  • 建立/取代/刪除容器
  • 取代容器輸送量
  • 建立/取代/刪除/讀取儲存的程式
  • 建立/取代/刪除/讀取觸發
  • 建立/取代/刪除/讀取使用者定義的函數

您無法使用任何 Azure Cosmos資料庫資料平面 SDK來驗證管理作業Azure AD身分識別。 您必須改為透過下列其中一個選項使用Azure RBAC:

讀取資料庫和讀取容器視為 中繼資料要求。 您可以如下一節所述,授予這些作業的存取權。

下表列出許可權模型公開的所有動作。

名字 對應的資料庫作業 ()
Microsoft.DocumentDB/databaseAccounts/readMetadata 讀取帳戶中繼資料。 請參閱 中繼資料要求 以瞭解詳細資料。
Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/items/create 建立新專案。
Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/items/read 以識別碼和分區鍵讀取個別專案, (點讀取) 。
Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/items/replace 取代現有的專案。
Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/items/upsert 「Upsert」專案,這表示若不存在,即建立專案,或將其取代為存在。
Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/items/delete 刪除專案。
Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/executeQuery 執行SQL查詢
Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/readChangeFeed 從容器的變更來源 讀取
Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/executeStoredProcedure 執行 儲存的程式
Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/manageConflicts 管理 寫入地區帳戶的衝突 (,也就是說,從衝突提要清單和刪除) 。

容器和專案層級都支援萬用字元

  • Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/*
  • Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/items/*

中繼資料要求

當使用 Azure Cosmos DB SDK 時,這些 SDK 在初始化期間會發出唯讀中繼資料要求,並且提供特定的資料要求。 這些中繼資料要求會提取各種組組詳細資料,例如:

  • 帳戶的通用群組組,包括帳戶可用的 Azure 區域。
  • 容器的分區鍵或其索引策略。
  • 製作容器及其位址之實體分區清單。

他們 不會 提取您儲存在您帳戶中的任何資料。

為了確保許可權模型的最佳透明度,動作會明確涵蓋這些中繼資料 Microsoft.DocumentDB/databaseAccounts/readMetadata 要求。 在透過其中一個 Azure 資料庫 SDK 存取 Azure Cosmos DB 帳戶時,應允許採取Cosmos動作。 您可以透過 Azure Cosmos (DB 階層) 角色指派 (帳戶、資料庫或容器) 。

動作允許的實際中繼資料要求取決於動作指派 Microsoft.DocumentDB/databaseAccounts/readMetadata 給的範圍:

範圍 動作允許的要求
帳戶 - 在帳戶下列出資料庫
- 針對帳戶下的每個資料庫,資料庫範圍允許的動作
資料庫 - 讀取資料庫中繼資料
- 在資料庫下列出容器
- 針對資料庫下的每個容器,容器範圍允許的動作
容器 - 讀取容器中繼資料
- 在容器下列出實體分區
- 解決每個實體分區的位址

內建的角色定義

Azure Cosmos DB 會公開 2 個內建的角色定義:

ID 名字 包含的動作
00000000-0000-0000-0000-000000000001 Cosmos DB 內建資料閱讀程式 Microsoft.DocumentDB/databaseAccounts/readMetadata
Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/items/read
Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/executeQuery
Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/readChangeFeed
00000000-0000-0000-0000-000000000002 Cosmos DB 內建資料參與者 Microsoft.DocumentDB/databaseAccounts/readMetadata
Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/*
Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/items/*

建立自訂角色定義

建立自訂角色定義時,您需要提供:

  • Azure 名稱Cosmos DB 帳戶。
  • 包含您帳戶的資源群組。
  • 角色定義的類型 CustomRole :。
  • 角色定義的名稱。
  • 您希望 角色 允許的動作清單。
  • 一或多個 () 可指派角色定義;支援的範圍為:
    • / (帳戶層級) ,
    • /dbs/<database-name> (資料庫層級) ,
    • /dbs/<database-name>/colls/<container-name> (容器層級) 。

注意

下列操作可用於:

使用Azure PowerShell

建立只包含 讀取動作的名為 MyReadOnlyRole 的角色:

$resourceGroupName = "<myResourceGroup>"
$accountName = "<myCosmosAccount>"
New-AzCosmosDBSqlRoleDefinition -AccountName $accountName `
    -ResourceGroupName $resourceGroupName `
    -Type CustomRole -RoleName MyReadOnlyRole `
    -DataAction @( `
        'Microsoft.DocumentDB/databaseAccounts/readMetadata',
        'Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/items/read', `
        'Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/executeQuery', `
        'Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/readChangeFeed') `
    -AssignableScope "/"

建立一個名為 MyReadWrite 的角色,其中包含 所有動作:

New-AzCosmosDBSqlRoleDefinition -AccountName $accountName `
    -ResourceGroupName $resourceGroupName `
    -Type CustomRole -RoleName MyReadWriteRole `
    -DataAction @( `
        'Microsoft.DocumentDB/databaseAccounts/readMetadata',
        'Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/items/*', `
        'Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/*') `
    -AssignableScope "/"

列出您為抓取其 ID 所建立的角色定義:

Get-AzCosmosDBSqlRoleDefinition -AccountName $accountName `
    -ResourceGroupName $resourceGroupName
RoleName         : MyReadWriteRole
Id               : /subscriptions/<mySubscriptionId>/resourceGroups/<myResourceGroup>/providers/Microsoft.DocumentDB/databaseAcc
                   ounts/<myCosmosAccount>/sqlRoleDefinitions/<roleDefinitionId>
Type             : CustomRole
Permissions      : {Microsoft.Azure.Management.CosmosDB.Models.Permission}
AssignableScopes : {/subscriptions/<mySubscriptionId>/resourceGroups/<myResourceGroup>/providers/Microsoft.DocumentDB/databaseAc
                   counts/<myCosmosAccount>}

RoleName         : MyReadOnlyRole
Id               : /subscriptions/<mySubscriptionId>/resourceGroups/<myResourceGroup>/providers/Microsoft.DocumentDB/databaseAcc
                   ounts/<myCosmosAccount>/sqlRoleDefinitions/<roleDefinitionId>
Type             : CustomRole
Permissions      : {Microsoft.Azure.Management.CosmosDB.Models.Permission}
AssignableScopes : {/subscriptions/<mySubscriptionId>/resourceGroups/<myResourceGroup>/providers/Microsoft.DocumentDB/databaseAc
                   counts/<myCosmosAccount>}

使用 Azure CLI

建立只包含 讀取動作的名為 MyReadOnlyRole 的角色:

// role-definition-ro.json
{
    "RoleName": "MyReadOnlyRole",
    "Type": "CustomRole",
    "AssignableScopes": ["/"],
    "Permissions": [{
        "DataActions": [
            "Microsoft.DocumentDB/databaseAccounts/readMetadata",
            "Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/items/read",
            "Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/executeQuery",
            "Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/readChangeFeed"
        ]
    }]
}
resourceGroupName='<myResourceGroup>'
accountName='<myCosmosAccount>'
az cosmosdb sql role definition create --account-name $accountName --resource-group $resourceGroupName --body @role-definition-ro.json

建立一個名為 MyReadWrite 的角色,其中包含 所有動作:

// role-definition-rw.json
{
    "RoleName": "MyReadWriteRole",
    "Type": "CustomRole",
    "AssignableScopes": ["/"],
    "Permissions": [{
        "DataActions": [
            "Microsoft.DocumentDB/databaseAccounts/readMetadata",
            "Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/items/*",
            "Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/*"
        ]
    }]
}
az cosmosdb sql role definition create --account-name $accountName --resource-group $resourceGroupName --body @role-definition-rw.json

列出您為抓取其 ID 所建立的角色定義:

az cosmosdb sql role definition list --account-name $accountName --resource-group $resourceGroupName
[
  {
    "assignableScopes": [
      "/subscriptions/<mySubscriptionId>/resourceGroups/<myResourceGroup>/providers/Microsoft.DocumentDB/databaseAccounts/<myCosmosAccount>"
    ],
    "id": "/subscriptions/<mySubscriptionId>/resourceGroups/<myResourceGroup>/providers/Microsoft.DocumentDB/databaseAccounts/<myCosmosAccount>/sqlRoleDefinitions/<roleDefinitionId>",
    "name": "<roleDefinitionId>",
    "permissions": [
      {
        "dataActions": [
          "Microsoft.DocumentDB/databaseAccounts/readMetadata",
          "Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/items/*",
          "Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/*"
        ],
        "notDataActions": []
      }
    ],
    "resourceGroup": "<myResourceGroup>",
    "roleName": "MyReadWriteRole",
    "sqlRoleDefinitionGetResultsType": "CustomRole",
    "type": "Microsoft.DocumentDB/databaseAccounts/sqlRoleDefinitions"
  },
  {
    "assignableScopes": [
      "/subscriptions/<mySubscriptionId>/resourceGroups/<myResourceGroup>/providers/Microsoft.DocumentDB/databaseAccounts/<myCosmosAccount>"
    ],
    "id": "/subscriptions/<mySubscriptionId>/resourceGroups/<myResourceGroup>/providers/Microsoft.DocumentDB/databaseAccounts/<myCosmosAccount>/sqlRoleDefinitions/<roleDefinitionId>",
    "name": "<roleDefinitionId>",
    "permissions": [
      {
        "dataActions": [
          "Microsoft.DocumentDB/databaseAccounts/readMetadata",
          "Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/items/read",
          "Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/executeQuery",
          "Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/readChangeFeed"
        ],
        "notDataActions": []
      }
    ],
    "resourceGroup": "<myResourceGroup>",
    "roleName": "MyReadOnlyRole",
    "sqlRoleDefinitionGetResultsType": "CustomRole",
    "type": "Microsoft.DocumentDB/databaseAccounts/sqlRoleDefinitions"
  }
]

使用 Azure Resource Manager 範本

請參閱 此頁面, 瞭解使用 Azure Resource Manager 範本建立角色定義的參考和範例。

建立角色指派

您可以將內建或自訂角色定義與使用者身分Azure AD關聯。 建立角色指派時,您需要提供:

  • Azure 名稱Cosmos DB 帳戶。

  • 包含您帳戶的資源群組。

  • 要指派的角色定義識別碼。

  • 角色定義應指派給身分識別的主要識別碼。

  • 角色指派的範圍;支援的範圍為:

    • / (帳戶層級)
    • /dbs/<database-name> (資料庫層級)
    • /dbs/<database-name>/colls/<container-name> (容器層級)

    範圍必須與角色定義之一的可指派範圍相符或為子範圍。

注意

如果您想要為服務主體建立角色指派,請確定使用其物件識別碼,Enterprise入口網站邊欄選項卡的 Azure Active Directory區段

注意

下列操作可用於:

使用Azure PowerShell

將角色指派給身分識別:

$resourceGroupName = "<myResourceGroup>"
$accountName = "<myCosmosAccount>"
$readOnlyRoleDefinitionId = "<roleDefinitionId>" # as fetched above
$principalId = "<aadPrincipalId>"
New-AzCosmosDBSqlRoleAssignment -AccountName $accountName `
    -ResourceGroupName $resourceGroupName `
    -RoleDefinitionId $readOnlyRoleDefinitionId `
    -Scope "/" `
    -PrincipalId $principalId

使用 Azure CLI

將角色指派給身分識別:

resourceGroupName='<myResourceGroup>'
accountName='<myCosmosAccount>'
readOnlyRoleDefinitionId = '<roleDefinitionId>' # as fetched above
principalId = '<aadPrincipalId>'
az cosmosdb sql role assignment create --account-name $accountName --resource-group $resourceGroupName --scope "/" --principal-id $principalId --role-definition-id $readOnlyRoleDefinitionId

使用 Azure Resource Manager 範本

請參閱 此頁面, 瞭解使用 Azure Resource Manager 範本建立角色指派的參考和範例。

使用應用程式初始化 SDK Azure AD

若要在應用程式中使用 Azure Cosmos DB RBAC,您必須更新在 DB SDK 中初始化 Azure Cosmos的方式。 您必須傳遞班級的實例,而不是傳遞帳戶的主 TokenCredential 鍵。 此實例提供 Azure Cosmos DB SDK,提供代表您AAD身分識別來抓取權杖所需的上下文。

建立實例 TokenCredential 的方式不在本文討論範圍內。 根據您想要在 AAD 使用者主體、服務主體、群組等 (的身分識別類型,建立這類實例的方法) 。 最重要的是,您的實例必須解析為 (角色) 識別碼的 TokenCredential 身分識別。 您可以找到建立班級的 TokenCredential 範例:

下列範例將服務主體與實例 ClientSecretCredential 一起使用。

在 .NET 中

Azure Cosmos DB RBAC 目前支援.NET SDK V3。

TokenCredential servicePrincipal = new ClientSecretCredential(
    "<azure-ad-tenant-id>",
    "<client-application-id>",
    "<client-application-secret>");
CosmosClient client = new CosmosClient("<account-endpoint>", servicePrincipal);

在 JAVA 中

Azure Cosmos DB RBAC 目前支援 JAVA SDK V4。

TokenCredential ServicePrincipal = new ClientSecretCredentialBuilder()
    .authorityHost("https://login.microsoftonline.com")
    .tenantId("<azure-ad-tenant-id>")
    .clientId("<client-application-id>")
    .clientSecret("<client-application-secret>")
    .build();
CosmosAsyncClient Client = new CosmosClientBuilder()
    .endpoint("<account-endpoint>")
    .credential(ServicePrincipal)
    .build();

在 JavaScript 中

Azure Cosmos DB RBAC 目前支援JavaScript SDK V3。

const servicePrincipal = new ClientSecretCredential(
    "<azure-ad-tenant-id>",
    "<client-application-id>",
    "<client-application-secret>");
const client = new CosmosClient({
    "<account-endpoint>",
    aadCredentials: servicePrincipal
});

在 REST API 上驗證要求

建構 REST API 授權標頭時,將 type 參數設定為 aad, 而雜湊簽名 (sig ) sig) 為指定 符號,如下列範例所示:

type=aad&ver=1.0&sig=<token-from-oauth>

使用資料管理器

注意

Azure 入口網站中公開的資料管理器目前Cosmos Azure 資料庫 RBAC。 若要在探索Azure AD使用您的身分識別,您必須改為使用 Azure Cosmos DB Explorer。

當您使用特定查詢Cosmos存取 Azure和 DB Explorer 並登錄時,會使用下列邏輯 來存取您的資料:

  1. 會代表已登錄的身分識別,嘗試要求取回帳戶的主鍵。 如果此要求成功,主鍵會用來存取帳戶的資料。
  2. 如果不允許已登錄的身分識別取得帳戶的主鍵,則此身分識別會直接用來驗證資料存取。 在此模式中,身分識別必須指派 適當的角色定義 ,以確保資料存取。

稽核資料要求

使用 Azure Cosmos DB RBAC時,診斷記錄會隨著每個資料作業的身分識別與授權資訊而擴充。 這可讓您執行詳細稽核,並AAD每個資料要求在 DB 帳戶上Cosmos身分識別。

這項額外資訊會排列在 Data方列記錄 類別中,並包含兩個額外的欄:

  • aadPrincipalId_g顯示用來驗證AAD身分識別的主要識別碼。
  • aadAppliedRoleAssignmentId_g 顯示 aadAppliedRoleAssignmentId_g 要求時所遵守的角色指派。

強制執行 RBAC 做為唯一的驗證方法

在您想要強制用戶端透過 RBAC Cosmos Azure 資料庫的情況下,您可以選擇停用帳戶的主/次要金鑰。 這麼做時,任何使用主/次要金鑰或資源權杖的傳入要求都會遭到主動拒絕。

使用 Azure Resource Manager 範本

使用 Azure Resource Manager 範本Cosmos或更新 Azure 資料庫帳戶時,將 disableLocalAuth 屬性設定為 true

"resources": [
    {
        "type": " Microsoft.DocumentDB/databaseAccounts",
        "properties": {
            "disableLocalAuth": true,
            // ...
        },
        // ...
    },
    // ...
 ]

限制

  • 您可以為每個 Azure 和 DB 帳戶建立最多 100 個角色定義和 2,000 Cosmos指派。
  • 您只可以將角色定義指派Azure AD您的 Azure 或 DB 帳戶Azure AD同一個租使用者Cosmos身分。
  • Azure AD超過 200 個群組的身分標識目前不支援群組解析度。
  • 此Azure AD權杖目前會以標頭傳遞,每個個別要求會Cosmos Azure Cosmos DB 服務,增加整體負載大小。

常見問題

RBAC Cosmos哪些 Azure 資料庫 API?

目前僅SQL API。

是否可能從 Azure 入口網站管理角色定義和角色指派?

尚未提供角色管理的 Azure 入口網站支援。

Azure 中的哪些 SDK Cosmos DB SQL支援 RBAC?

目前支援 .NET V3、JAVAV4JavaScript V3 SDK。

當 azure Azure AD DB SDK 到期時,Cosmos權杖是否自動重新過?

是的。

使用 RBAC 時,是否可能停用帳戶主/次要金鑰的使用方式?

是, 請參閱強制執行 RBAC 做為唯一的驗證方法

下一個步驟