Condividi tramite

Usare il controllo degli accessi in base al ruolo del piano dati con Azure Cosmos DB per NoSQL

  • Articolo

SI APPLICA A: NoSQL

Diagramma della posizione corrente ('Controllo degli accessi in base al ruolo') nella sequenza della guida alla distribuzione.

Suggerimento

Visitare la nuova raccolta di esempi per gli esempi più recenti per la creazione di nuove app

Questo articolo illustra la procedura per concedere a un'identità l'accesso per gestire i dati in un account Azure Cosmos DB per NoSQL.

Importante

I passaggi descritti in questo articolo riguardano solo l'accesso al piano dati per eseguire operazioni su singoli elementi ed eseguire query. Per informazioni su come gestire ruoli, definizioni e assegnazioni per il piano di controllo, vedere Concedere l'accesso in base al ruolo del piano di controllo.

Prerequisiti

  • Un account Azure con una sottoscrizione attiva. Creare un account gratuitamente.
  • Un account Azure Cosmos DB for NoSQL già presente.
  • Una o più identità esistenti in Microsoft Entra ID.

Preparare la definizione del ruolo

Prima di tutto, è necessario preparare una definizione di ruolo con un elenco di dataActions per concedere l'accesso a dati di lettura, query e gestione in Azure Cosmos DB per NoSQL.

Importante

Per ottenere una definizione di ruolo del piano dati esistente sono necessarie queste autorizzazioni del piano di controllo:

  • Microsoft.DocumentDB/databaseAccounts/sqlRoleDefinitions/read

Per altre informazioni, vedere Concedere l'accesso in base al ruolo del piano di controllo.

Elencare tutte le definizioni di ruolo associate all'account Azure Cosmos DB per NoSQL usando az cosmosdb sql role definition list. Esaminare l'output e individuare la definizione del ruolo denominata Collaboratore dati predefinito di Cosmos DB. L'output contiene l'identificatore univoco della definizione del ruolo nella id proprietà . Registrare questo valore perché è necessario usare nel passaggio di assegnazione più avanti in questa guida.

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"
  }
  ...
]

Nota

Per questo esempio, il valore id sarebbe /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/msdocs-identity-example/providers/Microsoft.DocumentDB/databaseAccounts/msdocs-identity-example-nosql/sqlRoleDefinitions/00000000-0000-0000-0000-000000000002. In questo esempio vengono usati dati fittizi e l'identificatore è diverso da questo esempio.

Usare Get-AzCosmosDBSqlRoleDefinition per elencare tutte le definizioni di ruolo associate all'account Azure Cosmos DB per NoSQL. Esaminare l'output e individuare la definizione del ruolo denominata Collaboratore dati predefinito di Cosmos DB. L'output contiene l'identificatore univoco della definizione del ruolo nella Id proprietà . Registrare questo valore perché è necessario usare nel passaggio di assegnazione più avanti in questa guida.

$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 :

Nota

Per questo esempio, il valore Id sarebbe /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/msdocs-identity-example/providers/Microsoft.DocumentDB/databaseAccounts/msdocs-identity-example-nosql/sqlRoleDefinitions/00000000-0000-0000-0000-000000000002. In questo esempio vengono usati dati fittizi e l'identificatore è diverso da questo esempio. Tuttavia, l'identificatore (00000000-0000-0000-0000-000000000002) è univoco in tutte le definizioni di ruolo nell'account.

Assegnare un ruolo all'identità

Assegnare ora il ruolo appena definito a un'identità in modo che le applicazioni possano accedere ai dati in Azure Cosmos DB per NoSQL.

Importante

La creazione di un'assegnazione di ruolo del piano dati richiede queste autorizzazioni del piano di controllo:

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

Per altre informazioni, vedere Concedere l'accesso in base al ruolo del piano di controllo.

  1. Usare az cosmosdb show per ottenere l'identificatore univoco per l'account corrente.

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

  2. Osservare l'output del comando precedente. Registrare il valore della id proprietà per questo account perché è necessario usare nel passaggio successivo.

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

    Nota

    Per questo esempio, il valore id sarebbe /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/msdocs-identity-example/providers/Microsoft.DocumentDB/databaseAccounts/msdocs-identity-example-nosql. In questo esempio vengono usati dati fittizi e l'identificatore è diverso da questo esempio.

  3. Assegnare il nuovo ruolo usando az cosmosdb sql role assignment create. Usare gli identificatori di definizione del ruolo registrati in precedenza per l'argomento --role-definition-id e l'identificatore univoco per l'identità dell'argomento --principal-id . Infine, usare l'identificatore dell'account per l'argomento --scope .

    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. Usare az cosmosdb sql role assignment list per elencare tutte le assegnazioni di ruolo per l'account Azure Cosmos DB per NoSQL. Esaminare l'output per verificare che l'assegnazione di ruolo sia stata creata.

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

  1. Creare un nuovo file Bicep per definire l'assegnazione di ruolo. Assegnare al file il nome 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. Creare un nuovo file di parametri Bicep denominato data-plane-role-assignment.bicepparam In questo file di parametri assegnare il nome dell'account Azure Cosmos DB per NoSQL esistente al accountName parametro , gli identificatori di definizione del ruolo registrati in precedenza al roleDefinitionId parametro e l'identificatore univoco per l'identità al identityId parametro .

    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. Distribuire il modello Bicep usando 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. Ripetere questi passaggi per concedere l'accesso all'account da qualsiasi altra identità che si vuole usare.

    Suggerimento

    È possibile ripetere questi passaggi per tutte le identità desiderate. In genere, questi passaggi vengono almeno ripetuti per consentire agli sviluppatori di accedere a un account usando la propria identità umana e consentire alle applicazioni di accedere usando un'identità gestita.

  1. Usare Get-AzCosmosDBAccount per ottenere i metadati per l'account corrente.

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

  2. Osservare l'output del comando precedente. Registrare il valore della Id proprietà per questo account perché è necessario usare nel passaggio successivo.

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

    Nota

    Per questo esempio, il valore Id sarebbe /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/msdocs-identity-example/providers/Microsoft.DocumentDB/databaseAccounts/msdocs-identity-example-nosql. In questo esempio vengono usati dati fittizi e l'identificatore è diverso da questo esempio.

  3. Usare New-AzCosmosDBSqlRoleAssignment per assegnare il nuovo ruolo. Usare gli identificatori di definizione del ruolo registrati in precedenza per il RoleDefinitionId parametro e l'identificatore univoco per l'identità con il PrincipalId parametro . Infine, usare l'identificatore dell'account per il Scope parametro .

    $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. Elencare tutte le assegnazioni di ruolo per l'account Azure Cosmos DB per NoSQL usando Get-AzCosmosDBSqlRoleAssignment. Esaminare l'output per verificare che l'assegnazione di ruolo sia stata creata.

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

Convalidare l'accesso al piano dati nel codice

Verificare infine di aver concesso correttamente l'accesso usando il codice dell'applicazione e Azure SDK nel linguaggio di programmazione preferito.

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

string endpoint = "<account-endpoint>";

TokenCredential credential = new DefaultAzureCredential();

CosmosClient client = new(endpoint, credential);

Importante

Questo esempio di codice usa le Microsoft.Azure.Cosmos librerie e Azure.Identity di NuGet.