Configurer la clé gérée par le client (CMK) pour le chiffrement des données au repos pour un cluster Azure DocumentDB

Dans cet article, vous allez apprendre à configurer la clé gérée par le client (CMK) pour le chiffrement des données au repos dans Azure DocumentDB. Les étapes décrites dans ce guide configurent un nouveau cluster Azure DocumentDB, un cluster de réplica ou un cluster restauré. La configuration de CMK utilise une clé gérée par le client stockée dans un Azure Key Vault et une identité managée affectée par l’utilisateur.

Prerequisites

• Un abonnement Azure

  • Si vous n’avez pas d’abonnement Azure, créez un compte gratuit

• 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.

Préparer l’identité managée affectée par l’utilisateur et Azure Key Vault

Pour configurer le chiffrement de clé géré par le client sur votre cluster Azure DocumentDB pour MonogDB, vous avez besoin d’une identité managée affectée par l’utilisateur, d’une instance Azure Key Vault et d’autorisations correctement configurées.

Important

L’identité managée affectée par l’utilisateur et l’instance Azure Key Vault utilisées pour configurer CMK doivent se trouver dans la même région Azure où le cluster Azure DocumentDB est hébergé et appartient tous au même locataire Microsoft.

Utilisation du portail Azure :

1. Créez une identité managée affectée par l’utilisateur dans la région du cluster, si vous n’en avez pas encore une.

2. Créez un Azure Key Vault dans la région de cluster, si vous n’avez pas encore créé de magasin de clés. Assurez-vous que vous répondez aux exigences. Suivez également les suggestions avant de configurer le magasin de clés, puis avant de créer la clé et d’attribuer les autorisations requises à l’identité managée affectée par l’utilisateur.

3. Créez une clé dans votre magasin de clés.

4. Accordez des autorisations d’identité managée affectée par l’utilisateur à l’instance Azure Key Vault, comme indiqué dans les exigences.

Configurer le chiffrement de données avec une clé gérée par le client lors de l’approvisionnement du cluster

Portal

1. Lors de l’approvisionnement d’un nouveau cluster Azure DocumentDB, les clés gérées par le service ou gérées par le client pour le chiffrement des données de cluster sont configurées sous l’onglet Chiffrement . Sélectionnez la clé gérée par le client pour le chiffrement des données.

   

2. Dans la section Identité managée affectée par l’utilisateur, sélectionnez Modifier l’identité.

   

3. Dans la liste des identités managées affectées par l’utilisateur, sélectionnez celle que vous souhaitez que votre cluster utilise pour accéder à la clé de chiffrement des données stockée dans Azure Key Vault.

   

4. Sélectionnez Ajouter.

   

5. Dans la Méthode de sélection de clé, choisissez Sélectionner une clé.

6. Dans la section Clé , sélectionnez Modifier la clé.

   

7. Dans le volet Sélectionner une clé, sélectionnez Azure Key Vault dans le Coffre de clés et la clé de chiffrement dans la Clé. Confirmez ensuite os choix en sélectionnant Sélectionner.

   

   Important

   L’instance Azure Key Vault sélectionnée doit se trouver dans la même région Azure que celle où le cluster Azure DocumentDB sera hébergé.

8. Confirmez l’identité managée affectée par l’utilisateur sélectionnée et la clé de chiffrement sous l’onglet Chiffrement, puis sélectionnez Vérifier + créer pour créer le cluster.

   

API REST

Vous pouvez activer le chiffrement des données avec la clé de chiffrement affectée par l’utilisateur lors de l’approvisionnement d’un nouveau cluster, avec une commande az rest.

1. Créez un fichier JSON avec le contenu suivant. Remplacez les espaces réservés qui commencent par le symbole $ par les valeurs réelles, puis enregistrez le fichier.

   {
       "identity": {
           "type": "UserAssigned",
           "userAssignedIdentities": {
             "/subscriptions/$subscriptionId/resourceGroups/$resourceGroup/providers/Microsoft.ManagedIdentity/userAssignedIdentities/$userAssignedIdentityName": {}
           }
         },
     "location": "$regionName",
         "properties": {
           "administrator": {
             "userName": "$adminName",
             "password": "$complexPassword"
           },
           "serverVersion": "8.0",
           "storage": {
             "sizeGb": 32
           },
           "compute": {
             "tier": "M40"
           },
           "sharding": {
             "shardCount": 1
           },
           "highAvailability": {
             "targetMode": "ZoneRedundantPreferred"
           },
         "encryption": {
             "customerManagedKeyEncryption": {
               "keyEncryptionKeyIdentity": {
                 "identityType": "UserAssignedIdentity",
                 "userAssignedIdentityResourceId": "/subscriptions/$subscriptionId/resourceGroups/$resourceGroup/providers/Microsoft.ManagedIdentity/userAssignedIdentities/$userAssignedIdentityName"
               },
               "keyEncryptionKeyUrl": "$encryptionKeyUrl"
             }
           }
         }
   }
   

   Note

   La keyEncryptionKeyUrl doit contenir le nom de la clé, mais ne doit pas contenir une version de clé spécifique.

2. Exécutez la commande Azure CLI suivante pour effectuer un appel d’API REST pour créer un cluster Azure DocumentDB. Remplacez les espaces réservés dans la section des variables et le nom de fichier du paramètre --body dans la ligne de commande az rest par les valeurs réelles.

   # Define your variables
   $randomIdentifier = (New-Guid).ToString().Substring(0,8)
   $subscriptionId="00000000-0000-0000-0000-000000000000"
   $resourceGroup="DocumentDB"
   $mongoClustersName="msdocscr$randomIdentifier"
   
   # Execute the az rest command to make REST API call
   az rest --method "PUT" --url https://management.azure.com/subscriptions/$subscriptionId/resourceGroups/$resourceGroup/providers/Microsoft.DocumentDB/mongoClusters/${mongoClustersName}?api-version=2025-09-01 --body  @jsonFileFromThePreviousStep.json
   

Mettre à jour les paramètres de chiffrement des données du cluster avec la CMK activée

Pour les clusters existants qui ont été déployés avec le chiffrement des données à l’aide d’une clé gérée par le client, vous pouvez effectuer plusieurs modifications de configuration. Vous pouvez modifier le coffre de clés dans lequel la clé de chiffrement est stockée et la clé de chiffrement qui est utilisée comme clé gérée par le client. Vous pouvez également modifier l’identité managée affectée par l’utilisateur que le service utilise pour accéder à la clé de chiffrement conservée dans le magasin de clés.

Portal

1. Dans la barre latérale du cluster, sous Paramètres, sélectionnez Chiffrement des données.

2. Dans la section Identité managée affectée par l’utilisateur, sélectionnez Modifier l’identité.

   

3. Dans la liste des identités managées affectées par l’utilisateur, sélectionnez celle que vous souhaitez que votre cluster utilise pour accéder à la clé de chiffrement des données stockée dans Azure Key Vault.

   

4. Sélectionnez Ajouter.

5. Dans la Méthode de sélection de clé, choisissez Sélectionner une clé.

6. Dans Clé, choisissez Modifier la clé.

   

7. Dans le volet Sélectionner une clé, sélectionnez Azure Key Vault dans le Coffre de clés et la clé de chiffrement dans la Clé. Confirmez ensuite os choix en sélectionnant Sélectionner.

   

   Important

   L’instance Azure Key Vault sélectionnée doit se trouver dans la même région Azure où le cluster Azure DocumentDB est hébergé.

8. Confirmez l’identité managée affectée par l’utilisateur sélectionnée et la clé de chiffrement dans la page Chiffrement des données, puis sélectionnez Enregistrer pour confirmer vos sélections et créer un cluster de réplicas.

   

API REST

Vous pouvez modifier l’identité managée affectée par l’utilisateur et la clé de chiffrement pour le chiffrement des données sur un cluster existant via un appel API REST.

1. Créez un fichier JSON avec le contenu suivant. Remplacez les espaces réservés qui commencent par le symbole $ par les valeurs réelles, puis enregistrez le fichier.

   {
       "identity": {
           "type": "UserAssigned",
           "userAssignedIdentities": {
             "/subscriptions/$subscriptionId/resourceGroups/$resourceGroup/providers/Microsoft.ManagedIdentity/userAssignedIdentities/$userAssignedIdentityName": {}
           }
         },
     "location": "$regionName",
         "properties": {
           "encryption": {
             "customerManagedKeyEncryption": {
               "keyEncryptionKeyIdentity": {
                 "identityType": "UserAssignedIdentity",
                 "userAssignedIdentityResourceId": "/subscriptions/$subscriptionId/resourceGroups/$resourceGroup/providers/Microsoft.ManagedIdentity/userAssignedIdentities/$userAssignedIdentityName"
               },
               "keyEncryptionKeyUrl": "$encryptionKeyUrl"
             }
           }
         }
   }
   

   Note

   La keyEncryptionKeyUrl doit contenir le nom de la clé, mais ne doit pas contenir une version de clé spécifique.

2. Exécutez la commande Azure CLI suivante pour effectuer un appel d’API REST pour créer un cluster Azure DocumentDB. Remplacez les espaces réservés dans la section des variables et le nom de fichier du paramètre --body dans la ligne de commande az rest par les valeurs réelles.

   # Define your variables
   $subscriptionId="00000000-0000-0000-0000-000000000000"
   $resourceGroup="resourceGroupName"
   $mongoClustersName="clusterName"
   
   # Execute the az rest command to make REST API call
   az rest --method "PUT" --url https://management.azure.com/subscriptions/$subscriptionId/resourceGroups/$resourceGroup/providers/Microsoft.DocumentDB/mongoClusters/${mongoClustersName}?api-version=2025-09-01 --body  @jsonFileFromThePreviousStep.json
   

Que vous souhaitez uniquement modifier l’identité managée affectée par l’utilisateur utilisée pour accéder à la clé, ou que vous voulez uniquement modifier la clé utilisée pour le chiffrement des données, ou bien que vous souhaitez modifier les deux à la fois, vous devez fournir tous les paramètres listés dans le fichier JSON.

Si la clé ou l’identité managée affectée par l’utilisateur spécifiée n’existe pas, vous recevez l’erreur.

Les identités passées en tant que paramètres, s’ils existent et sont valides, sont automatiquement ajoutées à la liste des identités managées affectées par l’utilisateur associées à votre cluster Azure DocumentDB. C’est le cas même si la commande échoue ultérieurement avec une autre erreur.

Modifier le mode de chiffrement des données sur des clusters existants

Le seul moment auquel vous pouvez décider d’utiliser une clé gérée par le service ou une clé gérée par le client (CMK) pour le chiffrement des données se présente lorsque vous créez le cluster. Une fois que vous avez pris votre décision et créé le cluster, vous ne pouvez pas basculer entre les deux options. Pour créer une copie de votre cluster Azure DocumentDB avec une autre option de chiffrement, vous pouvez créer un cluster de réplicas ou effectuer une restauration de cluster et sélectionner le nouveau mode de chiffrement pendant la création du cluster de réplica ou de la création du cluster restauré.

Activer ou désactiver le chiffrement de données de clé gérée par le client (CMK) lors de la création du cluster de réplicas

Suivez ces étapes pour créer un cluster de réplicas avec le chiffrement de données par CMK ou SMK, afin d’activer ou désactiver la CMK sur un cluster de réplicas.

Portal

1. Dans la barre latérale du cluster, sous Paramètres, sélectionnez Distribution globale.

2. Sélectionnez Ajouter un nouveau réplica en lecture.

   

3. Fournissez un nom de cluster de réplicas dans le champ de noms Réplica en lecture.

4. Sélectionnez une région dans Région du réplica en lecture. Le cluster de réplicas est hébergé dans la région Azure sélectionnée.

   Note

   Le cluster de réplicas est toujours créé dans le même abonnement Azure et le même groupe de ressources que son cluster principal (en lecture-écriture).

   

5. Dans la section Chiffrement des données, sélectionnez la Clé gérée par le client pour activer la CMK ou la Clé gérée par le service pour désactiver la CMK sur le cluster de réplicas.

   

6. Dans la section Identité managée affectée par l’utilisateur, sélectionnez Modifier l’identité.

   

7. Dans la liste des identités managées affectées par l’utilisateur, sélectionnez celle que vous souhaitez que votre cluster utilise pour accéder à la clé de chiffrement des données stockée dans Azure Key Vault.

   

8. Sélectionnez Ajouter.

9. Dans la Méthode de sélection de clé, choisissez Sélectionner une clé.

10. Dans Clé, choisissez Modifier la clé.

    

11. Dans le volet Sélectionner une clé, sélectionnez Azure Key Vault dans le Coffre de clés et la clé de chiffrement dans la Clé. Confirmez ensuite os choix en sélectionnant Sélectionner.

    

12. Confirmez l’identité managée affectée par l’utilisateur et la clé de chiffrement dans la page Distribution globale, puis sélectionnez Enregistrer pour confirmer vos sélections et créer un cluster de réplicas.

    

API REST

Pour créer un cluster de réplicas avec la CMK activée dans la même région, procédez comme suit.

1. Créez un fichier JSON avec le contenu suivant. Remplacez les espaces réservés qui commencent par le symbole $ par les valeurs réelles, puis enregistrez le fichier.

   {
           "identity": {
               "type": "UserAssigned",
               "userAssignedIdentities": {
                 "/subscriptions/$subscriptionId/resourceGroups/$resourceGroup/providers/Microsoft.ManagedIdentity/userAssignedIdentities/$userAssignedIdentityName": {}
               }
             },
         "location": "$targetRegionName",
             "properties": {
             	"createMode": "GeoReplica",
                   "replicaParameters": {
                     "sourceResourceId": "/subscriptions/$subscriptionId/resourceGroups/$resourceGroup/providers/Microsoft.DocumentDB/mongoClusters/$sourceClusterName",
                     "sourceLocation": "sourceRegionName"
                   },
                   "encryption": {
                     "customerManagedKeyEncryption": {
                       "keyEncryptionKeyIdentity": {
                         "identityType": "UserAssignedIdentity",
                         "userAssignedIdentityResourceId": "/subscriptions/$subscriptionId/resourceGroups/$resourceGroup/providers/Microsoft.ManagedIdentity/userAssignedIdentities/$userAssignedIdentityName"
                       },
                       "keyEncryptionKeyUrl": "$encryptionKeyUrl"
                     }
                   }
             }
       }
   

   Note

   La keyEncryptionKeyUrl doit contenir le nom de la clé, mais ne doit pas contenir une version de clé spécifique.

2. Exécutez la commande Azure CLI suivante pour effectuer un appel d’API REST pour créer un cluster Azure DocumentDB. Remplacez les espaces réservés dans la section des variables et le nom de fichier du paramètre --body dans la ligne de commande az rest par les valeurs réelles.

   # Define your variables
   $subscriptionId="00000000-0000-0000-0000-000000000000"
   $resourceGroup="resourceGroupName"
   $mongoClustersName="clusterName"
   
   # Execute the az rest command to make REST API call
   az rest --method "PUT" --url https://management.azure.com/subscriptions/$subscriptionId/resourceGroups/$resourceGroup/providers/Microsoft.DocumentDB/mongoClusters/${mongoClustersName}?api-version=2025-09-01 --body  @jsonFileFromThePreviousStep.json
   

Activer ou désactiver le chiffrement des données de clé gérée par le client (CMK) lors de la restauration de cluster

Le processus de restauration crée un cluster avec la même configuration dans les mêmes région, abonnement et groupe de ressources Azure que le cluster d’origine. Suivez ces étapes pour créer un cluster restauré avec la CMK ou la SMK activée.

Portal

1. Sélectionnez un cluster Azure DocumentDB existant.

2. Dans la barre latérale du cluster, sous Paramètres, sélectionnez Restauration à un instant dans le passé.

3. Sélectionnez une date et indiquez une heure (dans le fuseau horaire UTC) dans les champs de date et d’heure.

   

4. Entrez un nom de cluster dans le champ Restaurer le nom du cluster cible.

   

5. Entrez un nom d’administrateur de cluster pour le cluster restauré dans le champ Nom d’utilisateur administrateur.

6. Entrez un mot de passe pour le rôle d’administrateur dans les champs Mot de passe et Confirmer le mot de passe.

   

7. Dans la section Chiffrement des données, sélectionnez la Clé gérée par le client pour activer la CMK. Si vous devez désactiver la CMK sur le cluster restauré, sélectionnez la Clé gérée par le service.

   

8. Dans la section Identité managée affectée par l’utilisateur, sélectionnez Modifier l’identité.

   

9. Dans la liste des identités managées affectées par l’utilisateur, sélectionnez celle que vous souhaitez que votre cluster utilise pour accéder à la clé de chiffrement des données stockée dans Azure Key Vault.

   

10. Sélectionnez Ajouter.

11. Dans la Méthode de sélection de clé, choisissez Sélectionner une clé.

12. Dans Clé, choisissez Modifier la clé.

    

13. Dans le volet Sélectionner une clé, sélectionnez Azure Key Vault dans le Coffre de clés et la clé de chiffrement dans la Clé. Confirmez ensuite os choix en sélectionnant Sélectionner.

    

14. Sélectionnez Envoyer pour lancer la restauration du cluster.

API REST

Pour restaurer un cluster avec la CMK activée, procédez comme suit.

1. Créez un fichier JSON avec le contenu suivant. Remplacez les espaces réservés qui commencent par le symbole $ par les valeurs réelles, puis enregistrez le fichier.

   {
       "identity": {
           "type": "UserAssigned",
           "userAssignedIdentities": {
             "/subscriptions/$subscriptionId/resourceGroups/$resourceGroup/providers/Microsoft.ManagedIdentity/userAssignedIdentities/$userAssignedIdentityName": {}
           }
         },
     "location": "$regionName",
         "properties": {
               "administrator": {
                 "userName": "$adminName"
               },
         	"createMode": "PointInTimeRestore",
               "restoreParameters": {
                 "pointInTimeUTC": "yyyy-mm-ddThh:mm:ssZ",
                 "sourceResourceId": "/subscriptions/$subscriptionId/resourceGroups/$resourceGroup/providers/Microsoft.DocumentDB/mongoClusters/$restoredClusterName"
               },
               "encryption": {
                 "customerManagedKeyEncryption": {
                   "keyEncryptionKeyIdentity": {
                     "identityType": "UserAssignedIdentity",
                     "userAssignedIdentityResourceId": "/subscriptions/$subscriptionId/resourceGroups/$resourceGroup/providers/Microsoft.ManagedIdentity/userAssignedIdentities/$userAssignedIdentityName"
                   },
                   "keyEncryptionKeyUrl": "$encryptionKeyUrl"
                 }
               }
         }
   }
   

   Note

   La keyEncryptionKeyUrl doit contenir le nom de la clé, mais ne doit pas contenir une version de clé spécifique.

2. Exécutez la commande Azure CLI suivante pour effectuer un appel d’API REST pour créer un cluster Azure DocumentDB. Remplacez les espaces réservés dans la section des variables et le nom de fichier du paramètre --body dans la ligne de commande az rest par les valeurs réelles.

   # Define your variables
   $subscriptionId="00000000-0000-0000-0000-000000000000"
   $resourceGroup="resourceGroupName"
   $mongoClustersName="clusterName"
   
   # Execute the az rest command to make REST API call
   az rest --method "PUT" --url https://management.azure.com/subscriptions/$subscriptionId/resourceGroups/$resourceGroup/providers/Microsoft.DocumentDB/mongoClusters/${mongoClustersName}?api-version=2025-09-01 --body  @jsonFileFromThePreviousStep.json
   

Une fois le cluster restauré créé, passez en revue la liste des tâches après restauration.

Contenu connexe

• En savoir plus sur le chiffrement des données au repos dans Azure DocumentDB
• Dépanner la configuration de CMK
• En savoir plus sur les limitations des CMK
• Migrer des données vers Azure DocumentDB