Konfigurowanie klucza zarządzanego przez klienta (CMK) na potrzeby szyfrowania danych magazynowanych dla klastra usługi Azure DocumentDB

Z tego artykułu dowiesz się, jak skonfigurować klucz zarządzany przez klienta (CMK) do szyfrowania danych w stanie spoczynku w usłudze Azure DocumentDB. Kroki opisane w tym przewodniku umożliwiają skonfigurowanie nowego klastra usługi Azure DocumentDB, klastra repliki lub przywróconego klastra. Konfiguracja CMK wykorzystuje klucz zarządzany przez klienta przechowywany w usłudze Azure Key Vault oraz tożsamość zarządzaną, przypisaną przez użytkownika.

Prerequisites

• Subskrypcja platformy Azure

  • Jeśli nie masz subskrypcji platformy Azure, utwórz bezpłatne konto

• Użyj środowiska Bash w Azure Cloud Shell. Aby uzyskać więcej informacji, zobacz Get started with Azure Cloud Shell.

  

• Jeśli wolisz uruchamiać polecenia referencyjne interfejsu wiersza polecenia lokalnie, zainstaluj Azure CLI. Jeśli korzystasz z systemu Windows lub macOS, rozważ uruchomienie Azure CLI w kontenerze Docker. Aby uzyskać więcej informacji, zobacz Jak uruchomić Azure CLI w kontenerze Docker.

  • Jeśli używasz instalacji lokalnej, zaloguj się do Azure CLI przy użyciu polecenia az login. Aby zakończyć proces uwierzytelniania, wykonaj kroki wyświetlane na Twoim terminalu. Aby uzyskać inne opcje logowania, zobacz Uwierzytelnianie do Azure za pomocą Azure CLI.

  • Gdy zostaniesz o to poproszony/a, zainstaluj rozszerzenie Azure CLI przy pierwszym użyciu. Aby uzyskać więcej informacji na temat rozszerzeń, zobacz Używanie rozszerzeń i zarządzanie nimi za pomocą Azure CLI.

  • Uruchom az version, aby sprawdzić zainstalowaną wersję i biblioteki zależne. Aby zaktualizować do najnowszej wersji, uruchom az upgrade.

Przygotowywanie tożsamości zarządzanej przypisanej przez użytkownika i usługi Azure Key Vault

Aby skonfigurować szyfrowanie kluczy zarządzanych przez klienta w klastrze usługi Azure DocumentDB for MonogDB, potrzebna jest tożsamość zarządzana przypisana przez użytkownika, wystąpienie usługi Azure Key Vault i prawidłowo skonfigurowane uprawnienia.

Ważna

Tożsamość zarządzana przypisana przez użytkownika i wystąpienie usługi Azure Key Vault używane do konfigurowania kluczy zarządzanych przez klientów (Customer Managed Key) powinny znajdować się w tym samym regionie Azure, w którym jest hostowany klaster usługi Azure DocumentDB, a wszystkie należą do tej samej dzierżawy firmy Microsoft.

Korzystanie z portalu Azure:

1. Utwórz jedną tożsamość zarządzaną przypisaną przez użytkownika w regionie klastra, jeśli jeszcze jej nie masz.

2. Utwórz jedną usługę Azure Key Vault w regionie klastra, jeśli nie masz jeszcze jednego magazynu kluczy. Upewnij się, że spełniasz wymagania. Ponadto, przed skonfigurowaniem magazynu kluczy, postępuj zgodnie z zaleceniami, a przed utworzeniem klucza przypisz wymagane uprawnienia do tożsamości zarządzanej przypisanej przez użytkownika.

3. Utwórz jeden klucz w magazynie kluczy.

4. Udziel uprawnień tożsamości zarządzanej przypisanej przez użytkownika do wystąpienia usługi Azure Key Vault, jak opisano w wymaganiach.

Konfigurowanie szyfrowania danych przy użyciu klucza zarządzanego przez klienta podczas aprowizacji klastra

Portal

1. Podczas aprowizacji nowego klastra usługi Azure DocumentDB klucze zarządzane przez usługę lub klucze zarządzane przez klienta na potrzeby szyfrowania danych klastra są konfigurowane na karcie Szyfrowanie . Wybierz klucz zarządzany przez klienta na potrzeby szyfrowania danych.

   

2. W sekcji Tożsamość zarządzana przypisana przez użytkownika wybierz pozycję Zmień tożsamość.

   

3. Na liście tożsamości zarządzanych przypisanych przez użytkownika wybierz tę, której klaster ma używać do uzyskiwania dostępu do klucza szyfrowania danych przechowywanego w usłudze Azure Key Vault.

   

4. Wybierz opcję Dodaj.

   

5. W metodzie Wyboru klucza wybierz pozycję Wybierz klucz .

6. W sekcji Klucz wybierz pozycję Zmień klucz .

   

7. W okienku Wybierz klucz wybierz Azure Key Vault z magazynu kluczy oraz klucz szyfrowania w kluczu, a następnie potwierdź swój wybór za pomocą opcji Wybierz.

   

   Ważna

   Wybrane wystąpienie usługi Azure Key Vault powinno znajdować się w tym samym regionie Azure, gdzie będzie hostowany klaster Azure DocumentDB.

8. Potwierdź wybraną tożsamość zarządzaną przypisaną przez użytkownika i klucz szyfrowania na karcie Szyfrowanie , a następnie wybierz pozycję Przejrzyj i utwórz , aby utworzyć klaster.

   

API REST

Szyfrowanie danych przy użyciu klucza szyfrowania przypisanego przez użytkownika można włączyć podczas aprowizacji nowego klastra az rest za pomocą polecenia .

1. Utwórz plik JSON z następującą zawartością. Zastąp symbole zastępcze rozpoczynające się znakiem $ rzeczywistymi wartościami i zapisz plik.

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

   Uwaga / Notatka

   Element keyEncryptionKeyUrl powinien zawierać nazwę klucza, ale nie powinien zawierać określonej wersji klucza.

2. Uruchom następujące polecenie Azure CLI, aby wykonać wywołanie interfejsu API REST w celu utworzenia klastra Azure DocumentDB. Zastąp symbole zastępcze w sekcji zmiennych oraz nazwę pliku dla parametru --body w wierszu polecenia az rest wartościami rzeczywistymi.

   # 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
   

Aktualizowanie ustawień szyfrowania danych w klastrze z włączonym kluczem zarządzanym przez klienta

W przypadku istniejących klastrów wdrożonych przy użyciu szyfrowania danych przy użyciu klucza zarządzanego przez klienta można wykonać kilka zmian konfiguracji. Możesz zmienić magazyn kluczy, w którym jest przechowywany klucz szyfrowania, oraz klucz szyfrowania używany jako klucz zarządzany przez klienta. Można również zmienić tożsamość zarządzaną przypisaną przez użytkownika używaną przez usługę w celu uzyskania dostępu do klucza szyfrowania przechowywanego w magazynie kluczy.

Portal

1. Na pasku bocznym klastra w obszarze Ustawienia wybierz pozycję Szyfrowanie danych.

2. W sekcji Tożsamość zarządzana przypisana przez użytkownika wybierz pozycję Zmień tożsamość.

   

3. Na liście tożsamości zarządzanych przypisanych przez użytkownika wybierz tę, której klaster ma używać do uzyskiwania dostępu do klucza szyfrowania danych przechowywanego w usłudze Azure Key Vault.

   

4. Wybierz opcję Dodaj.

5. W metodzie Wyboru klucza wybierz pozycję Wybierz klucz .

6. W polu Klucz wybierz pozycję Zmień klucz.

   

7. W okienku Wybierz klucz wybierz Azure Key Vault z magazynu kluczy oraz klucz szyfrowania w kluczu, a następnie potwierdź swój wybór za pomocą opcji Wybierz.

   

   Ważna

   Wybrane wystąpienie usługi Azure Key Vault powinno znajdować się w tym samym regionie świadczenia usługi Azure, w którym jest hostowany klaster usługi Azure DocumentDB.

8. Potwierdź wybraną tożsamość zarządzaną przypisaną przez użytkownika i klucz szyfrowania na stronie Szyfrowanie danych , a następnie wybierz pozycję Zapisz , aby potwierdzić wybrane opcje i utworzyć klaster repliki.

   

API REST

Tożsamość zarządzana przypisana przez użytkownika i klucz szyfrowania można zmienić na potrzeby szyfrowania danych w istniejącym klastrze za pośrednictwem wywołania interfejsu API REST.

1. Utwórz plik JSON z następującą zawartością. Zastąp symbole zastępcze rozpoczynające się znakiem $ rzeczywistymi wartościami i zapisz plik.

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

   Uwaga / Notatka

   Element keyEncryptionKeyUrl powinien zawierać nazwę klucza, ale nie powinien zawierać określonej wersji klucza.

2. Uruchom następujące polecenie Azure CLI, aby wykonać wywołanie interfejsu API REST w celu utworzenia klastra Azure DocumentDB. Zastąp symbole zastępcze w sekcji zmiennych oraz nazwę pliku dla parametru --body w wierszu polecenia az rest wartościami rzeczywistymi.

   # 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
   

Niezależnie od tego, czy chcesz zmienić tożsamość zarządzaną przypisaną przez użytkownika używaną do uzyskiwania dostępu do klucza, czy chcesz zmienić tylko klucz używany do szyfrowania danych, czy chcesz zmienić obie te elementy w tym samym czasie, musisz podać wszystkie parametry wymienione w pliku JSON.

Jeśli określony klucz lub określona tożsamość zarządzana przypisana przez użytkownika nie istnieje, zostanie wyświetlony błąd.

Tożsamości przekazywane jako parametry, jeśli istnieją i są prawidłowe, są automatycznie dodawane do listy tożsamości zarządzanych przypisanych przez użytkownika skojarzonych z klastrem usługi Azure DocumentDB. Tak jest, nawet jeśli polecenie później zakończy się niepowodzeniem z innym błędem.

Zmienianie trybu szyfrowania danych w istniejących klastrach

Jedynym punktem, w którym można zdecydować, czy chcesz użyć klucza zarządzanego przez usługę, czy klucza zarządzanego przez klienta (CMK) na potrzeby szyfrowania danych, jest w czasie tworzenia klastra. Po podjęciu tej decyzji i utworzeniu klastra nie można przełączać się między dwiema opcjami. Aby utworzyć kopię klastra usługi Azure DocumentDB z inną opcją szyfrowania, możesz utworzyć klaster repliki lub wykonać przywracanie klastra i wybrać nowy tryb szyfrowania podczas tworzenia klastra repliki lub przywróconego klastra.

Włączanie lub wyłączanie szyfrowania danych klucza zarządzanego przez klienta (CMK) podczas tworzenia klastra repliki

Wykonaj następujące kroki, aby utworzyć klaster replik z szyfrowaniem danych za pomocą CMK lub SMK, aby umożliwić lub wyłączyć CMK na klastrze replik.

Portal

1. Na pasku bocznym klastra w obszarze Ustawienia wybierz pozycję Dystrybucja globalna.

2. Wybierz Dodaj nową replikę do odczytu.

   

3. Podaj nazwę klastra repliki w polu Nazwa repliki do odczytu .

4. Wybierz region w regionie repliki odczytu. Klaster repliki jest hostowany w wybranym regionie świadczenia usługi Azure.

   Uwaga / Notatka

   Klaster repliki jest zawsze tworzony w tej samej subskrypcji Azure i grupie zasobów, co jego podstawowy klaster (odczyt-zapis).

   

5. W sekcji Szyfrowanie danych wybierz klucz zarządzany przez klienta, aby włączyć CMK lub klucz zarządzany przez usługę, aby wyłączyć CMK w klastrze repliki.

   

6. W sekcji Tożsamość zarządzana przypisana przez użytkownika wybierz pozycję Zmień tożsamość.

   

7. Na liście tożsamości zarządzanych przypisanych przez użytkownika wybierz tę, której klaster ma używać do uzyskiwania dostępu do klucza szyfrowania danych przechowywanego w usłudze Azure Key Vault.

   

8. Wybierz opcję Dodaj.

9. W metodzie Wyboru klucza wybierz pozycję Wybierz klucz .

10. W polu Klucz wybierz pozycję Zmień klucz.

    

11. W okienku Wybierz klucz wybierz Azure Key Vault z magazynu kluczy oraz klucz szyfrowania w kluczu, a następnie potwierdź swój wybór za pomocą opcji Wybierz.

    

12. Potwierdź wybraną tożsamość zarządzaną przypisaną przez użytkownika i klucz szyfrowania na stronie Globalnej dystrybucji , a następnie wybierz pozycję Zapisz , aby potwierdzić wybrane opcje i utworzyć klaster repliki.

    

API REST

Aby utworzyć klaster replik z włączonym kluczem CMK w tym samym regionie, należy wykonać następujące kroki.

1. Utwórz plik JSON z następującą zawartością. Zastąp symbole zastępcze rozpoczynające się znakiem $ rzeczywistymi wartościami i zapisz plik.

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

   Uwaga / Notatka

   Element keyEncryptionKeyUrl powinien zawierać nazwę klucza, ale nie powinien zawierać określonej wersji klucza.

2. Uruchom następujące polecenie Azure CLI, aby wykonać wywołanie interfejsu API REST w celu utworzenia klastra Azure DocumentDB. Zastąp symbole zastępcze w sekcji zmiennych oraz nazwę pliku dla parametru --body w wierszu polecenia az rest wartościami rzeczywistymi.

   # 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
   

Włączanie lub wyłączanie szyfrowania danych klucza zarządzanego przez klienta (CMK) podczas przywracania klastra

Proces przywracania tworzy nowy klaster z tą samą konfiguracją w tym samym regionie, subskrypcji i grupie zasobów platformy Azure co oryginalna. Wykonaj następujące kroki, aby utworzyć odtworzony klaster z włączonymi kluczami CMK lub SMK.

Portal

1. Wybierz istniejący klaster usługi Azure DocumentDB.

2. Na pasku bocznym klastra w obszarze Ustawienia wybierz pozycję Przywracanie punktu czasowego.

3. Wybierz datę i podaj godzinę (w strefie czasowej UTC) w polach daty i godziny.

   

4. Wprowadź nazwę klastra w polu Przywróć nazwę docelowego klastra .

   

5. Wprowadź nazwę administratora klastra dla przywróconego klastra w polu Nazwa użytkownika administratora .

6. Wprowadź hasło roli administratora w polach Hasło i Potwierdź hasło .

   

7. W sekcji Szyfrowanie danych wybierz klucz zarządzany przez klienta , aby włączyć klucz cmK. Jeśli potrzebujesz wyłączyć CMK w przywróconym klastrze, wybierz klucz zarządzany przez usługodawcę.

   

8. W sekcji Tożsamość zarządzana przypisana przez użytkownika wybierz pozycję Zmień tożsamość.

   

9. Na liście tożsamości zarządzanych przypisanych przez użytkownika wybierz tę, której klaster ma używać do uzyskiwania dostępu do klucza szyfrowania danych przechowywanego w usłudze Azure Key Vault.

   

10. Wybierz opcję Dodaj.

11. W metodzie Wyboru klucza wybierz pozycję Wybierz klucz .

12. W polu Klucz wybierz pozycję Zmień klucz.

    

13. W okienku Wybierz klucz wybierz Azure Key Vault z magazynu kluczy oraz klucz szyfrowania w kluczu, a następnie potwierdź swój wybór za pomocą opcji Wybierz.

    

14. Wybierz pozycję Prześlij , aby zainicjować przywracanie klastra.

API REST

Aby przywrócić klaster z włączoną funkcją CMK, wykonaj następujące kroki.

1. Utwórz plik JSON z następującą zawartością. Zastąp symbole zastępcze rozpoczynające się znakiem $ rzeczywistymi wartościami i zapisz plik.

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

   Uwaga / Notatka

   Element keyEncryptionKeyUrl powinien zawierać nazwę klucza, ale nie powinien zawierać określonej wersji klucza.

2. Uruchom następujące polecenie Azure CLI, aby wykonać wywołanie interfejsu API REST w celu utworzenia klastra Azure DocumentDB. Zastąp symbole zastępcze w sekcji zmiennych oraz nazwę pliku dla parametru --body w wierszu polecenia az rest wartościami rzeczywistymi.

   # 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
   

Po utworzeniu przywróconego klastra przejrzyj listę zadań po przywróceniu.

Treści powiązane

• Dowiedz się więcej o szyfrowaniu danych magazynowanych w usłudze Azure DocumentDB
• Rozwiązywanie problemów z konfiguracją CMK
• Zapoznaj się z ograniczeniami CMK
• Migrowanie danych do usługi Azure DocumentDB