Freigeben über

Konfigurieren der rollenbasierten Zugriffssteuerung mit Microsoft Entra ID für Ihr Azure Cosmos DB-Konto

  • Artikel

GILT FÜR: NoSQL

Hinweis

In diesem Artikel geht es um die rollenbasierte Zugriffssteuerung für Vorgänge auf Datenebene in Azure Cosmos DB. Falls Sie Vorgänge auf Verwaltungsebene verwenden, finden Sie weitere Informationen in dem Artikel zur rollenbasierten Zugriffssteuerung, die für Vorgänge auf Verwaltungsebene angewendet wird.

Azure Cosmos DB bietet ein integriertes System für die rollenbasierte Zugriffssteuerung, das folgende Möglichkeiten umfasst:

  • Authentifizieren Sie Ihre Datenanforderungen mit einer Microsoft Entra-Identität.
  • Autorisieren Ihrer Datenanforderungen mit einem differenzierten, rollenbasierten Berechtigungsmodell

Konzepte

Die rollenbasierte Zugriffssteuerung der Azure Cosmos DB-Datenebene basiert auf Konzepten, die häufig in anderen rollenbasierten Zugriffssteuerungssystemen wie der rollenbasierten Zugriffssteuerung in Azure zu finden sind:

  • Das Berechtigungsmodell besteht aus einer Reihe von Aktionen, die jeweils einem oder mehreren Datenbankvorgängen zugeordnet sind. Einige Beispiele für Aktionen sind das Lesen eines Elements, das Schreiben eines Elements oder das Ausführen einer Abfrage.
  • Azure Cosmos DB-Benutzer erstellen Rollendefinitionen , die eine Liste zulässiger Aktionen enthalten.
  • Rollendefinitionen werden mithilfe von Rollenzuweisungen bestimmten Microsoft Entra-Identitäten zugewiesen. Eine Rollenzuweisung definiert auch den Bereich, auf den die Rollendefinition angewendet wird. Derzeit gibt es drei Bereiche:
    • Azure Cosmos DB-Konto
    • Azure Cosmos DB-Datenbank
    • Azure Cosmos DB-Container

Diagramm häufiger rollenbasierter Zugriffssteuerungskonzepte, einschließlich Rollendefinitionen, Rollenzuweisungen und Prinzipalen.

Berechtigungsmodell

Wichtig

Dieses Berechtigungsmodell deckt nur Datenbankvorgänge ab, die das Lesen und Schreiben von Daten umfassen. Es deckt keine Verwaltungsvorgänge für Verwaltungsressourcen ab. Dies umfasst Folgendes:

  • Erstellen/Ersetzen/Löschen von Datenbanken
  • Erstellen/Ersetzen/Löschen von Containern
  • Lesen/Ersetzen des Containerdurchsatzes
  • Erstellen/Ersetzen/Löschen/Lesen gespeicherter Prozeduren
  • Erstellen/Ersetzen/Löschen/Lesen von Triggern
  • Erstellen/Ersetzen/Löschen/Lesen benutzerdefinierter Funktionen

Sie können kein SDK auf Azure Cosmos DB-Datenebene verwenden, um Verwaltungsvorgänge mit einer Microsoft Entra-Identität zu authentifizieren. Stattdessen müssen Sie rollenbasierte Zugriffssteuerung in Azure über eine der folgenden Optionen verwenden:

„Datenbank lesen“ und „Container lesen“ werden als Metadatenanforderungen betrachtet. Der Zugriff auf diese Vorgänge kann wie im folgenden Abschnitt beschrieben gewährt werden.

In dieser Tabelle sind alle Aktionen aufgeführt, die vom Berechtigungsmodell bereitgestellt werden.

Name Entsprechende Datenbankvorgänge
Microsoft.DocumentDB/databaseAccounts/readMetadata Lesen von Kontometadaten. Ausführliche Informationen finden Sie unter Metadatenanforderungen.
Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/items/create Erstellen eines neuen Elements.
Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/items/read Lesen eines einzelnen Elements anhand seiner ID und seines Partitionsschlüssels (Punktlesevorgang).
Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/items/replace Ersetzen eines vorhandenen Elements.
Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/items/upsert Upsert eines Elements ausführen. Dieser Vorgang erstellt ein Element, wenn es noch nicht vorhanden ist, oder ersetzt ein Element, wenn es bereits vorhanden ist.
Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/items/delete Löschen eines Elements.
Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/executeQuery Ausführen einer SQL-Abfrage.
Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/readChangeFeed Lesen aus dem Änderungsfeed des Containers. Führen Sie SQL-Abfragen mithilfe der SDKs aus.
Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/executeStoredProcedure Ausführen einer gespeicherten Prozedur.
Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/manageConflicts Verwalten von Konflikten für Konten mit mehreren Schreibregionen (d. h. Auflisten und Löschen von Elementen aus dem Konfliktfeed).

Hinweis

Beim Ausführen von Abfragen über die SDKs sind sowohl Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/executeQuery- als auch Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/readChangeFeed-Berechtigungen erforderlich.

Platzhalter werden sowohl auf Containerebene als auch auf Elementebene unterstützt:

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

Metadatenanforderungen

Azure Cosmos DB-SDKs geben während der Initialisierung und zur Verarbeitung bestimmter Datenanforderungen schreibgeschützte Metadatenanforderungen aus. Diese Anforderungen rufen verschiedene Konfigurationsdetails ab. Dazu gehören beispielsweise:

  • Die globale Konfiguration Ihres Kontos, einschließlich der Azure-Regionen, in denen das Konto verfügbar ist
  • Der Partitionsschlüssel Ihrer Container oder deren Indizierungsrichtlinie
  • Die Liste der physischen Partitionen, die einen Container und seine Adressen bilden

Es werden keine Daten abgerufen, die Sie in Ihrem Konto gespeichert haben.

Um bestmögliche Transparenz des Berechtigungsmodells sicherzustellen, werden diese Metadatenanforderungen explizit durch die Aktion Microsoft.DocumentDB/databaseAccounts/readMetadata abgedeckt. Diese Aktion sollte in jeder Situation zulässig sein, in der über eines der Azure Cosmos DB-SDKs auf Ihr Azure Cosmos DB-Konto zugegriffen wird. Sie kann auf jeder Ebene in der Azure Cosmos DB-Hierarchie (d. h. Konto, Datenbank oder Container) zugewiesen werden (über eine Rollenzuweisung).

Die tatsächlich von der Aktion Microsoft.DocumentDB/databaseAccounts/readMetadata zugelassenen Metadatenanforderungen richten sich nach dem Bereich, dem die Aktion zugewiesen ist:

Bereich Von der Aktion zugelassene Anforderungen
Konto • Auflisten der Datenbanken unter dem Konto
• Für jede Datenbank unter dem Konto: die zulässigen Aktionen im Datenbankbereich
Datenbank • Lesen von Datenbankmetadaten
• Auflisten der Container unter der Datenbank
• Für jeden Container unter der Datenbank: die zulässigen Aktionen im Containerbereich
Container • Lesen von Containermetadaten
• Auflisten physischer Partitionen unter dem Container
• Auflösen der Adresse der einzelnen physischen Partitionen

Wichtig

Der Durchsatz ist nicht in den Metadaten für diese Aktion enthalten.

Definitionen integrierter Rollen

Azure Cosmos DB macht zwei integrierte Rollendefinitionen verfügbar:

Wichtig

Der Begriff Rollendefinitionen bezieht sich hier auf für Azure Cosmos DB spezifische Rollendefinitionen. Diese unterscheiden sich von Rollendefinitionen der rollenbasierten Zugriffssteuerung in Azure.

ID Name Eingeschlossene Aktionen
00000000-0000-0000-0000-000000000001 Integrierter Cosmos DB-Datenleser 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 Integrierter Mitwirkender an Cosmos DB-Daten Microsoft.DocumentDB/databaseAccounts/readMetadata
Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/*
Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/items/*

Erstellen benutzerdefinierter Rollendefinitionen

Beim Erstellen einer benutzerdefinierten Rollendefinition müssen Sie Folgendes angeben:

  • Den Namen Ihres Azure Cosmos DB-Kontos.
  • Die Ressourcengruppe, die Ihr Konto enthält.
  • Den Typ der Rollendefinition: CustomRole
  • Den Namen der Rollendefinition.
  • Eine Liste von Aktionen, die von der Rolle zugelassen werden sollen.
  • Mindestens ein Bereich, in dem die Rollendefinition zugewiesen werden kann; folgende Bereiche werden unterstützt:
    • / (Kontoebene)
    • /dbs/<database-name> (Datenbankebene)
    • /dbs/<database-name>/colls/<container-name> (Containerebene)

Hinweis

Die beschriebenen Vorgänge sind verfügbar in:

Verwenden von Azure PowerShell

Erstellen Sie eine Rolle mit dem Namen MyReadOnlyRole, die nur Leseaktionen enthält:

$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 "/"

Erstellen Sie eine Rolle mit dem Namen MyReadWriteRole, die alle Aktionen enthält:

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 "/"

Listen Sie die Rollendefinitionen auf, die Sie zum Abrufen der jeweiligen IDs erstellt haben:

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>}

Verwenden der Azure CLI

Erstellen Sie eine Rolle namens MyReadOnlyRole, die nur Leseaktionen in einer Datei mit dem Namen role-definition-ro.json enthält:

{
    "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

Erstellen Sie eine Rolle namens MyReadWriteRole, die alle Aktionen in einer Datei mit dem Namen role-definition-rw.json enthält:

{
    "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

Listen Sie die Rollendefinitionen auf, die Sie zum Abrufen der jeweiligen IDs erstellt haben:

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

Verwenden von Azure-Ressourcen-Manager-Vorlagen

Unter Microsoft.DocumentDB databaseAccounts/sqlRoleDefinitions finden Sie eine Referenz und Beispiele für die Verwendung von Azure Resource Manager-Vorlagen zum Erstellen von Rollendefinitionen.

Erstellen von Rollenzuweisung

Sie können integrierte oder benutzerdefinierte Rollendefinitionen Ihren Microsoft Entra-Identitäten zuordnen. Beim Erstellen einer Rollenzuweisung müssen Sie Folgendes angeben:

  • Den Namen Ihres Azure Cosmos DB-Kontos.

  • Die Ressourcengruppe, die Ihr Konto enthält.

  • Die ID der zuzuweisenden Rollendefinition.

  • Die Prinzipal-ID der Identität, der die Rollendefinition zugewiesen werden soll.

  • Den Bereich der Rollenzuweisung. Folgende Bereiche werden unterstützt:

    • / (Kontoebene)
    • /dbs/<database-name> (Datenbankebene)
    • /dbs/<database-name>/colls/<container-name> (Containerebene)

    Der Geltungsbereich muss mit einem der zuweisbaren Geltungsbereiche der Rollendefinition übereinstimmen oder ein Unterbereich davon sein.

Hinweis

Wenn Sie eine Rollenzuweisung für einen Dienstprinzipal erstellen möchten, stellen Sie sicher, dass die zugehörige Objekt-ID wie im Abschnitt Unternehmensanwendungen auf dem Blatt Microsoft Entra ID des Portals verwendet wird.

Hinweis

Die beschriebenen Vorgänge sind verfügbar in:

Verwenden von Azure PowerShell

Weisen Sie einer Identität eine Rolle zu:

$resourceGroupName = "<myResourceGroup>"
$accountName = "<myCosmosAccount>"
$readOnlyRoleDefinitionId = "<roleDefinitionId>" # as fetched above
# For Service Principals make sure to use the Object ID as found in the Enterprise applications section of the Azure Active Directory portal blade.
$principalId = "<aadPrincipalId>"
New-AzCosmosDBSqlRoleAssignment -AccountName $accountName `
    -ResourceGroupName $resourceGroupName `
    -RoleDefinitionId $readOnlyRoleDefinitionId `
    -Scope "/" `
    -PrincipalId $principalId

Verwenden der Azure-Befehlszeilenschnittstelle

Weisen Sie einer Identität eine Rolle zu:

resourceGroupName='<myResourceGroup>'
accountName='<myCosmosAccount>'
readOnlyRoleDefinitionId='<roleDefinitionId>' # as fetched above
# For Service Principals make sure to use the Object ID as found in the Enterprise applications section of the Azure Active Directory portal blade.
principalId='<aadPrincipalId>'
az cosmosdb sql role assignment create --account-name $accountName --resource-group $resourceGroupName --scope "/" --principal-id $principalId --role-definition-id $readOnlyRoleDefinitionId --principal-type "ServicePrincipal"

Verwenden von Bicep/Azure Resource Manager-Vorlagen

Für eine integrierte Zuweisung mithilfe einer Bicep-Vorlage:

resource sqlRoleAssignment 'Microsoft.DocumentDB/databaseAccounts/sqlRoleAssignments@2023-04-15' = {
  name: guid(<roleDefinitionId>, <aadPrincipalId>, <databaseAccountResourceId>)
  parent: databaseAccount
  properties:{
    principalId: <aadPrincipalId>
    roleDefinitionId: '/${subscription().id}/resourceGroups/<databaseAccountResourceGroup>/providers/Microsoft.DocumentDB/databaseAccounts/<myCosmosAccount>/sqlRoleDefinitions/<roleDefinitionId>'
    scope: <databaseAccountResourceId>
  }
}

Unter Microsoft.DocumentDB databaseAccounts/sqlRoleAssignments finden Sie eine Referenz und Beispiele für die Verwendung von Azure Resource Manager-Vorlagen zum Erstellen von Rollenzuweisungen.

Initialisieren des SDK mit Microsoft Entra ID

Wenn Sie die rollenbasierte Zugriffsteuerung inAzure Cosmos DB in Ihrer Anwendung verwenden möchten, müssen Sie die Methode zur Initialisierung des Azure Cosmos DB-SDK aktualisieren. Anstatt den Primärschlüssel Ihres Kontos zu übergeben, müssen Sie eine Instanz einer TokenCredential-Klasse übergeben. Diese Instanz stellt das Azure Cosmos DB SDK mit dem Kontext bereit, der zum Abrufen eines Microsoft Entra-Tokens im Namen der Identität erforderlich ist, die Sie verwenden möchten.

Die Methode zur Erstellung einer TokenCredential-Instanz wird in diesem Artikel nicht behandelt. Es gibt viele Möglichkeiten, eine solche Instanz zu erstellen, abhängig vom Typ der Microsoft Entra-Identität, die Sie verwenden möchten (Benutzerprinzipal, Dienstprinzipal, Gruppe usw.). Am wichtigsten ist, dass Ihre TokenCredential-Instanz in die Identität (Prinzipal-ID) aufgelöst werden muss, der Sie die Rollen zugewiesen haben. Beispiele für das Erstellen einer TokenCredential-Klasse finden Sie hier:

In den folgenden Beispielen wird ein Dienstprinzipal mit einer ClientSecretCredential-Instanz verwendet.

In .NET

Die rollenbasierte Zugriffssteuerung in Azure Cosmos DB wird derzeit im .NET-SDK V3 unterstützt.

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

In Java

Die rollenbasierte Zugriffssteuerung in Azure Cosmos DB wird derzeit im Java-SDK V4 unterstützt.

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();

In JavaScript

Die rollenbasierte Zugriffssteuerung in Azure Cosmos DB wird derzeit im JavaScript-SDK V3 unterstützt.

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

In Python

Die rollenbasierte Zugriffssteuerung in Azure Cosmos DB wird von den Python-SDK-Versionen 4.3.0b4 und höher unterstützt.

aad_credentials = ClientSecretCredential(
    tenant_id="<azure-ad-tenant-id>",
    client_id="<client-application-id>",
    client_secret="<client-application-secret>")
client = CosmosClient("<account-endpoint>", aad_credentials)

Authentifizieren von Anforderungen an die REST-API

Legen Sie beim Erstellen des REST-API-Autorisierungsheaders den Parameter Typ auf Microsoft Entra ID und die Hashsignatur (sig) auf das OAuth-Token fest, wie im folgenden Beispiel gezeigt:

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

Verwenden des Daten-Explorers

Die Verwendung der rollenbasierten Zugriffssteuerung von Azure Cosmos DB im Daten-Explorer (entweder im Azure-Portal oder unter https://cosmos.azure.com) wird von der Einstellung Entra ID-RBAC aktivieren gesteuert. Sie können über das Radsymbol oben rechts in der Daten-Explorer-Benutzeroberfläche auf diese Einstellung zugreifen.

Die Einstellung besitzt drei mögliche Werte:

  • Automatisch (Standard): In diesem Modus wird die rollenbasierte Zugriffssteuerung automatisch verwendet, wenn das Konto die Verwendung von Schlüsseln deaktiviert hat. Andernfalls verwendet der Daten-Explorer Kontoschlüssel für Datenanforderungen.

  • TRUE: In diesem Modus wird der rollenbasierte Zugriff immer für Datenanforderungen des Daten-Explorers verwendet. Wenn der rollenbasierte Zugriff nicht für das Konto aktiviert wurde, schlägt die Anforderung fehl.

  • FALSE: In diesem Modus werden immer Kontoschlüssel für Datenanforderungen des Daten-Explorers verwendet. Wenn die Verwendung von Schlüsseln für das Konto deaktiviert wurde, schlagen die Anforderungen fehl.

Wenn Sie Modi verwenden, die den rollenbasierten Zugriff im Daten-Explorer des Azure Portals ermöglichen, müssen Sie vor dem Senden von Datenanforderungen (in der Befehlsleiste des Daten-Explorers) auf die Schaltfläche Für Entra ID-RBAC anmelden klicken, bevor Sie Datenanforderungen senden. Dies ist bei Verwendung des Cosmos Explorers auf cosmos.azure.com nicht notwendig. Stellen Sie sicher, dass der angemeldeten Identität die angemessenen Rollendefinitionen zugewiesen wurden, um den Datenzugriff zu ermöglichen.

Beachten Sie außerdem, dass das Ändern des Modus in einen Modus, der Kontoschlüssel verwendet, möglicherweise dazu führt, dass im Namen der angemeldeten Identität eine Anforderung zum Abrufen des Primärschlüssels gesendet wird.

Hinweis

Zuvor wurde der rollenbasierte Zugriff im Cosmos-Explorer nur mit https://cosmos.azure.com/?feature.enableAadDataPlane=true unterstützt. Dies wird weiterhin unterstützt und setzt den Wert der Einstellung Entra ID-RBAC aktivieren außer Kraft. Die Verwendung dieses Abfrageparameters entspricht der Verwendung des oben erwähnten Modus „TRUE“.

Überwachen von Datenanforderungen

Diagnoseprotokolle werden bei Verwendung der rollenbasierten Zugriffssteuerung in Azure Cosmos DB mit Identitäts- und Autorisierungsinformationen für jeden Datenvorgang erweitert. Mit dieser Erweiterung können Sie eine detaillierte Überwachung durchführen und die Microsoft Entra-Identität abrufen, die für jede Datenanforderung verwendet wird, die an Ihr Azure Cosmos DB-Konto gesendet wird.

Diese zusätzlichen Informationen fließen in die Protokollkategorie DataPlaneRequests ein und umfassen zwei zusätzliche Spalten:

  • aadPrincipalId_g zeigt die Prinzipal-ID der Microsoft Entra-Identität an, die zum Authentifizieren der Anforderung verwendet wurde.
  • aadAppliedRoleAssignmentId_g gibt die Rollenzuweisung an, die beim Autorisieren der Anforderung berücksichtigt wurde.

Erzwingen der rollenbasierten Zugriffssteuerung als einzige Authentifizierungsmethode

In Situationen, in denen Clients ausschließlich über die rollenbasierte Zugriffssteuerung eine Verbindung mit Azure Cosmos DB herstellen sollen, können Sie die primären/sekundären Schlüssel des Kontos deaktivieren. Daraufhin werden alle eingehenden Anforderungen, bei denen entweder ein primärer oder sekundärer Schlüssel oder ein Ressourcentoken verwendet wird, aktiv abgelehnt.

Verwenden von Azure-Ressourcen-Manager-Vorlagen

Legen Sie die Eigenschaft disableLocalAuth auf true fest, wenn Sie Ihr Azure Cosmos DB-Konto mithilfe von Azure Resource Manager-Vorlagen erstellen oder aktualisieren:

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

Einschränkungen

  • Sie können bis zu 100 Rollendefinitionen und 2.000 Rollenzuweisungen pro Azure Cosmos DB-Konto erstellen.
  • Sie können Rollendefinitionen nur Microsoft Entra-Identitäten zuweisen, die zum selben Microsoft Entra-Mandanten wie Ihr Azure Cosmos DB-Konto.
  • Die Auflösung von Microsoft Entra-Gruppen wird derzeit für Identitäten, die zu mehr als 200 Gruppen gehören, nicht unterstützt.
  • Das Microsoft Entra-Token wird derzeit als Header mit jeder einzelnen Anforderung übergeben, die an den Azure Cosmos DB-Dienst gesendet wird und die Gesamtnutzlastgröße erhöht.

Häufig gestellte Fragen

Dieser Abschnitt enthält häufig gestellte Fragen zur rollenbasierten Zugriffssteuerung und Azure Cosmos DB.

Welche Azure Cosmos DB-APIs unterstützen die rollenbasierte Zugriffssteuerung für die Datenebene?

Derzeit wird nur die NoSQL-API unterstützt.

Können Rollendefinitionen und Rollenzuweisungen über das Azure-Portal verwaltet werden?

Eine Unterstützung für die Rollenverwaltung ist im Azure-Portal noch nicht verfügbar.

Welche SDKs in der Azure Cosmos DB-API für NoSQL unterstützen die rollenbasierte Zugriffssteuerung?

.NET V3-, Java V4-, JavaScript V3- und Python V4.3+-SDK werden derzeit unterstützt.

Wird das Microsoft Entra-Token bei Ablauf automatisch von den Azure Cosmos DB-SDKs aktualisiert?

Ja.

Kann die Verwendung der Primär-/Sekundärschlüssel für das Konto bei Nutzung der rollenbasierten Zugriffssteuerung deaktiviert werden?

Ja, siehe Erzwingen der rollenbasierten Zugriffssteuerung als einzige Authentifizierungsmethode.

Nächste Schritte