Utiliser le contrôle d’accès en fonction du rôle de plan de données avec Azure Cosmos DB for NoSQL
S’APPLIQUE À : 
NoSQL
Diagramme de la séquence du guide de déploiement, y compris ces emplacements, dans l’ordre : Vue d’ensemble, Concepts, Préparation, Contrôle d’accès en fonction du rôle, Réseau et Référence. L’emplacement « Contrôle d’accès en fonction du rôle » est actuellement mis en surbrillance.
Conseil
Pour obtenir les derniers exemples de création de nouvelles applications, visitez notre nouvelle Galerie d’exemples
Cet article décrit les étapes d’octroi d’un accès d’identité pour gérer les données dans un compte Azure Cosmos DB for NoSQL.
Important
Les étapes décrites dans cet article couvrent uniquement l’accès au plan de données pour effectuer des opérations sur des éléments individuels et exécuter des requêtes. Pour savoir comment gérer des rôles, des définitions et des affectations pour le plan de contrôle, consultez accorder l’accès en fonction du rôle du plan de contrôle.
Prérequis
- Compte Azure avec un abonnement actif. Créez un compte gratuitement.
- Un compte Azure Cosmos DB for NoSQL déjà créé :
- Une ou plusieurs identités existantes dans Microsoft Entra ID.
Utilisez l’environnement Bash dans Azure Cloud Shell. Pour plus d’informations, consultez Démarrage rapide pour Bash dans Azure Cloud Shell.
Si vous préférez exécuter les commandes de référence de l’interface de ligne de commande localement, installez l’interface 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 Guide pratique pour 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 finir le processus d’authentification, suivez les étapes affichées dans votre terminal. Pour connaître les autres options de connexion, consultez Se connecter avec 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 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.
Préparer la définition de rôle
Tout d’abord, vous devez préparer une définition de rôle avec une liste de dataActions pour accorder l’accès à la lecture, à la requête et à la gestion des données dans Azure Cosmos DB for NoSQL.
Important
L’obtention d’une définition de rôle existante pour le plan de données nécessite ces autorisations pour le plan de contrôle :
Microsoft.DocumentDB/databaseAccounts/sqlRoleDefinitions/read
Pour plus d’informations, consultez Accorder un accès en fonction du rôle dans le plan de contrôle.
Répertoriez toutes les définitions de rôle associées à votre compte Azure Cosmos DB for NoSQL à l’aide de az cosmosdb sql role definition list. 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 propriété id. Enregistrez cette valeur, car vous devrez l’utiliser dans l’étape d’affectation plus loin dans ce guide.
az cosmosdb sql role definition list \
--resource-group "<name-of-existing-resource-group>" \
--account-name "<name-of-existing-nosql-account>"
[
...,
{
"assignableScopes": [
"/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/msdocs-identity-example/providers/Microsoft.DocumentDB/databaseAccounts/msdocs-identity-example-nosql"
],
"id": "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/msdocs-identity-example/providers/Microsoft.DocumentDB/databaseAccounts/msdocs-identity-example-nosql/sqlRoleDefinitions/00000000-0000-0000-0000-000000000002",
"name": "00000000-0000-0000-0000-000000000002",
"permissions": [
{
"dataActions": [
"Microsoft.DocumentDB/databaseAccounts/readMetadata",
"Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/*",
"Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/items/*"
],
"notDataActions": []
}
],
"resourceGroup": "msdocs-identity-example",
"roleName": "Cosmos DB Built-in Data Contributor",
"type": "Microsoft.DocumentDB/databaseAccounts/sqlRoleDefinitions",
"typePropertiesType": "BuiltInRole"
}
...
]
Remarque
Pour cet exemple, la valeur id 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 sera distinct de cet exemple.
Utilisez Get-AzCosmosDBSqlRoleDefinition pour répertorier toutes les définitions de rôle associées à votre compte Azure Cosmos DB for NoSQL. 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 propriété Id. Enregistrez cette valeur, car vous devrez l’utiliser dans l’étape d’affectation plus loin dans ce guide.
$parameters = @{
ResourceGroupName = "<name-of-existing-resource-group>"
AccountName = "<name-of-existing-nosql-account>"
}
Get-AzCosmosDBSqlRoleDefinition @parameters
Id : /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/msdocs-identity-example/providers/Microsoft.DocumentDB/databaseAccounts/msdocs-identity-example-nosql/sqlRoleDefinitions/00000000-0000-0000-0000-000000000002
RoleName : Cosmos DB Built-in Data Contributor
Type : BuiltInRole
AssignableScopes : {/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/msdocs-identity-example/providers/Microsoft.DocumentDB/databaseAccountsmsdocs-identity-example-nosql}
Permissions.DataActions : {Microsoft.DocumentDB/databaseAccounts/readMetadata, Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/*, Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/items/*}
Permissions.NotDataActions :
Remarque
Pour cet exemple, la valeur Id 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 sera 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.
Attribuer un rôle à l’identité
À présent, affectez le rôle nouvellement défini à une identité afin que vos applications puissent accéder aux données dans Azure Cosmos DB for NoSQL.
Important
La création d’une nouvelle attribution de rôle au niveau du plan de données nécessite ces autorisations au niveau du plan de contrôle :
Microsoft.DocumentDB/databaseAccounts/sqlRoleDefinitions/readMicrosoft.DocumentDB/databaseAccounts/sqlRoleAssignments/readMicrosoft.DocumentDB/databaseAccounts/sqlRoleAssignments/write
Pour plus d’informations, consultez Accorder un accès en fonction du rôle dans le plan de contrôle.
Utilisez
az cosmosdb showpour obtenir l’identificateur unique de votre compte actuel.az cosmosdb show \ --resource-group "<name-of-existing-resource-group>" \ --name "<name-of-existing-nosql-account>" \ --query "{id:id}"Observez la sortie de la commande précédente. Enregistrez la valeur de la propriété
idpour ce compte, car il est nécessaire d’utiliser à l’étape suivante.{ "id": "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/msdocs-identity-example/providers/Microsoft.DocumentDB/databaseAccounts/msdocs-identity-example-nosql" }Remarque
Pour cet exemple, la valeur
idserait/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 sera 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 dans l’argument--role-definition-idet l’identificateur unique de votre identité à l’argument--principal-id. 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"Utilisez
az cosmosdb sql role assignment listpour répertorier toutes les attributions de rôles pour votre compte Azure Cosmos DB for NoSQL. Passez en revue la sortie pour vous assurer que votre attribution 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>"
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 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.idCréez un fichier de paramètres Bicep nommé data-plane-role-assignment.
bicepparam. Dans ce fichier de paramètres, affectez le nom de votre compte Azure Cosmos DB for NoSQL existant au paramètreaccountName, les identificateurs de définition de rôle précédemment enregistrés au paramètreroleDefinitionIdet l’identificateur unique de votre identité au paramètreidentityId.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>'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.bicepRépétez ces étapes pour accorder l’accès au compte à partir d’autres identités que vous souhaitez utiliser.
Conseil
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 pour accorder aux applications l’accès à l’aide d’une identité managée.
Utilisez
Get-AzCosmosDBAccountpour 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 IdObservez la sortie de la commande précédente. Enregistrez la valeur de la propriété
Idpour ce compte, car il est nécessaire d’utiliser à l’étape suivante.Id -- /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/msdocs-identity-example/providers/Microsoft.DocumentDB/databaseAccounts/msdocs-identity-example-nosqlRemarque
Pour cet exemple, la valeur
Idserait/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 sera distinct de cet exemple.Utilisez
New-AzCosmosDBSqlRoleAssignmentpour attribuer le nouveau rôle. Utilisez les identificateurs de définition de rôle précédemment enregistrés dans le paramètreRoleDefinitionIdet l’identificateur unique de votre identité au paramètrePrincipalId. Enfin, utilisez l’identificateur de votre compte pour le paramètreScope.$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 @parametersRépertoriez toutes les attributions de rôles pour votre compte Azure Cosmos DB for NoSQL à l’aide de
Get-AzCosmosDBSqlRoleAssignment. Passez en revue la sortie pour vous assurer que votre attribution de rôle a été créée.$parameters = @{ ResourceGroupName = "<name-of-existing-resource-group>" AccountName = "<name-of-existing-nosql-account>" } Get-AzCosmosDBSqlRoleAssignment @parameters
Valider l’accès au plan de données dans le code
Enfin, 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 dans votre langage de programmation préféré.
using Azure.Core;
using Azure.Identity;
using Microsoft.Azure.Cosmos;
string endpoint = "<account-endpoint>";
TokenCredential credential = new DefaultAzureCredential();
CosmosClient client = new(endpoint, credential);
Important
Cet exemple de code utilise les bibliothèques Microsoft.Azure.Cosmos et Azure.Identity de NuGet.