Freigeben über

Verwenden der rollenbasierten Zugriffssteuerung auf Datenebene mit Azure Cosmos DB for NoSQL

  • Artikel

GILT FÜR: NoSQL

Abbildung: Aktuelle Phase („Rollenbasierte Zugriffssteuerung“) in der Sequenz des Bereitstellungsleitfadens

Tipp

Besuchen Sie unsere neue Samples Gallery für die neuesten Beispiele zum Erstellen neuer Apps

In diesem Artikel werden die Schritte zum Gewähren des Zugriffs für eine Identität zum Verwalten von Daten in einem Azure Cosmos DB for NoSQL-Konto erläutert.

Wichtig

Die Schritte in diesem Artikel umfassen nur den Zugriff auf Datenebene, um Vorgänge für einzelne Elemente und Abfragen auszuführen. Informationen zum Verwalten von Rollen, Definitionen und Zuweisungen für die Steuerungsebene finden Sie unter Gewähren des rollenbasierten Zugriffs auf Steuerungsebene.

Voraussetzungen

  • Ein Azure-Konto mit einem aktiven Abonnement. Sie können kostenlos ein Konto erstellen.
  • Ein vorhandenes Azure Cosmos DB for NoSQL-Konto
  • Mindestens eine Identität in Microsoft Entra ID

  • Verwenden Sie die Bash-Umgebung in Azure Cloud Shell. Weitere Informationen finden Sie unter Schnellstart für Bash in Azure Cloud Shell.

  • Wenn Sie CLI-Referenzbefehle lieber lokal ausführen, installieren Sie die Azure CLI. Wenn Sie Windows oder macOS ausführen, sollten Sie die Azure CLI in einem Docker-Container ausführen. Weitere Informationen finden Sie unter Ausführen der Azure CLI in einem Docker-Container.

    • Wenn Sie eine lokale Installation verwenden, melden Sie sich mithilfe des Befehls az login bei der Azure CLI an. Führen Sie die in Ihrem Terminal angezeigten Schritte aus, um den Authentifizierungsprozess abzuschließen. Informationen zu anderen Anmeldeoptionen finden Sie unter Anmelden mit der Azure CLI.

    • Installieren Sie die Azure CLI-Erweiterung beim ersten Einsatz, wenn Sie dazu aufgefordert werden. Weitere Informationen zu Erweiterungen finden Sie unter Verwenden von Erweiterungen mit der Azure CLI.

    • Führen Sie az version aus, um die installierte Version und die abhängigen Bibliotheken zu ermitteln. Führen Sie az upgrade aus, um das Upgrade auf die aktuelle Version durchzuführen.

Vorbereiten der Rollendefinition

Zunächst müssen Sie eine Rollendefinition mit einer Liste von dataActions vorbereiten, um Zugriff zum Lesen, Abfragen und Verwalten von Daten in Azure Cosmos DB for NoSQL zu gewähren.

Wichtig

Zum Abrufen einer vorhandenen Rollendefinition für Datenebenen sind die folgenden Berechtigungen für die Steuerungsebene erforderlich:

  • Microsoft.DocumentDB/databaseAccounts/sqlRoleDefinitions/read

Weitere Informationen finden Sie unter gewähren rollenbasierten Zugriff auf Steuerebenen.

Listen Sie mithilfe von az cosmosdb sql role definition list alle Rollendefinitionen auf, die Ihrem Azure Cosmos DB for NoSQL-Konto zugeordnet sind. Überprüfen Sie die Ausgabe, und suchen Sie die Rollendefinition namens Integrierter Mitwirkender an Cosmos DB-Daten. Die Ausgabe enthält den eindeutigen Bezeichner der Rollendefinition in der id-Eigenschaft. Notieren Sie diesen Wert, da er im Zuweisungsschritt weiter unten in diesem Leitfaden verwendet werden muss.

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

Hinweis

In diesem Beispiel wäre der Wert 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. In diesem Beispiel werden fiktive Daten verwendet, Ihr Bezeichner unterscheidet sich daher von diesem Beispiel.

Verwenden Sie Get-AzCosmosDBSqlRoleDefinition, um alle Rollendefinitionen aufzulisten, die Ihrem Azure Cosmos DB for NoSQL-Konto zugeordnet sind. Überprüfen Sie die Ausgabe, und suchen Sie die Rollendefinition namens Integrierter Mitwirkender an Cosmos DB-Daten. Die Ausgabe enthält den eindeutigen Bezeichner der Rollendefinition in der Id-Eigenschaft. Notieren Sie diesen Wert, da er im Zuweisungsschritt weiter unten in diesem Leitfaden verwendet werden muss.

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

Hinweis

In diesem Beispiel wäre der Wert 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. In diesem Beispiel werden fiktive Daten verwendet, Ihr Bezeichner unterscheidet sich daher von diesem Beispiel. Der Bezeichner (00000000-0000-0000-0000-000000000002) ist jedoch für alle Rollendefinitionen in Ihrem Konto eindeutig.

Zuweisen einer Rolle zur Identität

Weisen Sie nun die neu definierte Rolle einer Identität zu, damit Ihre Anwendungen auf Daten in Azure Cosmos DB for NoSQL zugreifen können.

Wichtig

Zum Erstellen einer neuen Rollenzuweisung für Datenebenen sind die folgenden Berechtigungen für die Steuerungsebene erforderlich:

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

Weitere Informationen finden Sie unter gewähren rollenbasierten Zugriff auf Steuerebenen.

  1. Verwenden Sie az cosmosdb show, um den eindeutigen Bezeichner für Ihr aktuelles Konto abzurufen.

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

  2. Sehen Sie sich die Ausgabe des vorherigen Befehls an. Notieren Sie den Wert der id-Eigenschaft für dieses Konto, da er im nächsten Schritt verwendet werden muss.

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

    Hinweis

    In diesem Beispiel wäre der Wert id /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/msdocs-identity-example/providers/Microsoft.DocumentDB/databaseAccounts/msdocs-identity-example-nosql. In diesem Beispiel werden fiktive Daten verwendet, Ihr Bezeichner unterscheidet sich daher von diesem Beispiel.

  3. Weisen Sie die neue Rolle mithilfe von az cosmosdb sql role assignment create zu. Verwenden Sie die zuvor notierten Rollendefinitionsbezeichner für das Argument --role-definition-id und den eindeutigen Bezeichner für Ihre Identität für das Argument --principal-id. Verwenden Sie schließlich den Bezeichner Ihres Kontos für das Argument --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. Verwenden Sie az cosmosdb sql role assignment list, um alle Rollenzuweisungen für Ihr Azure Cosmos DB for NoSQL-Konto aufzulisten. Überprüfen Sie die Ausgabe, um sicherzustellen, dass Ihre Rollenzuweisung erstellt wurde.

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

  1. Erstellen Sie eine neue Bicep-Datei, um Ihre Rollenzuweisung zu definieren. Geben Sie der Datei den Namen 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. Erstellen Sie eine neue Bicep-Parameterdatei mit dem Namen data-plane-role-assignment.bicepparam. Weisen Sie in dieser Parameterdatei den Namen Ihres vorhandenen Azure Cosmos DB for NoSQL-Kontos dem Parameter accountName, die zuvor notierten Rollendefinitionsbezeichner dem Parameter roleDefinitionId und den eindeutigen Bezeichner für Ihre Identität dem Parameter identityId zu.

    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. Bereitstellen der Bicep-Vorlage mithilfe von 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. Wiederholen Sie diese Schritte, um den Zugriff auf das Konto von allen anderen Identitäten zu gewähren, die Sie verwenden möchten.

    Tipp

    Sie können diese Schritte für beliebig viele Identitäten wiederholen. In der Regel werden diese Schritte mindestens wiederholt, um Entwicklern den Zugriff auf ein Konto mithilfe ihrer menschlichen Identität und den Zugriff auf Anwendungen mithilfe einer verwalteten Identität zu ermöglichen.

  1. Verwenden Sie Get-AzCosmosDBAccount, um die Metadaten für Ihr aktuelles Konto abzurufen.

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

  2. Sehen Sie sich die Ausgabe des vorherigen Befehls an. Notieren Sie den Wert der Id-Eigenschaft für dieses Konto, da er im nächsten Schritt verwendet werden muss.

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

    Hinweis

    In diesem Beispiel wäre der Wert Id /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/msdocs-identity-example/providers/Microsoft.DocumentDB/databaseAccounts/msdocs-identity-example-nosql. In diesem Beispiel werden fiktive Daten verwendet, Ihr Bezeichner unterscheidet sich daher von diesem Beispiel.

  3. Verwenden Sie New-AzCosmosDBSqlRoleAssignment, um die neue Rolle zuzuweisen. Verwenden Sie die zuvor notierten Rollendefinitionsbezeichner für den Parameter RoleDefinitionId und den eindeutigen Bezeichner für Ihre Identität für den Parameter PrincipalId. Verwenden Sie schließlich den Bezeichner Ihres Kontos für den Parameter Scope.

    $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. Listen Sie alle Rollenzuweisungen für Ihr Azure Cosmos DB for NoSQL-Konto mithilfe von Get-AzCosmosDBSqlRoleAssignment auf. Überprüfen Sie die Ausgabe, um sicherzustellen, dass Ihre Rollenzuweisung erstellt wurde.

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

Überprüfen des Zugriffs auf Datenebene im Code

Überprüfen Sie schließlich mithilfe von Anwendungscode und dem Azure SDK in Ihrer bevorzugten Sprache, ob Sie den Zugriff ordnungsgemäß gewährt haben.

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

string endpoint = "<account-endpoint>";

TokenCredential credential = new DefaultAzureCredential();

CosmosClient client = new(endpoint, credential);

Wichtig

In diesem Codebeispiel werden die Bibliotheken Microsoft.Azure.Cosmos und Azure.Identity von NuGet verwendet.