Konfigurera kundhanterad nyckel (CMK) för vilande datakryptering för ett Azure DocumentDB-kluster

I den här artikeln får du lära dig hur du konfigurerar kundhanterad nyckel (CMK) för datakryptering i vila i Azure DocumentDB. Stegen i den här guiden konfigurerar ett nytt Azure DocumentDB-kluster, ett replikkluster eller ett återställt kluster. CMK-konfigurationen använder kundhanterad nyckel som lagras i ett Azure Key Vault och en användartilldelad hanterad identitet.

Förutsättningar

• En prenumeration på Azure

  • Om du inte har någon Azure-prenumeration kan du skapa ett kostnadsfritt konto

• Använd Bash-miljön i Azure Cloud Shell. Mer information finns i Kom igång med Azure Cloud Shell.

  

• Om du föredrar att köra CLI-referenskommandon lokalt installerar du Azure CLI. Om du kör på Windows eller macOS, överväg att köra Azure CLI i en Docker-container. För mer information, se Hur man kör Azure CLI i en Docker-container.

  • Om du använder en lokal installation loggar du in på Azure CLI med hjälp av kommandot az login. För att avsluta autentiseringsprocessen, följ stegen som visas i din terminal. Andra inloggningsalternativ finns i Autentisera till Azure med Azure CLI.

  • När du blir uppmanad, installera Azure CLI-tillägget vid första användning. Mer information om tillägg finns i Använda och hantera tillägg med Azure CLI.

  • Kör az version för att ta reda på versionen och de beroende bibliotek som är installerade. Om du vill uppgradera till den senaste versionen kör du az upgrade.

Förbereda användartilldelad hanterad identitet och Azure Key Vault

För att konfigurera kundhanterad nyckelkryptering i ditt Azure DocumentDB för MonogDB-kluster behöver du en användartilldelad hanterad identitet, en Azure Key Vault-instans och behörigheter som är korrekt konfigurerade.

Viktigt!

Användartilldelad hanterad identitet och Azure Key Vault-instans som används för att konfigurera CMK ska finnas i samma Azure-region där Azure DocumentDB-klustret finns och alla tillhör samma Microsoft-klientorganisation.

Använda Azure-portalen:

1. Skapa en användartilldelad hanterad identitet i klusterregionen om du inte har någon ännu.

2. Skapa ett Azure Key Vault i klusterregionen om du inte har skapat något nyckelarkiv ännu. Se till att du uppfyller kraven. Följ också rekommendationerna innan du konfigurerar nyckelarkivet och innan du skapar nyckeln och tilldelar nödvändiga behörigheter till den användartilldelade hanterade identiteten.

3. Skapa en nyckel i nyckelarkivet.

4. Bevilja användartilldelade hanterade identitetsbehörigheter till Azure Key Vault-instansen enligt vad som beskrivs i kraven.

Konfigurera datakryptering med kundhanterad nyckel under klusteretablering

Portal

1. Under etableringen av ett nytt Azure DocumentDB-kluster konfigureras tjänsthanterade eller kundhanterade nycklar för klusterdatakryptering på fliken Kryptering . Välj den kundhanterade nyckeln för datakryptering.

   

2. I avsnittet Användartilldelad hanterad identitet väljer du Ändra identitet.

   

3. I listan över användartilldelade hanterade identiteter väljer du den som du vill att klustret ska använda för att komma åt datakrypteringsnyckeln som lagras i ett Azure Key Vault.

   

4. Välj Lägg till.

   

5. I metoden Nyckelval väljer du Välj en nyckel .

6. I avsnittet Nyckel väljer du Ändra nyckel .

   

7. I fönstret Välj en nyckel väljer du Azure Key Vault i nyckelvalvet och krypteringsnyckeln i nyckeln och bekräftar dina val genom att välja Välj.

   

   Viktigt!

   Den valda Azure Key Vault-instansen ska finnas i samma Azure-region där Azure DocumentDB-klustret ska finnas.

8. Bekräfta vald användartilldelad hanterad identitet och krypteringsnyckel på fliken Kryptering och välj Granska + skapa för att skapa kluster.

   

REST-APIer

Du kan aktivera datakryptering med användartilldelad krypteringsnyckel när du etablerar ett nytt kluster via ett az rest kommando.

1. Skapa en JSON-fil med följande innehåll. Ersätt platshållare som börjar med sign med $ de faktiska värdena och spara filen.

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

   Anmärkning

   keyEncryptionKeyUrl Ska innehålla nyckelnamnet men får inte innehålla någon specifik nyckelversion.

2. Kör följande Azure CLI-kommando för att göra ett REST API-anrop för att skapa ett Azure DocumentDB-kluster. Ersätt platshållarna i avsnittet variabler och filnamnet för parametern --body på kommandoraden az rest med de faktiska värdena.

   # 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
   

Uppdatera inställningar för datakryptering i kluster med CMK aktiverat

För befintliga kluster som har distribuerats med datakryptering med hjälp av en kundhanterad nyckel kan du göra flera konfigurationsändringar. Du kan ändra nyckelvalvet där krypteringsnyckeln lagras och krypteringsnyckeln som används som kundhanterad nyckel. Du kan också ändra den användartilldelade hanterade identiteten som används av tjänsten för att få åtkomst till krypteringsnyckeln som lagras i nyckelarkivet.

Portal

1. I klustrets sidofält går du till Inställningar och väljer Datakryptering.

2. I avsnittet Användartilldelad hanterad identitet väljer du Ändra identitet.

   

3. I listan över användartilldelade hanterade identiteter väljer du den som du vill att klustret ska använda för att komma åt datakrypteringsnyckeln som lagras i ett Azure Key Vault.

   

4. Välj Lägg till.

5. I metoden Nyckelval väljer du Välj en nyckel .

6. I nyckeln väljer du Ändra nyckel.

   

7. I fönstret Välj en nyckel väljer du Azure Key Vault i nyckelvalvet och krypteringsnyckeln i nyckeln och bekräftar dina val genom att välja Välj.

   

   Viktigt!

   Den valda Azure Key Vault-instansen ska finnas i samma Azure-region där Azure DocumentDB-klustret finns.

8. Bekräfta vald användartilldelad hanterad identitet och krypteringsnyckel på sidan Datakryptering och välj Spara för att bekräfta dina val och skapa replikkluster.

   

REST-APIer

Du kan ändra användartilldelad hanterad identitet och krypteringsnyckel för datakryptering i ett befintligt kluster via ett REST API-anrop.

1. Skapa en JSON-fil med följande innehåll. Ersätt platshållare som börjar med sign med $ de faktiska värdena och spara filen.

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

   Anmärkning

   keyEncryptionKeyUrl Ska innehålla nyckelnamnet men får inte innehålla någon specifik nyckelversion.

2. Kör följande Azure CLI-kommando för att göra ett REST API-anrop för att skapa ett Azure DocumentDB-kluster. Ersätt platshållarna i avsnittet variabler och filnamnet för parametern --body på kommandoraden az rest med de faktiska värdena.

   # 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
   

Oavsett om du bara vill ändra den användartilldelade hanterade identiteten som används för åtkomst till nyckeln, eller om du bara vill ändra nyckeln som används för datakryptering, eller om du vill ändra båda samtidigt, måste du ange alla parametrar som anges i JSON-filen.

Om nyckeln eller den angivna användartilldelade hanterade identiteten inte finns får du felet.

Identiteter som skickas som parametrar, om de finns och är giltiga, läggs automatiskt till i listan över användartilldelade hanterade identiteter som är associerade med ditt Azure DocumentDB-kluster. Detta gäller även om kommandot senare misslyckas med något annat fel.

Ändra datakrypteringsläge i befintliga kluster

Den enda punkt där du kan bestämma om du vill använda en tjänsthanterad nyckel eller en kundhanterad nyckel (CMK) för datakryptering är när klustret skapas. När du har fattat det beslutet och skapat klustret kan du inte växla mellan de två alternativen. Om du vill skapa en kopia av ditt Azure DocumentDB-kluster med ett annat krypteringsalternativ kan du antingen skapa ett replikkluster eller utföra en klusteråterställning och välja det nya krypteringsläget när replikklustret eller det återställde klustret skapas.

Aktivera eller inaktivera kundhanterad nyckelkryptering (CMK) när replikkluster skapas

Följ dessa steg för att skapa ett replikkluster med CMK- eller SMK-datakryptering för att aktivera eller inaktivera CMK i ett replikkluster.

Portal

1. Välj Global distribution under Inställningar i sidopanelen för klustret.

2. Välj Lägg till ny läsreplik.

   

3. Ange ett replikklusternamn i fältet Skrivskyddat repliknamn .

4. Välj en region i läsreplikregionen. Replikklustret finns i den valda Azure-regionen.

   Anmärkning

   Replikkluster skapas alltid i samma Azure-prenumeration och resursgrupp som dess primära (skrivskyddade) kluster.

   

5. I avsnittet Datakryptering väljer du den kundhanterade nyckeln för att aktivera CMK eller tjänsthanterad nyckel för att inaktivera CMK i replikklustret.

   

6. I avsnittet Användartilldelad hanterad identitet väljer du Ändra identitet.

   

7. I listan över användartilldelade hanterade identiteter väljer du den som du vill att klustret ska använda för att komma åt datakrypteringsnyckeln som lagras i ett Azure Key Vault.

   

8. Välj Lägg till.

9. I metoden Nyckelval väljer du Välj en nyckel .

10. I nyckeln väljer du Ändra nyckel.

    

11. I fönstret Välj en nyckel väljer du Azure Key Vault i nyckelvalvet och krypteringsnyckeln i nyckeln och bekräftar dina val genom att välja Välj.

    

12. Bekräfta vald användartilldelad hanterad identitet och krypteringsnyckel på sidan Global distribution och välj Spara för att bekräfta dina val och skapa replikkluster.

    

REST-APIer

Följ dessa steg om du vill skapa ett replikkluster med CMK aktiverat i samma region.

1. Skapa en JSON-fil med följande innehåll. Ersätt platshållare som börjar med sign med $ de faktiska värdena och spara filen.

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

   Anmärkning

   keyEncryptionKeyUrl Ska innehålla nyckelnamnet men får inte innehålla någon specifik nyckelversion.

2. Kör följande Azure CLI-kommando för att göra ett REST API-anrop för att skapa ett Azure DocumentDB-kluster. Ersätt platshållarna i avsnittet variabler och filnamnet för parametern --body på kommandoraden az rest med de faktiska värdena.

   # 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
   

Aktivera eller inaktivera kundhanterad nyckelkryptering (CMK) under klusteråterställning

Återställningsprocessen skapar ett nytt kluster med samma konfiguration i samma Azure-region, prenumeration och resursgrupp som originalet. Följ de här stegen för att skapa ett återställt kluster med CMK eller SMK aktiverat.

Portal

1. Välj ett befintligt Azure DocumentDB-kluster.

2. I klustrets sidofält går du till Inställningar och väljer Återställning till tidpunkt.

3. Välj ett datum och ange en tid (i UTC-tidszonen) i datum- och tidsfälten.

   

4. Ange ett klusternamn i fältet Återställ målklusternamn .

   

5. Ange ett klusteradministratörsnamn för det återställde klustret i fältet Administratörsanvändarnamn .

6. Ange ett lösenord för administratörsrollen i fälten Lösenord och Bekräfta lösenord .

   

7. I avsnittet Datakryptering väljer du den kundhanterade nyckeln för att aktivera CMK. Om du behöver ha CMK inaktiverat i det återställde klustret väljer du Tjänsthanterad nyckel.

   

8. I avsnittet Användartilldelad hanterad identitet väljer du Ändra identitet.

   

9. I listan över användartilldelade hanterade identiteter väljer du den som du vill att klustret ska använda för att komma åt datakrypteringsnyckeln som lagras i ett Azure Key Vault.

   

10. Välj Lägg till.

11. I metoden Nyckelval väljer du Välj en nyckel .

12. I nyckeln väljer du Ändra nyckel.

    

13. I fönstret Välj en nyckel väljer du Azure Key Vault i nyckelvalvet och krypteringsnyckeln i nyckeln och bekräftar dina val genom att välja Välj.

    

14. Välj Skicka för att initiera klusteråterställning.

REST-APIer

Följ dessa steg för att återställa ett kluster med CMK aktiverat.

1. Skapa en JSON-fil med följande innehåll. Ersätt platshållare som börjar med sign med $ de faktiska värdena och spara filen.

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

   Anmärkning

   keyEncryptionKeyUrl Ska innehålla nyckelnamnet men får inte innehålla någon specifik nyckelversion.

2. Kör följande Azure CLI-kommando för att göra ett REST API-anrop för att skapa ett Azure DocumentDB-kluster. Ersätt platshållarna i avsnittet variabler och filnamnet för parametern --body på kommandoraden az rest med de faktiska värdena.

   # 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
   

När det återställde klustret har skapats granskar du listan över uppgifter efter återställningen.

Relaterat innehåll

• Lär dig mer om vilande datakryptering i Azure DocumentDB
• Felsöka CMK-konfiguration
• Kolla in CMK-begränsningar
• Migrera data till Azure DocumentDB