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

GILT FÜR: NoSQL

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

Berechtigungsmodell

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

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:

Definitionen integrierter Rollen

Azure Cosmos DB macht zwei integrierte Rollendefinitionen verfügbar:

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)

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.

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 .NET
• In Java
• In JavaScript
• In Python

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.

Ü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

• Verschaffen Sie sich einen Überblick über den sicheren Zugriff auf Daten in Azure Cosmos DB.
• Erfahren Sie mehr über die rollenbasierte Zugriffssteuerung für die Azure Cosmos DB-Verwaltung.