Настройка управляемого клиентом ключа (CMK) для шифрования неактивных данных для кластера Azure DocumentDB

В этой статье вы узнаете, как настроить управляемый клиентом ключ (CMK) для шифрования данных в Azure DocumentDB. В этом руководстве описано, как настроить новый кластер Azure DocumentDB, кластер реплики или восстановленный кластер. Программа установки CMK использует управляемый клиентом ключ, хранящийся в Azure Key Vault, и управляемое удостоверение, назначаемое пользователем.

Предпосылки

• подписка Azure

  • Если у вас нет подписки Azure, создайте бесплатную учетную запись.

• Используйте среду Bash в Azure Cloud Shell. Дополнительные сведения см. в статье "Начало работы с Azure Cloud Shell".

  

• Если вы предпочитаете запускать справочные команды CLI локально, установите Azure CLI. Если вы работаете в Windows или macOS, подумайте о запуске Azure CLI в контейнере Docker. Дополнительные сведения см. в статье Как запустить Azure CLI в контейнере Docker.

  • Если вы используете локальную установку, войдите в Azure CLI с помощью команды az login . Чтобы завершить процесс аутентификации, следуйте шагам, отображаемым в вашем терминале. Сведения о других параметрах входа см. в статье "Проверка подлинности в Azure с помощью Azure CLI".

  • Когда вас попросят, установите расширение Azure CLI при первом использовании. Дополнительные сведения о расширениях см. в статье Использование расширений и управление ими с помощью Azure CLI.

  • Выполните команду az version, чтобы узнать установленную версию и зависимые библиотеки. Чтобы обновиться до последней версии, выполните команду az upgrade.

Подготовка управляемого удостоверения, назначаемого пользователем, и Azure Key Vault

Чтобы настроить шифрование ключей, управляемых клиентом, в кластере Azure DocumentDB для MonogDB, вам потребуется управляемое удостоверение, назначаемое пользователем, экземпляр Azure Key Vault и правильно настроенные разрешения.

Это важно

Назначаемое пользователем управляемое удостоверение и экземпляр Azure Key Vault, используемые для настройки CMK, должны находиться в одном регионе Azure, где размещен кластер Azure DocumentDB, и все они принадлежат одному клиенту Майкрософт.

Использование портала Azure:

1. Создайте одно управляемое удостоверение, назначаемое пользователем , в регионе кластера, если у вас еще нет.

2. Создайте azure Key Vault в регионе кластера, если у вас еще нет одного хранилища ключей. Убедитесь, что выполнены требования. Кроме того, следуйте рекомендациям перед настройкой хранилища ключей и перед созданием ключа и назначьте необходимые разрешения управляемому удостоверению, назначаемого пользователем.

3. Создайте один ключ в хранилище ключей.

4. Предоставьте разрешения на управляемое удостоверение, назначаемое пользователем, экземпляру Azure Key Vault, как описано в требованиях.

Настройка шифрования данных с помощью управляемого клиентом ключа во время подготовки кластера

Портал

1. Во время подготовки нового кластера Azure DocumentDB управляемые службой ключи или ключи, управляемые клиентом для шифрования данных кластера, настраиваются на вкладке "Шифрование ". Выберите ключ, управляемый клиентом , для шифрования данных.

   

2. В разделе управляемого удостоверения, назначаемого пользователем, выберите "Изменить удостоверение".

   

3. В списке управляемых удостоверений, назначаемых пользователем, выберите нужный кластер для доступа к ключу шифрования данных, хранящимся в Azure Key Vault.

   

4. Нажмите кнопку "Добавить".

   

5. В методе выбора ключа выберите "Выбрать ключ ".

6. В разделе "Ключ" выберите "Изменить ключ ".

   

7. В области "Выбор ключа " выберите Azure Key Vault в хранилище ключей и ключ шифрования в ключе и подтвердите выбор, нажав кнопку "Выбрать".

   

   Это важно

   Выбранный экземпляр Azure Key Vault должен находиться в том же регионе Azure, где будет размещен кластер Azure DocumentDB.

8. Подтвердите назначаемое пользователем управляемое удостоверение и ключ шифрования на вкладке "Шифрование " и выберите "Проверить и создать ", чтобы создать кластер.

   

REST API

Вы можете включить шифрование данных с помощью ключа шифрования, назначаемого пользователем, при подготовке нового кластера с помощью az rest команды.

1. Создайте JSON-файл со следующим содержимым. Замените заполнители, начинающиеся с $ знака фактическими значениями, и сохраните файл.

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

   Замечание

   Он keyEncryptionKeyUrl должен содержать имя ключа, но не должен содержать определенную версию ключа.

2. Выполните следующую команду Azure CLI, чтобы выполнить вызов REST API для создания кластера Azure DocumentDB. Замените заполнители в разделе переменных и имя файла для --body параметра в командной строке az rest фактическими значениями.

   # 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
   

Обновление параметров шифрования данных в кластере с поддержкой CMK

Для существующих кластеров, которые были развернуты с шифрованием данных с помощью ключа, управляемого клиентом, можно выполнить несколько изменений конфигурации. Вы можете изменить хранилище ключей, в котором хранится ключ шифрования, и ключ шифрования, используемый в качестве управляемого клиентом ключа. Вы также можете изменить управляемое удостоверение, назначаемое пользователем, используемое службой для доступа к ключу шифрования, сохраненном в хранилище ключей.

Портал

1. На боковой панели кластера в разделе "Параметры" выберите "Шифрование данных".

2. В разделе управляемого удостоверения, назначаемого пользователем, выберите "Изменить удостоверение".

   

3. В списке управляемых удостоверений, назначаемых пользователем, выберите нужный кластер для доступа к ключу шифрования данных, хранящимся в Azure Key Vault.

   

4. Нажмите кнопку "Добавить".

5. В методе выбора ключа выберите "Выбрать ключ ".

6. В разделе "Ключ" выберите "Изменить ключ".

   

7. В области "Выбор ключа " выберите Azure Key Vault в хранилище ключей и ключ шифрования в ключе и подтвердите выбор, нажав кнопку "Выбрать".

   

   Это важно

   Выбранный экземпляр Azure Key Vault должен находиться в том же регионе Azure, где размещен кластер Azure DocumentDB.

8. Убедитесь, что на странице шифрования данных выбрано управляемое удостоверение и ключ шифрования, назначаемые пользователем, и нажмите кнопку "Сохранить ", чтобы подтвердить выбранные параметры и создать кластер реплики.

   

REST API

Вы можете изменить назначаемое пользователем управляемое удостоверение и ключ шифрования для шифрования данных в существующем кластере с помощью вызова REST API.

1. Создайте JSON-файл со следующим содержимым. Замените заполнители, начинающиеся с $ знака фактическими значениями, и сохраните файл.

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

   Замечание

   Он keyEncryptionKeyUrl должен содержать имя ключа, но не должен содержать определенную версию ключа.

2. Выполните следующую команду Azure CLI, чтобы выполнить вызов REST API для создания кластера Azure DocumentDB. Замените заполнители в разделе переменных и имя файла для --body параметра в командной строке az rest фактическими значениями.

   # 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
   

Хотите ли вы изменить только управляемое удостоверение, назначаемое пользователем для доступа к ключу, или хотите изменить только ключ, используемый для шифрования данных, или вы хотите изменить оба в одно и то же время, необходимо предоставить все параметры, перечисленные в JSON-файле.

Если ключ или назначаемое пользователем управляемое удостоверение не существует, возникает ошибка.

Удостоверения, передаваемые в качестве параметров, если они существуют и допустимы, автоматически добавляются в список управляемых удостоверений, назначенных пользователем, связанных с кластером Azure DocumentDB. Это остается фактом, даже если команда позже все равно закончится другой ошибкой.

Изменение режима шифрования данных в существующих кластерах

Единственный момент, в котором можно решить, следует ли использовать управляемый службой ключ или ключ, управляемый клиентом для шифрования данных, — во время создания кластера. После принятия этого решения и создания кластера нельзя переключаться между двумя параметрами. Чтобы создать копию кластера Azure DocumentDB с другим параметром шифрования, можно создать кластер реплики или выполнить восстановление кластера и выбрать новый режим шифрования во время кластера реплики или восстановленного создания кластера.

Включение или отключение шифрования данных, управляемого клиентом (CMK), во время создания кластера реплики

Выполните следующие действия, чтобы создать кластер реплики с шифрованием данных CMK или SMK, чтобы включить или отключить CMK в кластере реплики.

Портал

1. На боковой панели кластера в разделе "Параметры" выберите "Глобальное распределение".

2. Выберите Добавить новую реплику для чтения.

   

3. Укажите имя кластера реплики в поле имени реплики чтения .

4. Выберите регион в регионе реплики чтения. Кластер реплики размещается в выбранном регионе Azure.

   Замечание

   Кластер реплик всегда создается в той же подписке Azure и группе ресурсов, что и его основной кластер (чтение и запись).

   

5. В разделе "Шифрование данных " выберите ключ, управляемый клиентом , чтобы включить ключ CMK или управляемый службой ключ , чтобы отключить CMK в кластере реплики.

   

6. В разделе управляемого удостоверения, назначаемого пользователем, выберите "Изменить удостоверение".

   

7. В списке управляемых удостоверений, назначаемых пользователем, выберите нужный кластер для доступа к ключу шифрования данных, хранящимся в Azure Key Vault.

   

8. Нажмите кнопку "Добавить".

9. В методе выбора ключа выберите "Выбрать ключ ".

10. В разделе "Ключ" выберите "Изменить ключ".

    

11. В области "Выбор ключа " выберите Azure Key Vault в хранилище ключей и ключ шифрования в ключе и подтвердите выбор, нажав кнопку "Выбрать".

    

12. Подтвердите назначаемое пользователем управляемое удостоверение и ключ шифрования на странице глобального распространения и нажмите кнопку "Сохранить ", чтобы подтвердить выбор и создать кластер реплики.

    

REST API

Чтобы создать кластер реплики с поддержкой CMK в том же регионе, выполните следующие действия.

1. Создайте JSON-файл со следующим содержимым. Замените заполнители, начинающиеся с $ знака фактическими значениями, и сохраните файл.

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

   Замечание

   Он keyEncryptionKeyUrl должен содержать имя ключа, но не должен содержать определенную версию ключа.

2. Выполните следующую команду Azure CLI, чтобы выполнить вызов REST API для создания кластера Azure DocumentDB. Замените заполнители в разделе переменных и имя файла для --body параметра в командной строке az rest фактическими значениями.

   # 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), во время восстановления кластера

Процесс восстановления создает новый кластер с той же конфигурацией в том же регионе Azure, подписке и группе ресурсов, что и исходная. Выполните следующие действия, чтобы создать восстановленный кластер с поддержкой CMK или SMK.

Портал

1. Выберите существующий кластер Azure DocumentDB.

2. На боковой панели кластера в разделе "Параметры" выберите " Восстановление точки во времени".

3. Выберите дату и укажите время (в часовом поясе UTC) в полях даты и времени.

   

4. Введите имя кластера в поле "Имя целевого кластера восстановления ".

   

5. Введите имя администратора кластера для восстановленного кластера в поле имени пользователя администратора .

6. Введите пароль для роли администратора в полях "Пароль " и "Подтверждение пароля ".

   

7. В разделе "Шифрование данных " выберите ключ, управляемый клиентом , чтобы включить CMK. Если необходимо отключить CMK в восстановленном кластере, выберите управляемый службой ключ.

   

8. В разделе управляемого удостоверения, назначаемого пользователем, выберите "Изменить удостоверение".

   

9. В списке управляемых удостоверений, назначаемых пользователем, выберите нужный кластер для доступа к ключу шифрования данных, хранящимся в Azure Key Vault.

   

10. Нажмите кнопку "Добавить".

11. В методе выбора ключа выберите "Выбрать ключ ".

12. В разделе "Ключ" выберите "Изменить ключ".

    

13. В области "Выбор ключа " выберите Azure Key Vault в хранилище ключей и ключ шифрования в ключе и подтвердите выбор, нажав кнопку "Выбрать".

    

14. Нажмите кнопку "Отправить ", чтобы инициировать восстановление кластера.

REST API

Чтобы восстановить кластер с поддержкой CMK, выполните следующие действия.

1. Создайте JSON-файл со следующим содержимым. Замените заполнители, начинающиеся с $ знака фактическими значениями, и сохраните файл.

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

   Замечание

   Он keyEncryptionKeyUrl должен содержать имя ключа, но не должен содержать определенную версию ключа.

2. Выполните следующую команду Azure CLI, чтобы выполнить вызов REST API для создания кластера Azure DocumentDB. Замените заполнители в разделе переменных и имя файла для --body параметра в командной строке az rest фактическими значениями.

   # 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
   

После создания восстановленного кластера просмотрите список задач после восстановления.

Связанный контент

• Сведения о шифровании неактивных данных в Azure DocumentDB
• Устранение неполадок при настройке CMK
• Ознакомьтесь с ограничениями CMK
• Перенос данных в Azure DocumentDB