Bagikan melalui

Menggunakan kontrol akses berbasis peran bidang data dengan Azure Cosmos DB untuk NoSQL

  • Artikel

BERLAKU UNTUK: NoSQL

Diagram lokasi saat ini ('Kontrol akses berbasis peran') dalam urutan panduan penyebaran.

Tip

Kunjungi Galeri Sampel baru kami untuk sampel terbaru untuk membangun aplikasi baru

Artikel ini menjelaskan langkah-langkah untuk memberikan akses identitas untuk mengelola data di akun Azure Cosmos DB for NoSQL.

Penting

Langkah-langkah dalam artikel ini hanya mencakup akses sarana data untuk melakukan operasi pada item individual dan menjalankan kueri. Untuk mempelajari cara mengelola peran, definisi, dan penugasan untuk sarana kontrol, lihat memberikan akses berbasis peran sarana kontrol.

Prasyarat

  • Akun Azure dengan langganan aktif. Buat akun secara gratis.
  • Akun Azure Cosmos DB for NoSQL yang sudah ada.
  • Satu atau beberapa identitas yang sudah ada di ID Microsoft Entra.

Menyiapkan definisi peran

Pertama, Anda harus menyiapkan definisi peran dengan daftar dataActions untuk memberikan akses ke baca, kueri, dan kelola data di Azure Cosmos DB untuk NoSQL.

Penting

Mendapatkan definisi peran sarana data yang ada memerlukan izin sarana kontrol ini:

  • Microsoft.DocumentDB/databaseAccounts/sqlRoleDefinitions/read

Untuk informasi selengkapnya, lihat memberikan akses berbasis peran sarana kontrol.

Cantumkan semua definisi peran yang terkait dengan Akun Azure Cosmos DB for NoSQL Anda menggunakan az cosmosdb sql role definition list. Tinjau output dan temukan definisi peran bernama Kontributor Data Bawaan Cosmos DB. Output berisi pengidentifikasi unik definisi peran dalam id properti . Rekam nilai ini karena diperlukan untuk digunakan dalam langkah penetapan nanti dalam panduan ini.

az cosmosdb sql role definition list \
    --resource-group "<name-of-existing-resource-group>" \
    --account-name "<name-of-existing-nosql-account>"

[
  ...,
  {
    "assignableScopes": [
      "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/msdocs-identity-example/providers/Microsoft.DocumentDB/databaseAccounts/msdocs-identity-example-nosql"
    ],
    "id": "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/msdocs-identity-example/providers/Microsoft.DocumentDB/databaseAccounts/msdocs-identity-example-nosql/sqlRoleDefinitions/00000000-0000-0000-0000-000000000002",
    "name": "00000000-0000-0000-0000-000000000002",
    "permissions": [
      {
        "dataActions": [
          "Microsoft.DocumentDB/databaseAccounts/readMetadata",
          "Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/*",
          "Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/items/*"
        ],
        "notDataActions": []
      }
    ],
    "resourceGroup": "msdocs-identity-example",
    "roleName": "Cosmos DB Built-in Data Contributor",
    "type": "Microsoft.DocumentDB/databaseAccounts/sqlRoleDefinitions",
    "typePropertiesType": "BuiltInRole"
  }
  ...
]

Catatan

Dalam contoh ini, nilainya id adalah /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/msdocs-identity-example/providers/Microsoft.DocumentDB/databaseAccounts/msdocs-identity-example-nosql/sqlRoleDefinitions/00000000-0000-0000-0000-000000000002. Contoh ini menggunakan data fiktif dan pengidentifikasi Anda akan berbeda dari contoh ini.

Gunakan Get-AzCosmosDBSqlRoleDefinition untuk mencantumkan semua definisi peran yang terkait dengan akun Azure Cosmos DB for NoSQL Anda. Tinjau output dan temukan definisi peran bernama Kontributor Data Bawaan Cosmos DB. Output berisi pengidentifikasi unik definisi peran dalam Id properti . Rekam nilai ini karena diperlukan untuk digunakan dalam langkah penetapan nanti dalam panduan ini.

$parameters = @{
    ResourceGroupName = "<name-of-existing-resource-group>"
    AccountName = "<name-of-existing-nosql-account>"
}
Get-AzCosmosDBSqlRoleDefinition @parameters

Id                         : /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/msdocs-identity-example/providers/Microsoft.DocumentDB/databaseAccounts/msdocs-identity-example-nosql/sqlRoleDefinitions/00000000-0000-0000-0000-000000000002
RoleName                   : Cosmos DB Built-in Data Contributor
Type                       : BuiltInRole
AssignableScopes           : {/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/msdocs-identity-example/providers/Microsoft.DocumentDB/databaseAccountsmsdocs-identity-example-nosql}
Permissions.DataActions    : {Microsoft.DocumentDB/databaseAccounts/readMetadata, Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/*, Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/items/*}
Permissions.NotDataActions :

Catatan

Dalam contoh ini, nilainya Id adalah /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/msdocs-identity-example/providers/Microsoft.DocumentDB/databaseAccounts/msdocs-identity-example-nosql/sqlRoleDefinitions/00000000-0000-0000-0000-000000000002. Contoh ini menggunakan data fiktif dan pengidentifikasi Anda akan berbeda dari contoh ini. Namun, pengidentifikasi (00000000-0000-0000-0000-000000000002) unik di semua definisi peran di akun Anda.

Menetapkan peran ke identitas

Sekarang, tetapkan peran yang baru ditentukan ke identitas sehingga aplikasi Anda dapat mengakses data di Azure Cosmos DB untuk NoSQL.

Penting

Membuat penetapan peran sarana data baru memerlukan izin sarana kontrol ini:

  • Microsoft.DocumentDB/databaseAccounts/sqlRoleDefinitions/read
  • Microsoft.DocumentDB/databaseAccounts/sqlRoleAssignments/read
  • Microsoft.DocumentDB/databaseAccounts/sqlRoleAssignments/write

Untuk informasi selengkapnya, lihat memberikan akses berbasis peran sarana kontrol.

  1. Gunakan az cosmosdb show untuk mendapatkan pengidentifikasi unik untuk akun Anda saat ini.

    az cosmosdb show \
    --resource-group "<name-of-existing-resource-group>" \
    --name "<name-of-existing-nosql-account>" \
    --query "{id:id}"

  2. Amati output perintah sebelumnya. Catat nilai id properti untuk akun ini karena diperlukan untuk digunakan pada langkah berikutnya.

    {
  "id": "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/msdocs-identity-example/providers/Microsoft.DocumentDB/databaseAccounts/msdocs-identity-example-nosql"
}

    Catatan

    Dalam contoh ini, nilainya id adalah /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/msdocs-identity-example/providers/Microsoft.DocumentDB/databaseAccounts/msdocs-identity-example-nosql. Contoh ini menggunakan data fiktif dan pengidentifikasi Anda akan berbeda dari contoh ini.

  3. Tetapkan peran baru menggunakan az cosmosdb sql role assignment create. Gunakan pengidentifikasi definisi peran yang direkam sebelumnya ke --role-definition-id argumen , dan pengidentifikasi unik untuk identitas Anda ke --principal-id argumen . Terakhir, gunakan pengidentifikasi akun Anda untuk --scope argumen .

    az cosmosdb sql role assignment create \
    --resource-group "<name-of-existing-resource-group>" \
    --account-name "<name-of-existing-nosql-account>" \
    --role-definition-id "<id-of-new-role-definition>" \
    --principal-id "<id-of-existing-identity>" \
    --scope "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/msdocs-identity-example/providers/Microsoft.DocumentDB/databaseAccounts/msdocs-identity-example-nosql"

  4. Gunakan az cosmosdb sql role assignment list untuk mencantumkan semua penetapan peran untuk akun Azure Cosmos DB for NoSQL Anda. Tinjau output untuk memastikan penetapan peran Anda dibuat.

    az cosmosdb sql role assignment list \
    --resource-group "<name-of-existing-resource-group>" \
    --account-name "<name-of-existing-nosql-account>"

  1. Buat file Bicep baru untuk menentukan penetapan peran Anda. Beri nama file data-plane-role-assignment.bicep.

    metadata description = 'Assign RBAC role for data plane access to Azure Cosmos DB for NoSQL.'

@description('Name of the Azure Cosmos DB for NoSQL account.')
param accountName string

@description('Id of the role definition to assign to the targeted principal in the context of the account.')
param roleDefinitionId string

@description('Id of the identity/principal to assign this role in the context of the account.')
param identityId string

resource account 'Microsoft.DocumentDB/databaseAccounts@2024-05-15' existing = {
  name: accountName
}

resource assignment 'Microsoft.DocumentDB/databaseAccounts/sqlRoleAssignments@2024-05-15' = {
  name: guid(roleDefinitionId, identityId, account.id)
  parent: account
  properties: {
    principalId: identityId
    roleDefinitionId: roleDefinitionId
    scope: account.id
  }
}

output assignmentId string = assignment.id

  2. Buat file parameter Bicep baru bernama data-plane-role-assignment.bicepparam. Dalam file parameter ini, tetapkan nama akun Azure Cosmos DB for NoSQL yang ada ke accountName parameter, pengidentifikasi definisi peran yang direkam sebelumnya ke roleDefinitionId parameter, dan pengidentifikasi unik untuk identitas Anda ke identityId parameter .

    using './data-plane-role-assignment.bicep'

param accountName = '<name-of-existing-nosql-account>'
param roleDefinitionId = '<id-of-new-role-definition>'
param identityId = '<id-of-existing-identity>'

  3. Sebarkan templat Bicep menggunakan az deployment group create.

    az deployment group create \
    --resource-group "<name-of-existing-resource-group>" \
    --parameters data-plane-role-assignment.bicepparam \
    --template-file data-plane-role-assignment.bicep

  4. Ulangi langkah-langkah ini untuk memberikan akses ke akun dari identitas lain yang ingin Anda gunakan.

    Tip

    Anda dapat mengulangi langkah-langkah ini untuk identitas sebanyak yang Anda inginkan. Biasanya, langkah-langkah ini setidaknya diulang untuk memungkinkan pengembang mengakses akun menggunakan identitas manusia mereka dan untuk memungkinkan aplikasi mengakses menggunakan identitas terkelola.

  1. Gunakan Get-AzCosmosDBAccount untuk mendapatkan metadata untuk akun Anda saat ini.

    $parameters = @{
    ResourceGroupName = "<name-of-existing-resource-group>"
    Name = "<name-of-existing-nosql-account>"
}    
Get-AzCosmosDBAccount @parameters | Select -Property Id

  2. Amati output perintah sebelumnya. Catat nilai Id properti untuk akun ini karena diperlukan untuk digunakan pada langkah berikutnya.

    Id
--    
/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/msdocs-identity-example/providers/Microsoft.DocumentDB/databaseAccounts/msdocs-identity-example-nosql

    Catatan

    Dalam contoh ini, nilainya Id adalah /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/msdocs-identity-example/providers/Microsoft.DocumentDB/databaseAccounts/msdocs-identity-example-nosql. Contoh ini menggunakan data fiktif dan pengidentifikasi Anda akan berbeda dari contoh ini.

  3. Gunakan New-AzCosmosDBSqlRoleAssignment untuk menetapkan peran baru. Gunakan pengidentifikasi definisi peran yang direkam sebelumnya ke RoleDefinitionId parameter , dan pengidentifikasi unik untuk identitas Anda ke PrincipalId parameter . Terakhir, gunakan pengidentifikasi akun Anda untuk Scope parameter .

    $parameters = @{
    ResourceGroupName = "<name-of-existing-resource-group>"
    AccountName = "<name-of-existing-nosql-account>"
    RoleDefinitionId = "<id-of-new-role-definition>"
    PrincipalId = "<id-of-existing-identity>"
    Scope = "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/msdocs-identity-example/providers/Microsoft.DocumentDB/databaseAccounts/msdocs-identity-example-nosql"
}    
New-AzCosmosDBSqlRoleAssignment @parameters

  4. Cantumkan semua penetapan peran untuk akun Azure Cosmos DB for NoSQL Anda menggunakan Get-AzCosmosDBSqlRoleAssignment. Tinjau output untuk memastikan penetapan peran Anda dibuat.

    $parameters = @{
    ResourceGroupName = "<name-of-existing-resource-group>"
    AccountName = "<name-of-existing-nosql-account>"
}
Get-AzCosmosDBSqlRoleAssignment @parameters

Memvalidasi akses sarana data dalam kode

Terakhir, validasi bahwa Anda memberikan akses dengan benar menggunakan kode aplikasi dan Azure SDK dalam bahasa pemrograman pilihan Anda.

using Azure.Core;
using Azure.Identity;
using Microsoft.Azure.Cosmos;

string endpoint = "<account-endpoint>";

TokenCredential credential = new DefaultAzureCredential();

CosmosClient client = new(endpoint, credential);

Penting

Sampel kode ini menggunakan Microsoft.Azure.Cosmos pustaka dan Azure.Identity dari NuGet.