Klantbeheerder sleutel (CMK) configureren voor data-encryptie in rust voor een Azure DocumentDB-cluster

In dit artikel leert u hoe u cmk (door de klant beheerde sleutel) configureert voor data-at-rest-versleuteling in Azure DocumentDB. Met de stappen in deze handleiding configureert u een nieuw Azure DocumentDB-cluster, een replicacluster of een hersteld cluster. CMK-installatie maakt gebruik van door de klant beheerde sleutel die is opgeslagen in een Azure Key Vault en door de gebruiker toegewezen beheerde identiteit.

Vereiste voorwaarden

• Een Azure-abonnement

  • Als u geen Azure-abonnement hebt, maakt u een gratis account

• Gebruik de Bash-omgeving in Azure Cloud Shell. Zie Aan de slag met Azure Cloud Shell voor meer informatie.

  

• Als je de voorkeur geeft aan het lokaal uitvoeren van CLI-referentiecommando's, installeer dan de Azure CLI. Als je op Windows of macOS werkt, overweeg dan om Azure CLI in een Docker-container uit te voeren. Voor meer informatie, zie Hoe u de Azure CLI in een Docker-container kunt uitvoeren.

  • Als u een lokale installatie gebruikt, meldt u zich aan bij Azure CLI met de opdracht az login. Om het authenticatieproces te voltooien, volgt u de stappen die op uw terminal worden weergegeven. Zie Verifiëren bij Azure met behulp van Azure CLI voor andere aanmeldingsopties.

  • Wanneer u daarom wordt gevraagd, installeer de Azure CLI-extensie bij het eerste gebruik. Zie Extensies gebruiken en beheren met de Azure CLIvoor meer informatie over extensies.

  • Voer az version uit om de geïnstalleerde versie en de afhankelijke bibliotheken te vinden. Voer az upgrade uit om naar de nieuwste versie te upgraden.

Door de gebruiker toegewezen beheerde identiteit en Azure Key Vault voorbereiden

Als u door de klant beheerde sleutelversleuteling wilt configureren in uw Azure DocumentDB voor MonogDB-cluster, hebt u een door de gebruiker toegewezen beheerde identiteit, een Azure Key Vault-exemplaar en machtigingen nodig die correct zijn geconfigureerd.

Belangrijk

Door de gebruiker toegewezen beheerde identiteit en het Azure Key Vault-exemplaar dat wordt gebruikt om CMK te configureren, moeten zich in dezelfde Azure-regio bevinden waar het Azure DocumentDB-cluster wordt gehost en allemaal deel uitmaken van dezelfde Microsoft-tenant.

Gebruik de Azure-portal:

1. Maak één door de gebruiker toegewezen beheerde identiteit in de clusterregio als u er nog geen hebt.

2. Maak één Azure Key Vault in de clusterregio als u nog geen sleutelarchief hebt gemaakt. Zorg ervoor dat u aan de vereisten voldoet. Volg ook de aanbevelingen voordat u het sleutelarchief configureert, en voordat u de sleutel maakt en de vereiste machtigingen toewijst aan de door de gebruiker toegewezen beheerde identiteit.

3. Maak één sleutel in uw sleutelarchief.

4. Verleen gebruiker-toegewezen machtigingen voor beheerde identiteiten aan het Azure Key Vault-exemplaar, zoals wordt beschreven in de vereisten.

Gegevensversleuteling configureren met door de klant beheerde sleutel tijdens het inrichten van clusters

Portal

1. Tijdens het inrichten van een nieuw Azure DocumentDB-cluster worden door de service beheerde of door de klant beheerde sleutels voor clustergegevensversleuteling geconfigureerd op het tabblad Versleuteling . Selecteer de door de klant beheerde sleutel voor gegevensversleuteling.

   

2. Selecteer in de sectie Door de gebruiker toegewezen beheerde identiteitde optie Identiteit wijzigen.

   

3. Selecteer in de lijst met door de gebruiker toegewezen beheerde identiteiten het cluster dat u wilt gebruiken voor toegang tot de gegevensversleutelingssleutel die is opgeslagen in een Azure Key Vault.

   

4. Selecteer Toevoegen.

   

5. Kies een sleutel selecteren in de methode Sleutelselectie.

6. Selecteer Sleutel wijzigen in de sectie Sleutel.

   

7. Selecteer in het deelvenster Een sleutel selecteren de Azure Key Vault in de sleutelkluis en versleutelingssleutel in de sleutel en bevestig uw keuzes door Selecteren te selecteren.

   

   Belangrijk

   Het geselecteerde Azure Key Vault-exemplaar moet zich in dezelfde Azure-regio bevinden waar het Azure DocumentDB-cluster wordt gehost.

8. Bevestig de geselecteerde door de gebruiker toegewezen beheerde identiteit en versleutelingssleutel op het tabblad Versleuteling en selecteer Beoordelen en maken om een cluster te maken.

   

REST API's

U kunt gegevensversleuteling inschakelen met een door de gebruiker toegewezen versleutelingssleutel, terwijl u een nieuw cluster inricht via een az rest opdracht.

1. Maak een JSON-bestand met de volgende inhoud. Vervang tijdelijke aanduidingen die beginnen met het teken door $ de werkelijke waarden en sla het bestand op.

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

   Opmerking

   De keyEncryptionKeyUrl sleutelnaam moet de sleutelnaam bevatten, maar mag geen specifieke sleutelversie bevatten.

2. Voer de volgende Azure CLI-opdracht uit om een REST API-aanroep uit te voeren om een Azure DocumentDB-cluster te maken. Vervang tijdelijke aanduidingen in de sectie variabelen en de bestandsnaam voor de --body parameter in de az rest opdrachtregel door de werkelijke waarden.

   # 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
   

Instellingen voor gegevensversleuteling op cluster bijwerken met CMK ingeschakeld

Voor bestaande clusters die zijn geïmplementeerd met gegevensversleuteling met behulp van een door de klant beheerde sleutel, kunt u verschillende configuratiewijzigingen uitvoeren. U kunt de sleutelkluis wijzigen waarin de versleutelingssleutel wordt opgeslagen en de versleutelingssleutel die wordt gebruikt als een door de klant beheerde sleutel. U kunt ook de door de gebruiker toegewezen beheerde identiteit wijzigen die door de service wordt gebruikt voor toegang tot de versleutelingssleutel die in het sleutelarchief wordt bewaard.

Portal

1. Selecteer gegevensversleuteling in de zijbalk van het cluster onder Instellingen.

2. Selecteer in de sectie Door de gebruiker toegewezen beheerde identiteitde optie Identiteit wijzigen.

   

3. Selecteer in de lijst met door de gebruiker toegewezen beheerde identiteiten het cluster dat u wilt gebruiken voor toegang tot de gegevensversleutelingssleutel die is opgeslagen in een Azure Key Vault.

   

4. Selecteer Toevoegen.

5. Kies een sleutel selecteren in de methode Sleutelselectie.

6. In de Sleutel kies Sleutel wijzigen.

   

7. Selecteer in het deelvenster Een sleutel selecteren de Azure Key Vault in de sleutelkluis en versleutelingssleutel in de sleutel en bevestig uw keuzes door Selecteren te selecteren.

   

   Belangrijk

   Het geselecteerde Azure Key Vault-exemplaar moet zich in dezelfde Azure-regio bevinden waar het Azure DocumentDB-cluster wordt gehost.

8. Bevestig de geselecteerde door de gebruiker toegewezen beheerde identiteit en versleutelingssleutel op de pagina Gegevensversleuteling en selecteer Opslaan om uw selecties te bevestigen en een replicacluster te maken.

   

REST API's

U kunt door de gebruiker toegewezen beheerde identiteit en versleutelingssleutel voor gegevensversleuteling op een bestaand cluster wijzigen via een REST API-aanroep.

1. Maak een JSON-bestand met de volgende inhoud. Vervang tijdelijke aanduidingen die beginnen met het teken door $ de werkelijke waarden en sla het bestand op.

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

   Opmerking

   De keyEncryptionKeyUrl sleutelnaam moet de sleutelnaam bevatten, maar mag geen specifieke sleutelversie bevatten.

2. Voer de volgende Azure CLI-opdracht uit om een REST API-aanroep uit te voeren om een Azure DocumentDB-cluster te maken. Vervang tijdelijke aanduidingen in de sectie variabelen en de bestandsnaam voor de --body parameter in de az rest opdrachtregel door de werkelijke waarden.

   # 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
   

Of u nu alleen de door de gebruiker toegewezen beheerde identiteit wilt wijzigen die wordt gebruikt voor toegang tot de sleutel, of u wilt alleen de sleutel wijzigen die wordt gebruikt voor gegevensversleuteling, of u wilt beide tegelijk wijzigen, u moet alle parameters opgeven die worden vermeld in het JSON-bestand.

Als de sleutel of de door de gebruiker toegewezen beheerde identiteit niet bestaat, wordt de fout weergegeven.

Identiteiten die worden doorgegeven als parameters, als deze bestaan en geldig zijn, worden automatisch toegevoegd aan de lijst met door de gebruiker toegewezen beheerde identiteiten die zijn gekoppeld aan uw Azure DocumentDB-cluster. Dit is het geval, zelfs als de opdracht later faalt door een andere fout.

De modus voor gegevensversleuteling op bestaande clusters wijzigen

Het enige punt waarop u kunt beslissen of u een door de service beheerde sleutel of een door de klant beheerde sleutel (CMK) wilt gebruiken voor gegevensversleuteling, is op het moment dat het cluster wordt gemaakt. Zodra u die beslissing hebt genomen en het cluster hebt gemaakt, kunt u niet schakelen tussen de twee opties. Als u een kopie van uw Azure DocumentDB-cluster wilt maken met een andere versleutelingsoptie, kunt u een replicacluster maken of een cluster herstellen en de nieuwe versleutelingsmodus selecteren tijdens het maken van een replicacluster of het herstellen van het cluster.

Cmk-gegevensversleuteling (door de klant beheerde sleutel) in- of uitschakelen tijdens het maken van een replicacluster

Volg deze stappen om een replicacluster te maken met CMK- of SMK-gegevensversleuteling om CMK in of uit te schakelen op een replicacluster.

Portal

1. Selecteer globale distributie in de zijbalk van het cluster onder Instellingen.

2. Selecteer Nieuwe leesreplica toevoegen.

   

3. Geef een replicaclusternaam op in het veld Leesreplicanaam.

4. Selecteer een regio in de Leesreplica-regio. Het replicacluster wordt gehost in de geselecteerde Azure-regio.

   Opmerking

   Replicacluster wordt altijd gemaakt in hetzelfde Azure-abonnement en dezelfde resourcegroep als het primaire cluster (read-write).

   

5. Selecteer in de sectie Gegevensversleuteling de door de klant beheerde sleutel om CMK of door de service beheerde sleutel in te schakelen om CMK uit te schakelen op het replicacluster.

   

6. Selecteer in de sectie Door de gebruiker toegewezen beheerde identiteitde optie Identiteit wijzigen.

   

7. Selecteer in de lijst met door de gebruiker toegewezen beheerde identiteiten het cluster dat u wilt gebruiken voor toegang tot de gegevensversleutelingssleutel die is opgeslagen in een Azure Key Vault.

   

8. Selecteer Toevoegen.

9. Kies een sleutel selecteren in de methode Sleutelselectie.

10. In de Sleutel kies Sleutel wijzigen.

    

11. Selecteer in het deelvenster Een sleutel selecteren de Azure Key Vault in de sleutelkluis en versleutelingssleutel in de sleutel en bevestig uw keuzes door Selecteren te selecteren.

    

12. Bevestig de geselecteerde door de gebruiker toegewezen beheerde identiteit en versleutelingssleutel op de pagina Globale distributie en selecteer Opslaan om uw selecties te bevestigen en een replicacluster te maken.

    

REST API's

Volg deze stappen om een replicacluster te maken waarvoor CMK is ingeschakeld in dezelfde regio.

1. Maak een JSON-bestand met de volgende inhoud. Vervang tijdelijke aanduidingen die beginnen met het teken door $ de werkelijke waarden en sla het bestand op.

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

   Opmerking

   De keyEncryptionKeyUrl sleutelnaam moet de sleutelnaam bevatten, maar mag geen specifieke sleutelversie bevatten.

2. Voer de volgende Azure CLI-opdracht uit om een REST API-aanroep uit te voeren om een Azure DocumentDB-cluster te maken. Vervang tijdelijke aanduidingen in de sectie variabelen en de bestandsnaam voor de --body parameter in de az rest opdrachtregel door de werkelijke waarden.

   # 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
   

Cmk-gegevensversleuteling (door de klant beheerde sleutel) in- of uitschakelen tijdens het herstellen van clusters

Het herstelproces maakt een nieuw cluster met dezelfde configuratie in dezelfde Azure-regio, hetzelfde abonnement en dezelfde resourcegroep als het origineel. Volg deze stappen om een hersteld cluster te maken waarvoor CMK of SMK is ingeschakeld.

Portal

1. Selecteer een bestaand Azure DocumentDB-cluster.

2. Selecteer op de zijbalk van het cluster onder Instellingen de optie Herstel naar een bepaald tijdstip.

3. Selecteer een datum en geef een tijd (in UTC-tijdzone) op in de datum- en tijdvelden.

   

4. Voer een clusternaam in het veld Doelclusternaam herstellen in.

   

5. Voer een clusterbeheerdernaam in voor het herstelde cluster in het veld Gebruikersnaam van beheerder.

6. Voer een wachtwoord in voor de beheerdersrol in de velden Wachtwoord en Wachtwoord bevestigen .

   

7. Selecteer in de sectie Gegevensversleuteling de door de klant beheerde sleutel om CMK in te schakelen. Als CMK moet zijn uitgeschakeld op het herstelde cluster, selecteert u de door de service beheerde sleutel.

   

8. Selecteer in de sectie Door de gebruiker toegewezen beheerde identiteitde optie Identiteit wijzigen.

   

9. Selecteer in de lijst met door de gebruiker toegewezen beheerde identiteiten het cluster dat u wilt gebruiken voor toegang tot de gegevensversleutelingssleutel die is opgeslagen in een Azure Key Vault.

   

10. Selecteer Toevoegen.

11. Kies een sleutel selecteren in de methode Sleutelselectie.

12. In de Sleutel kies Sleutel wijzigen.

    

13. Selecteer in het deelvenster Een sleutel selecteren de Azure Key Vault in de sleutelkluis en versleutelingssleutel in de sleutel en bevestig uw keuzes door Selecteren te selecteren.

    

14. Selecteer Verzenden om het herstellen van het cluster te initiëren.

REST API's

Volg deze stappen om een cluster te herstellen waarvoor CMK is ingeschakeld.

1. Maak een JSON-bestand met de volgende inhoud. Vervang tijdelijke aanduidingen die beginnen met het teken door $ de werkelijke waarden en sla het bestand op.

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

   Opmerking

   De keyEncryptionKeyUrl sleutelnaam moet de sleutelnaam bevatten, maar mag geen specifieke sleutelversie bevatten.

2. Voer de volgende Azure CLI-opdracht uit om een REST API-aanroep uit te voeren om een Azure DocumentDB-cluster te maken. Vervang tijdelijke aanduidingen in de sectie variabelen en de bestandsnaam voor de --body parameter in de az rest opdrachtregel door de werkelijke waarden.

   # 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
   

Nadat het herstelde cluster is gemaakt, bekijkt u de lijst met taken na het terugzetten.

Verwante inhoud

• Meer informatie over gegevensversleuteling in rusttoestand in Azure DocumentDB
• Problemen met CMK-installatie oplossen
• CMK-beperkingen uitchecken
• Gegevens migreren naar Azure DocumentDB