Delen via

Op rollen gebaseerd toegangsbeheer voor gegevensvlak gebruiken met Azure Cosmos DB for NoSQL

  • Artikel

VAN TOEPASSING OP: NoSQL

Diagram van de huidige locatie (op rollen gebaseerd toegangsbeheer) in de volgorde van de implementatiehandleiding.

Tip

Bezoek onze nieuwe voorbeeldengalerie voor de nieuwste voorbeelden voor het bouwen van nieuwe apps

In dit artikel worden de stappen beschreven voor het verlenen van toegang tot identiteiten voor het beheren van gegevens in een Azure Cosmos DB voor NoSQL-account.

Belangrijk

De stappen in dit artikel hebben alleen betrekking op gegevensvlaktoegang voor het uitvoeren van bewerkingen op afzonderlijke items en het uitvoeren van query's. Zie Op rollen gebaseerd toegangsvlak verlenen voor meer informatie over het beheren van rollen, definities en toewijzingen voor het besturingsvlak.

Vereisten

  • Een Azure-account met een actief abonnement. Gratis een account maken
  • Een bestaand Azure Cosmos DB for NoSQL-account.
  • Een of meer bestaande identiteiten in Microsoft Entra ID.

Roldefinitie voorbereiden

Eerst moet u een roldefinitie voorbereiden met een lijst met het verlenen van toegang tot lezen, opvragen en beheren van dataActions gegevens in Azure Cosmos DB voor NoSQL.

Belangrijk

Voor het verkrijgen van een bestaande roldefinitie voor het gegevensvlak zijn deze besturingsvlakmachtigingen vereist:

  • Microsoft.DocumentDB/databaseAccounts/sqlRoleDefinitions/read

Zie Toegang op basis van rollen in het besturingsvlak verlenen voor meer informatie.

Geef alle roldefinities weer die zijn gekoppeld aan uw Azure Cosmos DB for NoSQL-account met behulp van az cosmosdb sql role definition list. Controleer de uitvoer en zoek de roldefinitie met de naam Ingebouwde Gegevensbijdrager van Cosmos DB. De uitvoer bevat de unieke id van de roldefinitie in de id eigenschap. Noteer deze waarde omdat deze is vereist voor gebruik in de toewijzingsstap verderop in deze handleiding.

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

Notitie

In dit voorbeeld is /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/msdocs-identity-example/providers/Microsoft.DocumentDB/databaseAccounts/msdocs-identity-example-nosql/sqlRoleDefinitions/00000000-0000-0000-0000-000000000002de id waarde . In dit voorbeeld worden fictieve gegevens gebruikt en uw id is anders dan in dit voorbeeld.

Gebruik Get-AzCosmosDBSqlRoleDefinition dit om alle roldefinities weer te geven die zijn gekoppeld aan uw Azure Cosmos DB for NoSQL-account. Controleer de uitvoer en zoek de roldefinitie met de naam Ingebouwde Gegevensbijdrager van Cosmos DB. De uitvoer bevat de unieke id van de roldefinitie in de Id eigenschap. Noteer deze waarde omdat deze is vereist voor gebruik in de toewijzingsstap verderop in deze handleiding.

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

Notitie

In dit voorbeeld is /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/msdocs-identity-example/providers/Microsoft.DocumentDB/databaseAccounts/msdocs-identity-example-nosql/sqlRoleDefinitions/00000000-0000-0000-0000-000000000002de Id waarde . In dit voorbeeld worden fictieve gegevens gebruikt en uw id is anders dan in dit voorbeeld. De id (00000000-0000-0000-0000-000000000002) is echter uniek voor alle roldefinities in uw account.

Rol toewijzen aan identiteit

Wijs nu de zojuist gedefinieerde rol toe aan een identiteit, zodat uw toepassingen toegang hebben tot gegevens in Azure Cosmos DB voor NoSQL.

Belangrijk

Voor het maken van een nieuwe roltoewijzing voor het gegevensvlak zijn de volgende besturingsvlakmachtigingen vereist:

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

Zie Toegang op basis van rollen in het besturingsvlak verlenen voor meer informatie.

  1. Gebruik az cosmosdb show dit om de unieke id voor uw huidige account op te halen.

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

  2. Bekijk de uitvoer van de vorige opdracht. Noteer de waarde van de id eigenschap voor dit account omdat deze in de volgende stap moet worden gebruikt.

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

    Notitie

    In dit voorbeeld is /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/msdocs-identity-example/providers/Microsoft.DocumentDB/databaseAccounts/msdocs-identity-example-nosqlde id waarde . In dit voorbeeld worden fictieve gegevens gebruikt en uw id is anders dan in dit voorbeeld.

  3. Wijs de nieuwe rol toe met behulp van az cosmosdb sql role assignment create. Gebruik de eerder vastgelegde roldefinitie-id's voor het --role-definition-id argument en de unieke id voor uw identiteit voor het --principal-id argument. Gebruik ten slotte de id van uw account voor het --scope argument.

    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. Gebruik az cosmosdb sql role assignment list deze indeling om alle roltoewijzingen voor uw Azure Cosmos DB for NoSQL-account weer te geven. Controleer de uitvoer om ervoor te zorgen dat uw roltoewijzing is gemaakt.

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

  1. Maak een nieuw Bicep-bestand om uw roltoewijzing te definiëren. Geef het bestand de naam 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. Maak een nieuw Bicep-parametersbestand met de naam data-plane-role-assignment.bicepparam. Wijs in dit parameterbestand de naam van uw bestaande Azure Cosmos DB for NoSQL-account toe aan de accountName parameter, de eerder vastgelegde roldefinitie-id's aan de roleDefinitionId parameter en de unieke id voor uw identiteit aan de 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. Implementeer de Bicep-sjabloon met behulp van 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. Herhaal deze stappen om toegang te verlenen tot het account vanaf andere identiteiten die u wilt gebruiken.

    Tip

    U kunt deze stappen herhalen voor zo veel identiteiten als u wilt. Deze stappen worden doorgaans ten minste herhaald om ontwikkelaars toegang te geven tot een account met behulp van hun menselijke identiteit en om toepassingen toegang te geven met behulp van een beheerde identiteit.

  1. Gebruik Get-AzCosmosDBAccount dit om de metagegevens voor uw huidige account op te halen.

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

  2. Bekijk de uitvoer van de vorige opdracht. Noteer de waarde van de Id eigenschap voor dit account omdat deze in de volgende stap moet worden gebruikt.

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

    Notitie

    In dit voorbeeld is /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/msdocs-identity-example/providers/Microsoft.DocumentDB/databaseAccounts/msdocs-identity-example-nosqlde Id waarde . In dit voorbeeld worden fictieve gegevens gebruikt en uw id is anders dan in dit voorbeeld.

  3. Gebruik New-AzCosmosDBSqlRoleAssignment dit om de nieuwe rol toe te wijzen. Gebruik de eerder vastgelegde roldefinitie-id's voor de RoleDefinitionId parameter en de unieke id voor uw identiteit voor de PrincipalId parameter. Gebruik ten slotte de id van uw account voor de 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. Vermeld alle roltoewijzingen voor uw Azure Cosmos DB for NoSQL-account met behulp van Get-AzCosmosDBSqlRoleAssignment. Controleer de uitvoer om ervoor te zorgen dat uw roltoewijzing is gemaakt.

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

Toegang tot het gegevensvlak valideren in code

Controleer ten slotte of u op de juiste wijze toegang hebt verleend met behulp van toepassingscode en de Azure SDK in de programmeertaal van uw voorkeur.

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

string endpoint = "<account-endpoint>";

TokenCredential credential = new DefaultAzureCredential();

CosmosClient client = new(endpoint, credential);

Belangrijk

In dit codevoorbeeld worden de Microsoft.Azure.Cosmos en Azure.Identity bibliotheken van NuGet gebruikt.