Se connecter à Azure Cosmos DB pour NoSQL à l’aide du contrôle d’accès en fonction du rôle et de l’ID Microsoft Entra

S’applique à: ✅ NoSQL

Le contrôle d’accès en fonction du rôle fait référence à une méthode permettant de gérer l’accès aux ressources dans Azure. Cette méthode est basée sur des identités spécifiques affectées aux rôles qui gèrent le niveau d’accès dont ils ont besoin pour une ou plusieurs ressources. Le contrôle d’accès en fonction du rôle fournit un système flexible de gestion des accès affiné qui garantit que les identités disposent uniquement du niveau d’accès le moins privilégié dont ils ont besoin pour effectuer leur tâche.

Pour plus d’informations, consultez le contrôle d’accès en fonction du rôle.

Prerequisites

Un compte Azure avec un abonnement actif. Créez un compte gratuitement.
Un compte Azure Cosmos DB pour NoSQL existant.
Une ou plusieurs identités existantes dans Microsoft Entra ID.

Utilisez l’environnement Bash dans Azure Cloud Shell. Pour obtenir plus d’informations, consultez Démarrage d’Azure Cloud Shell.
Si vous préférez exécuter des commandes de référence CLI localement, installez Azure CLI. Si vous exécutez sur Windows ou macOS, envisagez d’exécuter Azure CLI dans un conteneur Docker. Pour plus d’informations, consultez Comment exécuter Azure CLI dans un conteneur Docker.
- Si vous utilisez une installation locale, connectez-vous à Azure CLI à l’aide de la commande az login. Pour terminer le processus d’authentification, suivez les étapes affichées dans votre terminal. Pour obtenir d’autres options de connexion, consultez S’authentifier auprès d’Azure à l’aide d’Azure CLI.
- Lorsque vous y êtes invité, installez l’extension Azure CLI lors de la première utilisation. Pour plus d’informations sur les extensions, consultez Utiliser et gérer des extensions avec Azure CLI.
- Exécutez az version pour rechercher la version et les bibliothèques dépendantes installées. Pour effectuer une mise à niveau vers la dernière version, exécutez az upgrade.

Si vous choisissez d’utiliser Azure PowerShell localement :
- Installez la dernière version du module Az PowerShell.
- Connectez-vous à votre compte Azure à l’aide de la cmdlet Connect-AzAccount.
Si vous choisissez d’utiliser Azure Cloud Shell :
- Pour plus d’informations, consultez Vue d’ensemble d’Azure Cloud Shell.

Désactiver l’authentification basée sur des clés

La désactivation de l’autorisation basée sur des clés empêche votre compte d’être utilisé sans la méthode d’authentification Microsoft Entra ID plus sécurisée. Cette procédure est une étape qui doit être effectuée sur de nouveaux comptes dans des charges de travail sécurisées. Vous pouvez également effectuer cette procédure sur les comptes existants en cours de migration vers un modèle de charge de travail sécurisé.

Tout d’abord, désactivez l’authentification basée sur des clés sur votre compte existant afin que les applications soient requises pour utiliser l’authentification d’ID Microsoft Entra. Utilisez az resource update pour modifier properties.disableLocalAuth du compte existant.

az resource update \
    --resource-group "<name-of-existing-resource-group>" \
    --name "<name-of-existing-account>" \
    --resource-type "Microsoft.DocumentDB/databaseAccounts" \
    --set properties.disableLocalAuth=true

Tout d’abord, créez un compte avec l’authentification basée sur des clés désactivée afin que les applications soient requises pour utiliser l’authentification Microsoft Entra.

Créez un fichier Bicep pour déployer votre nouveau compte avec l’authentification basée sur des clés désactivée. Nommez le fichier deploy-new-account.bicep.

metadata description = 'Deploys a new Azure Cosmos DB account with key-based auth disabled.'

@description('Name of the Azure Cosmos DB account.')
param name string = 'csms-${uniqueString(resourceGroup().id)}'

@description('Primary location for the Azure Cosmos DB account.')
param location string = resourceGroup().location

resource account 'Microsoft.DocumentDB/databaseAccounts@2024-05-15' = {
  name: name
  location: location
  kind: 'GlobalDocumentDB'
  properties: {
    databaseAccountOfferType: 'Standard'
    locations: [
      {
        locationName: location
      }
    ]
    disableLocalAuth: true
  }
}

Utilisez az deployment group create pour déployer le fichier Bicep avec le nouveau compte.

az deployment group create \
    --resource-group "<name-of-existing-resource-group>" \
    --template-file deploy-new-account.bicep

Tout d’abord, désactivez l’authentification basée sur des clés sur votre compte existant afin que les applications soient requises pour utiliser l’authentification Microsoft Entra. Utilisez Get-AzResource pour lire et Set-AzResource pour mettre à jour le compte existant, respectivement.

$parameters = @{
    ResourceGroupName = "<name-of-existing-resource-group>"
    ResourceName = "<name-of-existing-account>"
    ResourceType = "Microsoft.DocumentDB/databaseAccounts"
}
$resource = Get-AzResource @parameters

$resource.Properties.DisableLocalAuth = $true

$resource | Set-AzResource -Force

Utilisez ces étapes pour créer un compte Azure Cosmos DB pour NoSQL avec l’authentification basée sur des clés désactivée afin que les applications soient requises pour utiliser uniquement l’authentification Microsoft Entra.

Lors de la configuration d’un nouveau compte Azure Cosmos DB pour NoSQL, accédez à la section Sécurité du processus de création de compte.
Ensuite, sélectionnez Désactiver pour l’option d’authentification basée sur la clé .

Important

La modification d’un compte Azure Cosmos DB nécessite un rôle Azure avec au moins l’autorisation Microsoft.DocumentDb/databaseAccounts/*/write . Pour plus d’informations, consultez autorisations pour Azure Cosmos DB.

Vérifier que l’authentification basée sur des clés est désactivée

Pour vérifier que l’accès basé sur la clé est désactivé, essayez d’utiliser le Kit de développement logiciel (SDK) Azure pour se connecter à Azure Cosmos DB pour NoSQL à l’aide d’une information d’identification de mot de passe du propriétaire de la ressource (ROPC). Cette tentative doit échouer. Si nécessaire, des exemples de code pour les langages de programmation courants sont fournis ici.

using Microsoft.Azure.Cosmos;

string connectionString = "AccountEndpoint=<nosql-endpoint>;AccountKey=<key>;";

CosmosClient client = new(connectionString);

const { CosmosClient } = require('@azure/cosmos');

const connectionString = 'AccountEndpoint=<nosql-endpoint>;AccountKey=<key>;';

const client = new CosmosClient(connectionString);

import { CosmosClient } from '@azure/cosmos'

let connectionString: string = 'AccountEndpoint=<nosql-endpoint>;AccountKey=<key>;';

const client: CosmosClient = new CosmosClient(connectionString);

from azure.cosmos import CosmosClient

connection_string = "AccountEndpoint=<nosql-endpoint>;AccountKey=<key>;"

client = CosmosClient(connection_string)

package main

import (
    "github.com/Azure/azure-sdk-for-go/sdk/data/azcosmos"
)

const connectionString = "AccountEndpoint=<nosql-endpoint>;AccountKey=<key>;"

func main() {
    client, _ := azcosmos.NewClientFromConnectionString(connectionString, nil)
}

import com.azure.cosmos.CosmosClient;
import com.azure.cosmos.CosmosClientBuilder;

public class NoSQL{
    public static void main(String[] args){
        CosmosClient client = new CosmosClientBuilder()
            .endpoint("<nosql-endpoint>")
            .key("<key>")
            .buildClient();
    }
}

use azure_data_cosmos::CosmosClient;

fn main() {
    let client = CosmosClient::new_with_access_key(
        "<account-endpoint>",
        "<account-key>",
        None,
    ).unwrap();

    let container = client.database_client("<database-name>").container_client("<container-name>");

    let response = container.read_item("<partition-key>", "<item-id>", None);
    tokio::runtime::Runtime::new().unwrap().block_on(response).unwrap();
}

Accorder un accès en fonction du rôle au plan de contrôle

L’accès au plan de contrôle fait référence à la possibilité de gérer des ressources pour un service Azure sans gérer les données. Par exemple, l’accès au plan de contrôle Azure Cosmos DB peut inclure la possibilité de :

Lire toutes les métadonnées de compte et de ressource
Lire et régénérer les clés de compte et les chaînes de connexion
Effectuer des sauvegardes et des restaurations de compte
Démarrer et suivre les travaux de transfert de données
Gérer les bases de données et les conteneurs
Modifier les propriétés du compte

Important

Dans Azure Cosmos DB, vous avez besoin d’un accès au plan de contrôle pour gérer les définitions et les affectations de contrôle d’accès en fonction du rôle natives du plan de données. Étant donné que le mécanisme de contrôle d'accès basé sur les rôles d'Azure Cosmos DB est natif, vous devez disposer d'un accès au plan de gestion pour créer et stocker des définitions et des affectations en tant que ressources dans un compte Azure Cosmos DB.

Tout d’abord, vous devez préparer une définition de rôle avec une liste d’autorisations actions d’accès pour gérer les ressources de compte dans Azure Cosmos DB. Dans ce guide, vous préparez un rôle intégré et personnalisé. Ensuite, affectez le nouveau rôle défini à une identité afin que vos applications puissent accéder aux ressources dans Azure Cosmos DB.

Répertoriez toutes les définitions de rôle associées à votre compte Azure Cosmos DB à l’aide az role definition listde .
```
az role definition list \
    --name "Cosmos DB Operator"
```

Passez en revue la sortie et recherchez la définition de rôle nommée Opérateur Cosmos DB. La sortie contient l’identificateur unique de la définition de rôle dans la id propriété. Enregistrez cette valeur, car il est nécessaire d’utiliser dans l’étape d’affectation plus loin dans ce guide.

[
  {
    "assignableScopes": [
      "/"
    ],
    "description": "Lets you manage Azure Cosmos DB accounts, but not access data in them. Prevents access to account keys and connection strings.",
    "id": "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/providers/Microsoft.Authorization/roleDefinitions/230815da-be43-4aae-9cb4-875f7bd000aa",
    "name": "230815da-be43-4aae-9cb4-875f7bd000aa",
    "permissions": [
      {
        "actions": [
          "Microsoft.DocumentDb/databaseAccounts/*",
          "Microsoft.Insights/alertRules/*",
          "Microsoft.Authorization/*/read",
          "Microsoft.ResourceHealth/availabilityStatuses/read",
          "Microsoft.Resources/deployments/*",
          "Microsoft.Resources/subscriptions/resourceGroups/read",
          "Microsoft.Support/*",
          "Microsoft.Network/virtualNetworks/subnets/joinViaServiceEndpoint/action"
        ],
        "condition": null,
        "conditionVersion": null,
        "dataActions": [],
        "notActions": [
          "Microsoft.DocumentDB/databaseAccounts/dataTransferJobs/*",
          "Microsoft.DocumentDB/databaseAccounts/readonlyKeys/*",
          "Microsoft.DocumentDB/databaseAccounts/regenerateKey/*",
          "Microsoft.DocumentDB/databaseAccounts/listKeys/*",
          "Microsoft.DocumentDB/databaseAccounts/listConnectionStrings/*",
          "Microsoft.DocumentDB/databaseAccounts/sqlRoleDefinitions/write",
          "Microsoft.DocumentDB/databaseAccounts/sqlRoleDefinitions/delete",
          "Microsoft.DocumentDB/databaseAccounts/sqlRoleAssignments/write",
          "Microsoft.DocumentDB/databaseAccounts/sqlRoleAssignments/delete",
          "Microsoft.DocumentDB/databaseAccounts/mongodbRoleDefinitions/write",
          "Microsoft.DocumentDB/databaseAccounts/mongodbRoleDefinitions/delete",
          "Microsoft.DocumentDB/databaseAccounts/mongodbUserDefinitions/write",
          "Microsoft.DocumentDB/databaseAccounts/mongodbUserDefinitions/delete"
        ],
        "notDataActions": []
      }
    ],
    "roleName": "Cosmos DB Operator",
    "roleType": "BuiltInRole",
    "type": "Microsoft.Authorization/roleDefinitions",
  }
]

Note

Dans cet exemple, la id valeur serait /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/providers/Microsoft.Authorization/roleDefinitions/230815da-be43-4aae-9cb4-875f7bd000aa. Cet exemple utilise des données fictives et votre identificateur serait distinct de cet exemple. Toutefois, l’identificateur (230815da-be43-4aae-9cb4-875f7bd000aa) est globalement unique dans toutes les définitions de rôle dans Azure.

Permet az group show d’obtenir les métadonnées de votre groupe de ressources actuel.
```
az group show \
    --name "<name-of-existing-resource-group>"
```
Observez la sortie de la commande précédente. Enregistrez la valeur de la propriété id pour ce groupe de ressources, car elle est nécessaire pour l'utiliser à l'étape suivante.
```
{
  "id": "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/msdocs-identity-example",
  "location": "westus",
  "name": "msdocs-identity-example",
  "type": "Microsoft.Resources/resourceGroups"
}
```
Note

Dans cet exemple, la id valeur serait /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/msdocs-identity-example. Cet exemple utilise des données fictives et votre identificateur serait distinct de cet exemple. Cette chaîne est un exemple tronqué de la sortie.
Créez un fichier JSON nommé role-definition.json. Dans le fichier, créez cette définition de ressource en spécifiant les valeurs répertoriées ici. Dans la liste AssignableScopes, ajoutez la propriété id du groupe de ressources notée à l’étape précédente.
```
{
  "Name": "Azure Cosmos DB Control Plane Owner",
  "IsCustom": true,
  "Description": "Can perform all control plane actions for an Azure Cosmos DB account.",
  "Actions": [
    "Microsoft.DocumentDb/*"
  ],
  "AssignableScopes": [
    "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/msdocs-identity-example"
  ]
}
```
Note

Cet exemple utilise la /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/msdocs-identity-example valeur enregistrée à l’étape précédente. Votre identificateur de ressource réel peut être différent.
Créez une nouvelle définition de rôle à l’aide de az role definition create. Utilisez le fichier role-definition.json comme entrée pour l’argument --role-definition .
```
az role definition create \
    --role-definition role-definition.json
```
Passez en revue la sortie de la commande de création de définition. La sortie contient l’identificateur unique de la définition de rôle dans la id propriété. Enregistrez cette valeur, car il est nécessaire d’utiliser dans l’étape d’affectation plus loin dans ce guide.
```
{
  "assignableScopes": [
    "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/msdocs-identity-example"
  ],
  "description": "Can perform all control plane actions for an Azure Cosmos DB account.",
  "id": "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/msdocs-identity-example/providers/Microsoft.Authorization/roleDefinitions/a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1",
  "name": "e4e4e4e4-ffff-aaaa-bbbb-c5c5c5c5c5c5",
  "permissions": [
    {
      "actions": [
        "Microsoft.DocumentDb/*"
      ]
    }
  ],
  "roleName": "Azure Cosmos DB Control Plane Owner",
  "roleType": "CustomRole"
}
```
Note

Dans cet exemple, la id valeur serait /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/msdocs-identity-example/providers/Microsoft.Authorization/roleDefinitions/a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1. Cet exemple utilise des données fictives et votre identificateur serait distinct de cet exemple. Cet exemple est un sous-ensemble de la sortie JSON typique générée par le déploiement pour plus de clarté.
Permet az group show d’obtenir à nouveau les métadonnées de votre groupe de ressources actuel.
```
az group show \
    --name "<name-of-existing-resource-group>"
```
Observez la sortie de la commande précédente. Enregistrez la valeur de la propriété id pour ce groupe de ressources, car elle est nécessaire pour l'utiliser à l'étape suivante.
```
{
  "id": "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/msdocs-identity-example",
  "location": "westus",
  "name": "msdocs-identity-example",
  "type": "Microsoft.Resources/resourceGroups"
}
```
Note

Dans cet exemple, la id valeur serait /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/msdocs-identity-example. Cet exemple utilise des données fictives et votre identificateur serait distinct de cet exemple. Cette chaîne est un exemple tronqué de la sortie.
Attribuez le nouveau rôle à l'aide de az role assignment create. Utilisez l’identificateur de votre groupe de ressources pour l’argument --scope , l’identificateur du rôle pour l’argument -role et l’identificateur unique de votre identité à l’argument --assignee .
```
az role assignment create \
    --assignee "<your-principal-identifier>" \
    --role "subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/msdocs-identity-example/providers/Microsoft.Authorization/roleDefinitions/a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1" \
    --scope "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/msdocs-identity-example"
```
Note

Dans cet exemple de commande, le scope fictif a été assigné à l’exemple /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/msdocs-identity-example de l’étape précédente. L’identificateur de votre groupe de ressources est distinct de cet exemple. Le role a également été défini sur le /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/msdocs-identity-example/providers/Microsoft.Authorization/roleDefinitions/a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1 fictif. Là encore, votre identificateur de rôle serait distinct.

Observez la sortie de la commande. La sortie inclut un identificateur unique pour l’affectation dans la propriété id.

{
  "id": "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/msdocs-identity-example/providers/Microsoft.Authorization/roleAssignments/a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1",
  "name": "ffffffff-5555-6666-7777-aaaaaaaaaaaa",
  "principalId": "aaaaaaaa-bbbb-cccc-1111-222222222222",
  "resourceGroup": "msdocs-identity-example",
  "roleDefinitionId": "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/msdocs-identity-example/providers/Microsoft.Authorization/roleDefinitions/a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1",
  "scope": "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/msdocs-identity-example",
  "type": "Microsoft.Authorization/roleAssignments"
}

Note

Dans cet exemple, la id propriété est /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/msdocs-identity-example/providers/Microsoft.Authorization/roleAssignments/a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1, qui est un autre exemple fictif.

Répétez ces étapes pour accorder l’accès au compte à partir des autres identités que vous souhaitez utiliser.

Conseil / Astuce

Vous pouvez répéter ces étapes pour autant d’identités que vous le souhaitez. En règle générale, ces étapes sont au moins répétées pour permettre aux développeurs d’accéder à un compte à l’aide de leur identité humaine et d’autoriser les applications à accéder aux données à l’aide d’une identité managée.

Répertoriez toutes les définitions de rôle associées à votre compte Azure Cosmos DB à l’aide az role definition listde .
```
az role definition list \
    --name "Cosmos DB Operator"
```

[
  {
    "assignableScopes": [
      "/"
    ],
    "description": "Lets you manage Azure Cosmos DB accounts, but not access data in them. Prevents access to account keys and connection strings.",
    "id": "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/providers/Microsoft.Authorization/roleDefinitions/230815da-be43-4aae-9cb4-875f7bd000aa",
    "name": "230815da-be43-4aae-9cb4-875f7bd000aa",
    "permissions": [
      {
        "actions": [
          "Microsoft.DocumentDb/databaseAccounts/*",
          "Microsoft.Insights/alertRules/*",
          "Microsoft.Authorization/*/read",
          "Microsoft.ResourceHealth/availabilityStatuses/read",
          "Microsoft.Resources/deployments/*",
          "Microsoft.Resources/subscriptions/resourceGroups/read",
          "Microsoft.Support/*",
          "Microsoft.Network/virtualNetworks/subnets/joinViaServiceEndpoint/action"
        ],
        "condition": null,
        "conditionVersion": null,
        "dataActions": [],
        "notActions": [
          "Microsoft.DocumentDB/databaseAccounts/dataTransferJobs/*",
          "Microsoft.DocumentDB/databaseAccounts/readonlyKeys/*",
          "Microsoft.DocumentDB/databaseAccounts/regenerateKey/*",
          "Microsoft.DocumentDB/databaseAccounts/listKeys/*",
          "Microsoft.DocumentDB/databaseAccounts/listConnectionStrings/*",
          "Microsoft.DocumentDB/databaseAccounts/sqlRoleDefinitions/write",
          "Microsoft.DocumentDB/databaseAccounts/sqlRoleDefinitions/delete",
          "Microsoft.DocumentDB/databaseAccounts/sqlRoleAssignments/write",
          "Microsoft.DocumentDB/databaseAccounts/sqlRoleAssignments/delete",
          "Microsoft.DocumentDB/databaseAccounts/mongodbRoleDefinitions/write",
          "Microsoft.DocumentDB/databaseAccounts/mongodbRoleDefinitions/delete",
          "Microsoft.DocumentDB/databaseAccounts/mongodbUserDefinitions/write",
          "Microsoft.DocumentDB/databaseAccounts/mongodbUserDefinitions/delete"
        ],
        "notDataActions": []
      }
    ],
    "roleName": "Cosmos DB Operator",
    "roleType": "BuiltInRole",
    "type": "Microsoft.Authorization/roleDefinitions",
  }
]

Note

Créez un fichier Bicep pour définir votre définition de rôle. Nommez le fichier control-plane-role-definition.bicep. Ajoutez-les actions à la définition :

	Descriptif
*`Microsoft.DocumentDb/`**	Active toutes les actions possibles.

metadata description = 'Create RBAC definition for control plane access to Azure Cosmos DB.'

@description('Name of the role definition.')
param roleDefinitionName string = 'Azure Cosmos DB Control Plane Owner'

@description('Description of the role definition.')
param roleDefinitionDescription string = 'Can perform all control plane actions for an Azure Cosmos DB account.'

resource definition 'Microsoft.Authorization/roleDefinitions@2022-04-01' = {
  name: guid(subscription().id, resourceGroup().id, roleDefinitionName)
  scope: resourceGroup()
  properties: {
    roleName: roleDefinitionName
    description: roleDefinitionDescription
    type: 'CustomRole'
    permissions: [
      {
        actions: [
          'Microsoft.DocumentDb/*'
        ]
      }
    ]
    assignableScopes: [
      resourceGroup().id
    ]
  }
}

output definitionId string = definition.id

Déployez le modèle Bicep à l’aide de az deployment group create. Spécifiez le nom du modèle Bicep et du groupe de ressources Azure.

az deployment group create \
    --resource-group "<name-of-existing-resource-group>" \
    --template-file control-plane-role-definition.bicep

Passez en revue la sortie du déploiement. La sortie contient l’identificateur unique de la définition de rôle dans la properties.outputs.definitionId.value propriété. Enregistrez cette valeur, car il est nécessaire d’utiliser dans l’étape d’affectation plus loin dans ce guide.
```
{
  "properties": {
    "outputs": {
      "definitionId": {
        "type": "String",
        "value": "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/msdocs-identity-example/providers/Microsoft.Authorization/roleDefinitions/a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1"
      }
    }
  }
}
```
Note

Dans cet exemple, la id valeur serait /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/msdocs-identity-example/providers/Microsoft.Authorization/roleDefinitions/a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1. Cet exemple utilise des données fictives et votre identificateur serait distinct de cet exemple. Cet exemple est un sous-ensemble de la sortie JSON typique générée par le déploiement pour plus de clarté.

Créez un fichier Bicep pour définir votre attribution de rôle. Nommez le fichier control-plane-role-assignment.bicep.

metadata description = 'Assign RBAC role for control plane access to Azure Cosmos DB.'

@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 assignment 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
  name: guid(subscription().id, resourceGroup().id, roleDefinitionId, identityId)
  scope: resourceGroup()
  properties: {
    roleDefinitionId: roleDefinitionId
    principalId: identityId
  }
}

Créez un nouveau fichier de paramètres Bicep nommé control-plane-role-assignment.bicepparam. Dans ce fichier de paramètres ; affectez les identificateurs de définition de rôle précédemment enregistrés au roleDefinitionId paramètre et l’identificateur unique de votre identité au identityId paramètre.
```
using './control-plane-role-assignment.bicep'

param roleDefinitionId = '<id-of-new-role-definition>'
param identityId = '<id-of-existing-identity>'
```

Déployez ce modèle Bicep à l’aide de az deployment group create.

az deployment group create \
    --resource-group "<name-of-existing-resource-group>" \
    --parameters control-plane-role-assignment.bicepparam \
    --template-file control-plane-role-assignment.bicep

Répétez ces étapes pour accorder l’accès au compte à partir des autres identités que vous souhaitez utiliser.

Conseil / Astuce

Vous pouvez répéter ces étapes pour autant d’identités que vous le souhaitez. En règle générale, ces étapes sont au moins répétées pour permettre aux développeurs d’accéder à un compte à l’aide de leur identité humaine et d’autoriser les applications à accéder aux données à l’aide d’une identité managée.

Connectez-vous au portail Azure (https://portal.azure.com).
Entrez le groupe de ressources dans la barre de recherche globale.
Dans Services, sélectionnez Groupes de ressources.
Dans le volet Groupes de ressources, sélectionnez votre groupe de ressources existant.

Note

Cet exemple de capture d’écran inclut le msdocs-identity-example groupe de ressources. Le nom de votre groupe de ressources réel peut être différent.
Dans le volet du groupe de ressources, sélectionnez Contrôle d’accès (IAM) dans le menu du service.
Dans le volet Contrôle d’accès (IAM), sélectionnez Rôles.
Dans la section Rôles , utilisez l’expression de recherche Cosmos DB et recherchez la définition du rôle Opérateur Cosmos DB . Sélectionnez ensuite l’option Affichage associée à cette définition.
Dans la boîte de dialogue Définition de rôle opérateur Cosmos DB , observez les actions affectées dans le cadre de cette définition de rôle.
Fermez la boîte de dialogue Définition du rôle d'opérateur Cosmos DB.
Dans le volet Contrôle d’accès (IAM), sélectionnez Ajouter. Sélectionnez Ensuite Ajouter un rôle personnalisé.

Dans le volet Informations de base , configurez les options suivantes, puis sélectionnez Suivant :

	Valeur
Nom du rôle personnalisé	`Azure Cosmos DB Control Plane Owner`
Description	`Can perform all control plane actions for an Azure Cosmos DB account.`
Autorisations de référence	Commencer à partir de zéro

Capture d’écran du volet « De base » pour l’ajout d’un rôle personnalisé.

Dans le volet Autorisations , sélectionnez Ajouter des autorisations. Ensuite, recherchez DocumentDB dans la boîte de dialogue autorisations. Enfin, sélectionnez l’option Microsoft.DocumentDB .
Dans la boîte de dialogue Autorisations, sélectionnez toutes les actions pour Microsoft.DocumentDB. Ensuite, sélectionnez Ajouter pour revenir au volet *Autorisations .
De retour dans le volet Autorisations , observez la liste des autorisations. Ensuite, sélectionnez Vérifier + créer.
Dans le volet Vérifier + créer , passez en revue les options spécifiées pour la nouvelle définition de rôle. Enfin, sélectionnez Créer.
Attendez que le portail termine la création de la définition de rôle.
Dans le volet Contrôle d’accès (IAM), sélectionnez Ajouter , puis Ajouter une attribution de rôle.
Dans le volet Rôle , recherchez Azure Cosmos DB et sélectionnez le rôle Propriétaire du plan de contrôle Azure Cosmos DB créé précédemment dans ce guide. Ensuite, sélectionnez Suivant.

Conseil / Astuce

Vous pouvez éventuellement filtrer la liste des rôles pour inclure uniquement des rôles personnalisés.
Dans le volet Membres , sélectionnez l’option Sélectionner des membres . Dans la boîte de dialogue membres, sélectionnez l’identité que vous souhaitez accorder à ce niveau d’accès pour votre compte Azure Cosmos DB, puis utilisez l’option Sélectionner pour confirmer votre choix.

Note

Cette capture d’écran illustre un exemple d’utilisateur nommé « Kai Carter » avec un principal de kai@adventure-works.com.
De retour dans le volet Membres , passez en revue le membre sélectionné[s], puis sélectionnez Vérifier + affecter.
Dans le volet Révision + affectation , passez en revue les options spécifiées pour la nouvelle attribution de rôle. Enfin, sélectionnez Vérifier + affecter.
Attendez que le portail termine la création de l’attribution de rôle.

Permet Get-AzRoleDefinition de répertorier toutes les définitions de rôle associées à votre compte Azure Cosmos DB.
```
$parameters = @{
    Name = "Cosmos DB Operator"
}
Get-AzRoleDefinition @parameters
```

Passez en revue la sortie et recherchez la définition de rôle nommée Contributeur de données intégré Cosmos DB. La sortie contient l’identificateur unique de la définition de rôle dans la Id propriété. Enregistrez cette valeur, car il est nécessaire d’utiliser dans l’étape d’affectation plus loin dans ce guide.

Name             : Cosmos DB Operator
Id               : 230815da-be43-4aae-9cb4-875f7bd000aa
IsCustom         : False
Description      : Lets you manage Azure Cosmos DB accounts, but not access data in them. Prevents access to account keys and connection strings.
Actions          : {Microsoft.DocumentDb/databaseAccounts/*, Microsoft.Insights/alertRules/*, Microsoft.Authorization/*/read, Microsoft.ResourceHealth/availabilityStatuses/read…}
NotActions       : {Microsoft.DocumentDB/databaseAccounts/dataTransferJobs/*, Microsoft.DocumentDB/databaseAccounts/readonlyKeys/*, Microsoft.DocumentDB/databaseAccounts/regenerateKey/*, Microsoft.DocumentDB/databaseAccounts/listKeys/*…}
DataActions      : {}
NotDataActions   : {}
AssignableScopes : {/}

Note

Dans cet exemple, la Id valeur serait 230815da-be43-4aae-9cb4-875f7bd000aa. L’identificateur est globalement unique dans toutes les définitions de rôle dans Azure.

Permet Get-AzResourceGroup d’obtenir les métadonnées de votre groupe de ressources actuel.

$parameters = @{
    Name = "<name-of-existing-resource-group>"
}
Get-AzResourceGroup @parameters

Observez la sortie de la commande précédente. Enregistrez la valeur de la propriété ResourceId pour ce groupe de ressources, car elle est nécessaire pour l'utiliser à l'étape suivante.
```
ResourceGroupName : msdocs-identity-example
Location          : westus
ProvisioningState : Succeeded
ResourceId        : /subscriptions/a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1/resourcegroups/msdocs-identity-example
```
Note

Dans cet exemple, la ResourceId valeur serait /subscriptions/a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1/resourcegroups/msdocs-identity-example. Cet exemple utilise des données fictives et votre identificateur serait distinct de cet exemple. Cette chaîne est un exemple tronqué de la sortie classique.
Tout d’abord, importez le Az.Resources module. Ensuite, créez un Microsoft.Azure.Commands.Resources.Models.Authorization.PSRoleDefinition objet. Dans l’objet, créez cette définition de ressource en spécifiant les valeurs répertoriées ici. Dans la liste AssignableScopes, ajoutez la propriété ResourceId du groupe de ressources notée à l’étape précédente. Enfin, utilisez l’objet de définition de rôle comme entrée pour le -Role paramètre de New-AzRoleDefinition.
```
Import-Module Az.Resources

$parameters = @{
    TypeName = "Microsoft.Azure.Commands.Resources.Models.Authorization.PSRoleDefinition"
    Property = @{
        Name = "Azure Cosmos DB Control Plane Owner"
        Description = "Can perform all control plane actions for an Azure Cosmos DB account."
        IsCustom = $true
        Actions = @(
            "Microsoft.DocumentDb/*"
        )
        AssignableScopes = @(
            "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/msdocs-identity-example"
        )
    }
}
$role = New-Object @parameters

New-AzRoleDefinition -Role $role
```
Note

Cet exemple utilise la /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/msdocs-identity-example valeur enregistrée à l’étape précédente. Votre identificateur de ressource réel peut être différent.
Passez en revue la sortie de la commande de création de définition. La sortie contient l’identificateur unique de la définition de rôle dans la Name propriété. Enregistrez cette valeur, car il est nécessaire d’utiliser dans l’étape d’affectation plus loin dans ce guide.
```
Name             : Azure Cosmos DB Control Plane Owner
Id               : e4e4e4e4-ffff-aaaa-bbbb-c5c5c5c5c5c5
IsCustom         : True
Description      : Can perform all control plane actions for an Azure Cosmos DB account.
Actions          : {Microsoft.DocumentDb/*}
AssignableScopes : {/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/msdocs-identity-example}
```
Note

Dans cet exemple, la Name valeur serait Azure Cosmos DB Control Plane Owner. Cet exemple est un sous-ensemble du résultat typique du déploiement pour plus de clarté.

Attribuez le nouveau rôle à l'aide de New-AzRoleAssignment. Utilisez le nom du rôle pour le RoleDefinitionName paramètre et l’identificateur unique de votre identité au ObjectId paramètre.

$parameters = @{
    ResourceGroupName = "<name-of-existing-resource-group>"
    ObjectId = "<your-principal-identifier>"
    RoleDefinitionName = "Azure Cosmos DB Control Plane Owner"
}
New-AzRoleAssignment @parameters

Observez la sortie de la commande. La sortie inclut un identificateur unique pour l’affectation dans la propriété RoleAssignmentId.

RoleAssignmentName : ffffffff-5555-6666-7777-aaaaaaaaaaaa
RoleAssignmentId   : /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/msdocs-identity-example/providers/Microsoft.Authorization/roleAssignments/a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1
Scope              : /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/msdocs-identity-example
DisplayName        : Kai Carter
SignInName         : <kai@adventure-works.com>
RoleDefinitionName : Azure Cosmos DB Control Plane Owner
RoleDefinitionId   : e4e4e4e4-ffff-aaaa-bbbb-c5c5c5c5c5c5

Note

Dans cet exemple, la RoleAssignmentId propriété est /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/msdocs-identity-example/providers/Microsoft.Authorization/roleAssignments/a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1, qui est un autre exemple fictif. Cet exemple est un sous-ensemble du résultat typique du déploiement pour plus de clarté.

Répétez ces étapes pour accorder l’accès au compte à partir des autres identités que vous souhaitez utiliser.

Conseil / Astuce

Vous pouvez répéter ces étapes pour autant d’identités que vous le souhaitez. En règle générale, ces étapes sont au moins répétées pour permettre aux développeurs d’accéder à un compte à l’aide de leur identité humaine et d’autoriser les applications à accéder aux données à l’aide d’une identité managée.

Important

L’attribution d’une définition de rôle nécessite que vous disposiez déjà de l’identificateur unique de toute identité que vous souhaitez accorder aux autorisations de contrôle d’accès en fonction du rôle.

Valider le contrôle d'accès basé sur les rôles du plan de contrôle dans le code

Vérifiez que vous avez correctement accordé l’accès à l’aide du code d’application et du Kit de développement logiciel (SDK) de gestion Azure.

using Azure.Identity;
using Azure.ResourceManager;

DefaultAzureCredential credential = new();

ArmClient client = new(credential);

const { CosmosDBManagementClient } = require('@azure/arm-cosmosdb');
const { DefaultAzureCredential } = require('@azure/identity');

const subscriptionId = "<subscription-id>";

const credential = new DefaultAzureCredential();

const client = new CosmosDBManagementClient(credential, subscriptionId);

import { CosmosDBManagementClient } from '@azure/arm-cosmosdb';
import { TokenCredential, DefaultAzureCredential } from '@azure/identity';

let subscriptionId: string = "<subscription-id>";

let credential: TokenCredential = new DefaultAzureCredential();

const client: CosmosDBManagementClient = new CosmosDBManagementClient(credential, subscriptionId);

from azure.mgmt.cosmosdb import CosmosDBManagementClient
from azure.identity import DefaultAzureCredential

subscription_id = "<subscription-id>"

credential = DefaultAzureCredential()

client = CosmosDBManagementClient(credential=credential, subscription=subscription_id)

package main

import (
    "github.com/Azure/azure-sdk-for-go/sdk/azidentity"
    "github.com/Azure/azure-sdk-for-go/sdk/resourcemanager/cosmos/armcosmos"
)

const subscriptionId = "<subscription-id>"

func main() {
    credential, _ := azidentity.NewDefaultAzureCredential(nil)
    
    client, _ := armcosmos.NewDatabaseClient(subscriptionId, credential, nil)
}

package com.example;

import com.azure.core.management.profile.AzureProfile;
import com.azure.core.management.AzureEnvironment;
import com.azure.identity.DefaultAzureCredential;
import com.azure.identity.DefaultAzureCredentialBuilder;
import com.azure.resourcemanager.cosmos.CosmosManager;

public class CosmosDB {
    public static void main(String[] args) {
        AzureProfile profile = new AzureProfile(AzureEnvironment.AZURE);
        DefaultAzureCredential credential = new DefaultAzureCredentialBuilder()
          .build();

        CosmosManager manager = CosmosManager.authenticate(credential, profile);
    }
}

Accorder un accès en fonction du rôle au plan de données

L’accès au plan de données fait référence à la possibilité de lire et d’écrire des données au sein d’un service Azure sans pouvoir gérer les ressources dans le compte. Par exemple, l’accès au plan de données Azure Cosmos DB peut inclure la possibilité de :

Lire certaines métadonnées de compte et de ressource
Créer, lire, mettre à jour, corriger et supprimer des éléments
Exécuter des requêtes NoSQL
Lecture à partir du flux de modification d’un conteneur
Exécuter des procédures stockées
Gérer les conflits dans le flux des conflits

Tout d’abord, vous devez préparer une définition de rôle avec une liste d’autorisations d’accès dataActions à la lecture, à la requête et à la gestion des données dans Azure Cosmos DB pour NoSQL. Dans ce guide, vous préparez un rôle personnalisé. Ensuite, affectez le rôle nouvellement défini à une identité afin que vos applications puissent accéder aux données dans Azure Cosmos DB pour NoSQL.

Important

L’obtention d’une définition de rôle de plan de données existante nécessite ces autorisations de plan de contrôle :

Microsoft.DocumentDB/databaseAccounts/sqlRoleDefinitions/read

La création d’une définition de rôle de plan de données nécessite les autorisations de plan de contrôle suivantes :

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

La création d’une attribution de rôle de plan de données nécessite les autorisations de plan de contrôle suivantes :

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

Avertissement

Le contrôle d’accès en fonction du rôle natif d’Azure Cosmos DB for NoSQL ne prend pas en charge la propriété notDataActions. Toute action qui n’est pas spécifiée en tant qu’autorisation dataAction est exclue automatiquement.

Répertoriez toutes les définitions de rôle associées à votre compte Azure Cosmos DB pour NoSQL à l’aide de az cosmosdb sql role definition list.

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

Créez un fichier JSON nommé role-definition.json, qui est utilisé pour la création du rôle personnalisé. Dans ce fichier, créez une définition de ressource spécifiant les actions de données répertoriées ici :

	Descriptif
`Microsoft.DocumentDB/databaseAccounts/readMetadata`	Peut lire les métadonnées au niveau du compte
*`Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/`**	Peut effectuer n’importe quelle opération de données au niveau du conteneur
*`Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/items/`**	Peut effectuer n’importe quelle opération sur des éléments avec des conteneurs

{
  "RoleName": "Azure Cosmos DB for NoSQL Data Plane Owner",
  "Type": "CustomRole",
  "AssignableScopes": [
    "/"
  ],
  "Permissions": [
    {
      "DataActions": [
        "Microsoft.DocumentDB/databaseAccounts/readMetadata",
        "Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/*",
        "Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/items/*"
      ]
    }
  ]
}

Ensuite, utilisez cette option az cosmosdb sql role definition create pour créer la définition de rôle. Utilisez le role-definition.json comme entrée pour l’argument --body .

az cosmosdb sql role definition create \
    --resource-group "<name-of-existing-resource-group>" \
    --account-name "<name-of-existing-nosql-account>" \
    --body "@role-definition.json"

Passez en revue la sortie de la commande précédente. Recherchez la définition de rôle que vous venez de créer nommée Propriétaire du plan de données NOSQL pour Azure Cosmos DB. La sortie contient l’identificateur unique de la définition de rôle dans la id propriété. Enregistrez cette valeur, car il est nécessaire d’utiliser dans l’étape d’affectation plus loin dans ce guide en tant que --role-definition-id

{
  "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/bbbbbbbb-1111-2222-3333-cccccccccccc",
  "name": "bbbbbbbb-1111-2222-3333-cccccccccccc",
  "permissions": [
    {
      "dataActions": [
        "Microsoft.DocumentDB/databaseAccounts/readMetadata",
        "Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/*",
        "Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/items/*"
      ],
      "notDataActions": []
    }
  ],
  "resourceGroup": "msdocs-identity-example",
  "roleName": "Azure Cosmos DB for NoSQL Data Plane Owner",
  "type": "Microsoft.DocumentDB/databaseAccounts/sqlRoleDefinitions",
  "typePropertiesType": "CustomRole"
}

Note

Dans cet exemple, la --role-definition-id valeur serait bbbbbbbb-1111-2222-3333-cccccccccccc. Cet exemple utilise des données fictives et votre identificateur serait distinct de cet exemple.

Utilisez l’élément id obtenu à l’étape précédente et déterminez le --scope en supprimant tout après le nom du compte.

Note

Dans cet exemple, la --scope valeur serait /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/msdocs-identity-example/providers/Microsoft.DocumentDB/databaseAccounts/msdocs-identity-example-nosql. Cet exemple utilise des données fictives et votre identificateur serait distinct de cet exemple.
Attribuez le nouveau rôle à l'aide de az cosmosdb sql role assignment create.
Utilisez les identificateurs de définition de rôle précédemment enregistrés pour l’argument --role-definition-id ,
l’identificateur unique de votre identité à l’argument --principal-id ,
et enfin, utilisez l’identificateur de votre compte pour l’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"
```
Conseil / Astuce

Si vous tentez d’accorder le contrôle d’accès en fonction du rôle du plan de données à votre propre identité, vous pouvez utiliser cette commande pour obtenir l’identité :
```
az ad signed-in-user show
```
Pour plus d’informations, consultez az ad signed-in-user.
Conseil / Astuce

Dans l’implémentation native d’Azure Cosmos DB du contrôle d’accès en fonction du rôle, l’étendue fait référence à la granularité des ressources au sein d’un compte pour lequel vous souhaitez appliquer l’autorisation. Au plus haut niveau, vous pouvez définir l’étendue d’une affectation de contrôle d’accès en fonction du rôle du plan de données sur l’ensemble du compte à l’aide de l’étendue la plus large. Cette étendue inclut toutes les bases de données et conteneurs au sein du compte :
```
/subscriptions/<subscription-id>/resourcegroups/<resource-group-name>/providers/Microsoft.DocumentDB/databaseAccounts/<account-name>/
```
Vous pouvez également étendre votre attribution de rôle de plan de données à une base de données spécifique :
```
/subscriptions/<subscription-id>/resourcegroups/<resource-group-name>/providers/Microsoft.DocumentDB/databaseAccounts/<account-name>/dbs/<database-name>
```
Enfin, vous pouvez restreindre l’affectation à un seul conteneur, ce qui constitue l'étendue la plus fine.
```
/subscriptions/<subscription-id>/resourcegroups/<resource-group-name>/providers/Microsoft.DocumentDB/databaseAccounts/<account-name>/dbs/<database-name>/colls/<container-name>
```
Dans de nombreux cas, vous pouvez utiliser l’étendue relative au lieu de l’étendue complète. Par exemple, vous pouvez utiliser cette étendue relative pour accorder des autorisations de contrôle d’accès en fonction du rôle de plan de données à une base de données et un conteneur spécifiques à partir d’une commande Azure CLI :
```
/dbs/<database-name>/colls/<container-name>
```
Vous pouvez également accorder un accès universel à toutes les bases de données et conteneurs à l’aide de l’étendue relative :
```
/
```
Permet az cosmosdb sql role assignment list de répertorier toutes les attributions de rôles pour votre compte Azure Cosmos DB pour NoSQL. Vérifiez la sortie pour vous assurer que votre assignation de rôle a été créée.
```
az cosmosdb sql role assignment list \
    --resource-group "<name-of-existing-resource-group>" \
    --account-name "<name-of-existing-nosql-account>"
```

Répertoriez toutes les définitions de rôle associées à votre compte Azure Cosmos DB pour NoSQL à l’aide de az cosmosdb sql role definition list.

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

Passez en revue la sortie et recherchez la définition de rôle nommée Contributeur de données intégré Cosmos DB. La sortie contient l’identificateur unique de la définition de rôle dans la id propriété. Enregistrez cette valeur, car il est nécessaire d’utiliser dans l’étape d’affectation plus loin dans ce guide.

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

Note

Dans cet exemple, la id valeur serait /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/msdocs-identity-example/providers/Microsoft.DocumentDB/databaseAccounts/msdocs-identity-example-nosql/sqlRoleDefinitions/00000000-0000-0000-0000-000000000002. Cet exemple utilise des données fictives et votre identificateur serait distinct de cet exemple.

Créez un fichier Bicep pour définir votre définition de rôle. Nommez le fichier data-plane-role-definition.bicep. Ajoutez-les dataActions à la définition :

	Descriptif
`Microsoft.DocumentDB/databaseAccounts/readMetadata`	Peut lire les métadonnées au niveau du compte
*`Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/`**	Peut effectuer n’importe quelle opération de données au niveau du conteneur
*`Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/items/`**	Peut effectuer n’importe quelle opération sur des éléments avec des conteneurs

metadata description = 'Create RBAC definition for data plane access to Azure Cosmos DB for NoSQL.'

@description('Name of the Azure Cosmos DB for NoSQL account.')
param accountName string

@description('Name of the role definition.')
param roleDefinitionName string = 'Azure Cosmos DB for NoSQL Data Plane Owner'

resource account 'Microsoft.DocumentDB/databaseAccounts@2024-05-15' existing = {
  name: accountName
}

resource definition 'Microsoft.DocumentDB/databaseAccounts/sqlRoleDefinitions@2024-05-15' = {
  name: guid(account.id, roleDefinitionName)
  parent: account
  properties: {
    roleName: roleDefinitionName
    type: 'CustomRole'
    assignableScopes: [
      account.id
    ]
    permissions: [
      {
        dataActions: [
          'Microsoft.DocumentDB/databaseAccounts/readMetadata'
          'Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/*'
          'Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/items/*'
        ]
      }
    ]
  }
}

output definitionId string = definition.id

Conseil / Astuce

Dans l’implémentation native d’Azure Cosmos DB du contrôle d’accès en fonction du rôle, l’étendue fait référence à la granularité des ressources au sein d’un compte pour lequel vous souhaitez appliquer l’autorisation. Au plus haut niveau, vous pouvez définir l’étendue d’une affectation de contrôle d’accès en fonction du rôle du plan de données sur l’ensemble du compte à l’aide de l’étendue la plus large. Cette étendue inclut toutes les bases de données et conteneurs au sein du compte :

/subscriptions/<subscription-id>/resourcegroups/<resource-group-name>/providers/Microsoft.DocumentDB/databaseAccounts/<account-name>/

Vous pouvez également étendre votre attribution de rôle de plan de données à une base de données spécifique :

/subscriptions/<subscription-id>/resourcegroups/<resource-group-name>/providers/Microsoft.DocumentDB/databaseAccounts/<account-name>/dbs/<database-name>

Enfin, vous pouvez restreindre l’affectation à un seul conteneur, ce qui constitue l'étendue la plus fine.

/subscriptions/<subscription-id>/resourcegroups/<resource-group-name>/providers/Microsoft.DocumentDB/databaseAccounts/<account-name>/dbs/<database-name>/colls/<container-name>

Dans de nombreux cas, vous pouvez utiliser l’étendue relative au lieu de l’étendue complète. Par exemple, vous pouvez utiliser cette étendue relative pour accorder des autorisations de contrôle d’accès en fonction du rôle de plan de données à une base de données et un conteneur spécifiques à partir d’une commande Azure CLI :

/dbs/<database-name>/colls/<container-name>

Vous pouvez également accorder un accès universel à toutes les bases de données et conteneurs à l’aide de l’étendue relative :

Créez un fichier de paramètres Bicep nommé data-plane-role-definition.bicepparam. Dans ce fichier de paramètres, attribuez le nom de votre compte Azure Cosmos DB pour NoSQL existant au accountName paramètre.
```
using './data-plane-role-definition.bicep'

param accountName = '<name-of-existing-nosql-account>'
```

Déployez le modèle Bicep à l’aide de az deployment group create.

az deployment group create \
    --resource-group "<name-of-existing-resource-group>" \
    --parameters data-plane-role-definition.bicepparam \
    --template-file data-plane-role-definition.bicep

Créez un fichier Bicep pour définir votre attribution de rôle. Nommez le fichier 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 = deployer().objectId

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

Créez un nouveau fichier de paramètres Bicep nommé data-plane-role-assignment.bicepparam. Dans ce fichier de paramètres, attribuez le nom de votre compte Azure Cosmos DB pour NoSQL existant au accountName paramètre, les identificateurs de définition de rôle précédemment enregistrés au roleDefinitionId paramètre et l’identificateur unique de votre identité au identityId paramètre.
```
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>'
```
Conseil / Astuce

Si vous tentez d’accorder le contrôle d’accès en fonction du rôle du plan de données à votre propre identité, vous pouvez omettre le identityId paramètre. Le modèle Bicep utilise deployer().objectId ensuite pour obtenir l’identité du principal qui a déployé le modèle. Pour plus d’informations, consultez deployer.

Déployez le modèle Bicep à l’aide de 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

Répétez ces étapes pour accorder l’accès au compte à partir des autres identités que vous souhaitez utiliser.

Conseil / Astuce

Vous pouvez répéter ces étapes pour autant d’identités que vous le souhaitez. En règle générale, ces étapes sont au moins répétées pour permettre aux développeurs d’accéder à un compte à l’aide de leur identité humaine. Vous pouvez également répéter ces étapes pour permettre aux applications d’accéder aux ressources à l’aide d’une identité managée.

Permet Get-AzCosmosDBSqlRoleDefinition de répertorier toutes les définitions de rôle associées à votre compte Azure Cosmos DB pour NoSQL.

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

Passez en revue la sortie et recherchez la définition de rôle nommée Contributeur de données intégré Cosmos DB. La sortie contient l’identificateur unique de la définition de rôle dans la Id propriété. Enregistrez cette valeur, car il est nécessaire d’utiliser dans l’étape d’affectation plus loin dans ce guide.
```
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 : 
```
Note

Dans cet exemple, la Id valeur serait /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/msdocs-identity-example/providers/Microsoft.DocumentDB/databaseAccounts/msdocs-identity-example-nosql/sqlRoleDefinitions/00000000-0000-0000-0000-000000000002. Cet exemple utilise des données fictives et votre identificateur serait distinct de cet exemple. Toutefois, l’identificateur (00000000-0000-0000-0000-000000000002) est unique dans toutes les définitions de rôle de votre compte.

Créez une nouvelle définition de rôle à l’aide de New-AzCosmosDBSqlRoleDefinition. Pour le DataAction paramètre, spécifiez les actions de données répertoriées ici :

	Descriptif
`Microsoft.DocumentDB/databaseAccounts/readMetadata`	Peut lire les métadonnées au niveau du compte
*`Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/`**	Peut effectuer n’importe quelle opération de données au niveau du conteneur
*`Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/items/`**	Peut effectuer n’importe quelle opération sur des éléments avec des conteneurs

$parameters = @{
    ResourceGroupName = "<name-of-existing-resource-group>"
    AccountName = "<name-of-existing-nosql-account>"
    RoleName = "Azure Cosmos DB for NoSQL Data Plane Owner"
    Type = "CustomRole"
    AssignableScope = @(
        "/"
    )
    DataAction = @(
        "Microsoft.DocumentDB/databaseAccounts/readMetadata",
        "Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/*",
        "Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/items/*"
    )
}
New-AzCosmosDBSqlRoleDefinition @parameters

Conseil / Astuce

/subscriptions/<subscription-id>/resourcegroups/<resource-group-name>/providers/Microsoft.DocumentDB/databaseAccounts/<account-name>/

Vous pouvez également étendre votre attribution de rôle de plan de données à une base de données spécifique :

/subscriptions/<subscription-id>/resourcegroups/<resource-group-name>/providers/Microsoft.DocumentDB/databaseAccounts/<account-name>/dbs/<database-name>

Enfin, vous pouvez restreindre l’affectation à un seul conteneur, ce qui constitue l'étendue la plus fine.

/subscriptions/<subscription-id>/resourcegroups/<resource-group-name>/providers/Microsoft.DocumentDB/databaseAccounts/<account-name>/dbs/<database-name>/colls/<container-name>

/dbs/<database-name>/colls/<container-name>

Vous pouvez également accorder un accès universel à toutes les bases de données et conteneurs à l’aide de l’étendue relative :

Permet Get-AzCosmosDBSqlRoleDefinition de répertorier toutes les définitions de rôle associées à votre compte Azure Cosmos DB pour NoSQL.

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

Passez en revue la sortie de la commande précédente. Recherchez la définition de rôle que vous venez de créer nommée Propriétaire du plan de données NOSQL pour Azure Cosmos DB. La sortie contient l’identificateur unique de la définition de rôle dans la Id propriété. Enregistrez cette valeur, car il est nécessaire d’utiliser dans l’étape d’affectation plus loin dans ce guide.

Id                         : /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/msdocs-identity-example/providers/Microsoft.DocumentDB/databaseAccounts/msdocs-identity-example-nosql/sqlRoleDefinitions/bbbbbbbb-1111-2222-3333-cccccccccccc
RoleName                   : Azure Cosmos DB for NoSQL Data Plane Owner
Type                       : CustomRole
AssignableScopes           : {/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/msdocs-identity-example/providers/Microsoft.DocumentDB/databaseAccounts/msdocs-identity-example-nosql}
Permissions.DataActions    : {Microsoft.DocumentDB/databaseAccounts/readMetadata, Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/items/*, Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/*}
Permissions.NotDataActions :

Note

Dans cet exemple, la Id valeur serait /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/msdocs-identity-example/providers/Microsoft.DocumentDB/databaseAccounts/msdocs-identity-example-nosql/sqlRoleDefinitions/bbbbbbbb-1111-2222-3333-cccccccccccc. Cet exemple utilise des données fictives et votre identificateur serait distinct de cet exemple.

Permet Get-AzCosmosDBAccount d’obtenir les métadonnées de votre compte actuel.

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

Observez la sortie de la commande précédente. Enregistrez la valeur de la Id propriété pour ce compte, car elle doit être utilisée à l’étape suivante.
```
Id
--    
/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/msdocs-identity-example/providers/Microsoft.DocumentDB/databaseAccounts/msdocs-identity-example-nosql
```
Note

Dans cet exemple, la Id valeur serait /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/msdocs-identity-example/providers/Microsoft.DocumentDB/databaseAccounts/msdocs-identity-example-nosql. Cet exemple utilise des données fictives et votre identificateur serait distinct de cet exemple.
Utilisez New-AzCosmosDBSqlRoleAssignment pour attribuer le nouveau rôle. Utilisez les identificateurs de définition de rôle précédemment enregistrés dans le RoleDefinitionId paramètre et l’identificateur unique de votre identité au PrincipalId paramètre. Enfin, utilisez l’identificateur de votre compte pour le Scope paramètre.
```
$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
```
Conseil / Astuce

Si vous tentez d’accorder le contrôle d’accès en fonction du rôle du plan de données à votre propre identité, vous pouvez utiliser cette commande pour obtenir l’identité :
```
Get-AzADUser -SignedIn | Format-List `
    -Property Id, DisplayName, Mail, UserPrincipalName
```
Pour plus d’informations, consultez Get-AzADUser.
Répertoriez toutes les attributions de rôles pour votre compte Azure Cosmos DB pour NoSQL à l’aide de Get-AzCosmosDBSqlRoleAssignment. Vérifiez la sortie pour vous assurer que votre assignation de rôle a été créée.
```
$parameters = @{
    ResourceGroupName = "<name-of-existing-resource-group>"
    AccountName = "<name-of-existing-nosql-account>"
}
Get-AzCosmosDBSqlRoleAssignment @parameters
```

Avertissement

La gestion du contrôle d’accès en fonction du rôle du plan de données n’est pas prise en charge dans le portail Azure.

Valider l'accès basé sur les rôles dans le plan de données dans le code

Vérifiez que vous avez correctement accordé l’accès à l’aide du code d’application et du Kit de développement logiciel (SDK) Azure.

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

string endpoint = "<account-endpoint>";

TokenCredential credential = new DefaultAzureCredential();

CosmosClient client = new(endpoint, credential);

Container container = client.GetContainer("<database-name>", "<container-name>");

await container.ReadItemAsync<dynamic>("<item-id>", new PartitionKey("<partition-key>"));

const { CosmosClient } = require('@azure/cosmos');
const { DefaultAzureCredential } = require('@azure/identity');

const endpoint = '<account-endpoint>';

const credential = new DefaultAzureCredential();

const client = new CosmosClient({ endpoint, aadCredentials:credential});

const container = client.database('<database-name>').container('<container-name>');

await container.item('<item-id>', '<partition-key>').read<String>();

import { Container, CosmosClient, CosmosClientOptions } from '@azure/cosmos'
import { TokenCredential, DefaultAzureCredential } from '@azure/identity'

let endpoint: string = '<account-endpoint>';

let credential: TokenCredential = new DefaultAzureCredential();

let options: CosmosClientOptions = {
  endpoint: endpoint,
  aadCredentials: credential
};

const client: CosmosClient = new CosmosClient(options);

const container: Container = client.database('<database-name>').container('<container-name>');

await container.item('<item-id>', '<partition-key>').read<String>();

from azure.cosmos import CosmosClient
from azure.identity import DefaultAzureCredential

endpoint = "<account-endpoint>"

credential = DefaultAzureCredential()

client = CosmosClient(endpoint, credential=credential)

container = client.get_database_client("<database-name>").get_container_client("<container-name>")

container.read_item(
    item="<item-id>",
    partition_key="<partition-key>",
)

import (
    "context"
    
    "github.com/Azure/azure-sdk-for-go/sdk/azidentity"
    "github.com/Azure/azure-sdk-for-go/sdk/data/azcosmos"
)

const endpoint = "<account-endpoint>"

func main() {
    credential, _ := azidentity.NewDefaultAzureCredential(nil)
    client, _ := azcosmos.NewClient(endpoint, credential, nil)
    
    database, _ := client.NewDatabase("<database-name>")
    container, _ := database.NewContainer("<container-name>")
    
    _, err := container.ReadItem(context.TODO(), azcosmos.NewPartitionKeyString("<partition-key>"), "<item-id>", nil)
    if err != nil {
        panic(err)
    }
}

import com.azure.cosmos.CosmosClient;
import com.azure.cosmos.CosmosClientBuilder;
import com.azure.cosmos.CosmosContainer;
import com.azure.cosmos.models.PartitionKey;
import com.azure.identity.DefaultAzureCredential;
import com.azure.identity.DefaultAzureCredentialBuilder;

public class NoSQL {
    public static void main(String[] args) {   
        DefaultAzureCredential credential = new DefaultAzureCredentialBuilder()
            .build();
            
        CosmosClient client = new CosmosClientBuilder()
            .endpoint("<account-endpoint>")
            .credential(credential)
            .buildClient();

        CosmosContainer container = client.getDatabase("<database-name>").getContainer("<container-name>");

        container.readItem("<item-id>", new PartitionKey("<partition-key>"), Object.class);
    }
}

use azure_data_cosmos::CosmosClient;
use azure_identity::DefaultAzureCredential;

fn main() {
    let credential = DefaultAzureCredential::new().unwrap();
    let client = CosmosClient::new("<account-endpoint>", credential, None).unwrap();

    let container = client.database_client("<database-name>").container_client("<container-name>");

    let response = container.read_item("<partition-key>", "<item-id>", None);
    tokio::runtime::Runtime::new().unwrap().block_on(response).unwrap();
}

Commentaires

Cette page a-t-elle été utile ?

Last updated on 2025-12-19

Partager via

Se connecter à Azure Cosmos DB pour NoSQL à l’aide du contrôle d’accès en fonction du rôle et de l’ID Microsoft Entra

Prerequisites

Désactiver l’authentification basée sur des clés

Vérifier que l’authentification basée sur des clés est désactivée

Accorder un accès en fonction du rôle au plan de contrôle

Valider le contrôle d'accès basé sur les rôles du plan de contrôle dans le code

Accorder un accès en fonction du rôle au plan de données

Valider l'accès basé sur les rôles dans le plan de données dans le code

Contenu connexe

Commentaires

Ressources supplémentaires