Настройка ключей, управляемых клиентом, для учетной записи Azure Cosmos DB с помощью Azure Key Vault

Область применения: NoSQL Mongodb Кассандра Гремлин Таблица

Данные, хранящиеся в учетной записи Azure Cosmos DB, автоматически шифруются с помощью ключей, управляемых корпорацией Майкрософт (ключи, управляемые службой). При необходимости можно добавить второй уровень шифрования с ключами, которыми вы управляете (ключи, управляемые клиентом или CMK).

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

Предварительные условия

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

Регистрация поставщика ресурсов Azure Cosmos DB

Если поставщик ресурсов Microsoft.DocumentDB еще не зарегистрирован, необходимо зарегистрировать этот поставщик в качестве первого шага.

1. Войдите на портал Azure, перейдите к своей подписке Azure и на вкладке Параметры выберите Поставщики ресурсов.

   

2. Найдите поставщик ресурсов Microsoft.DocumentDB. Убедитесь, что поставщик ресурсов уже помечен как зарегистрированный. В противном случае выберите поставщика ресурсов и нажмите Зарегистрировать.

   

Настройка экземпляра Azure Key Vault

Для использования управляемых клиентом ключей с Azure Cosmos DB требуется установка двух свойств в экземпляре Azure Key Vault, который вы планируете использовать для размещения ключей шифрования: Мягкое удаление и Защита от окончательного удаления.

1. Если вы создаете новый экземпляр Azure Key Vault, включите эти свойства во время создания:

   

2. Если вы используете имеющийся экземпляр Azure Key Vault, проверьте, включены ли эти свойства, на портале Azure в разделе Свойства. Если какое-либо из этих свойств не включено, см. разделы "Включение обратимого удаления" и "Включение защиты от очистки" в одной из следующих статей:

   • Как использовать мягкое удаление с помощью PowerShell
   • Как использовать обратимое удаление с Azure CLI

Выбор предпочтительной модели безопасности

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

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

Добавление политики доступа

В этом варианте используйте учетную запись Azure Cosmos DB для создания политики доступа с необходимыми разрешениями.

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

   

2. Выберите + Добавить политику доступа.

3. В раскрывающемся меню Разрешения ключей выберите Получить, Распаковать ключ и Упаковать ключ.

   

4. В разделе Выбор субъекта выберите пункт Не выбрано.

5. Выполните поиск учетной записи Azure Cosmos DB и выберите её (для облегчения поиска можно также выполнить поиск по идентификатору приложения: 00001111-aaaa-2222-bbbb-3333cccc4444 для всех регионов Azure, за исключением регионов Azure для государственных организаций, где идентификатор приложения – 11112222-bbbb-3333-cccc-4444dddd5555).

   Совет

   Это регистрирует удостоверение первой стороны Azure Cosmos DB в политике доступа вашего Azure Key Vault. Если объект Azure Cosmos DB отсутствует в списке, возможно, потребуется повторно зарегистрировать поставщика ресурсов Microsoft.DocumentDB.

6. В нижней части нажмите кнопку Выбрать.

   

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

8. Нажмите Сохранить на экземпляре Key Vault, чтобы сохранить все изменения.

Добавление ролей управления доступом на базе ролевого контроля

1. На портале Azure перейдите к экземпляру Azure Key Vault, который планируется использовать для размещения ключей шифрования. Выберите элемент управления доступом (IAM) в меню слева и выберите "Предоставить доступ к этому ресурсу".

   

   

2. Найдите роль Key Vault Administrator и назначьте ее себе. Это назначение выполняется, сперва найдите имя роли из списка, и затем нажмите на вкладку "Члены". На вкладке выберите параметр "Пользователь, группа или служебный принципал" в переключателе, а затем найдите свою учетную запись Azure. После выбора учетной записи можно назначить роль.

   

3. Затем необходимые разрешения должны быть назначены главному объекту Cosmos DB. Таким же образом, как и последнее назначение ролей, перейдите на страницу назначения, но на этот раз найдите роль "Пользователь шифрования криптослужбы Key Vault" и на вкладке "Члены" найдите субъект Cosmos DB. Чтобы найти субъект, найдите субъект Azure Cosmos DB и выберите его.

   

   Внимание

   В регионе Azure Government идентификатор приложения 11112222-bbbb-3333-cccc-4444dddd5555.

4. Выберите пункт "Проверить и назначить", чтобы назначить роль для Cosmos DB.

Проверка правильности настройки ролей

Затем используйте страницу управления доступом, чтобы убедиться, что все роли настроены правильно.

1. После назначения ролей выберите "Просмотреть доступ к этому ресурсу" на странице контроль доступа IAM, чтобы убедиться, что все задано правильно.

   

2. На странице установите область на "Этот ресурс" и убедитесь, что у вас есть роль администратора Key Vault, а учетная запись Cosmos DB имеет роль пользователя шифрования Key Vault.

Создание нового ключа в Azure Key Vault

Здесь создайте новый ключ с помощью Azure Key Vault и получите уникальный идентификатор.

1. На портале Azure перейдите к экземпляру Azure Key Vault, который планируется использовать для размещения ключей шифрования. Затем в меню слева выберите Ключи.

   

2. Выберите Создать или импортировать, введите имя нового ключа и выберите размер ключа RSA. Для максимальной безопасности рекомендуется использовать как минимум 3072. Щелкните Создать.

   

   Совет

   Кроме того, с помощью Azure CLI можно создать ключ с помощью:

   az keyvault key create \
       --vault-name <name-of-key-vault> \
       --name <name-of-key>
   

   Дополнительные сведения об управлении хранилищем ключей с помощью Azure CLI см. в статье об управлении Azure Key Vault с помощью Azure CLI.

3. После создания ключа выберите только что созданный ключ, а затем его текущую версию.

4. Скопируйте идентификатор ключа, исключая часть после последней косой черты.

   

Создание учетной записи Azure Cosmos DB

Создайте новую учетную запись Azure Cosmos DB с помощью портал Azure или Azure CLI.

# Variable for resource group name
$RESOURCE_GROUP_NAME = "<resource-group-name>"

# Variable for location
$LOCATION = "<azure-region>"

# Variable for account name
$ACCOUNT_NAME = "<globally-unique-account-name>"

# Variable for key URI in the key vault
$KEY_VAULT_KEY_URI="https://<key-vault-name>.vault.azure.net/keys/<key-name>"

$parameters = @{
    ResourceType = "Microsoft.DocumentDb/databaseAccounts"
    ApiVersion = "2019-12-12"
    ResourceGroupName = $RESOURCE_GROUP_NAME
    Location = $LOCATION 
    Name = $ACCOUNT_NAME 
    PropertyObject = @{
        databaseAccountOfferType = "Standard"
        locations = @(
            @{ 
                locationName = $LOCATION 
                failoverPriority = 0
            }
        )
        keyVaultKeyUri = $KEY_VAULT_KEY_URI
    }
}
New-AzResource @parameters  

$parameters = @{
    ResourceGroupName = $RESOURCE_GROUP_NAME
    Name = $ACCOUNT_NAME
    ResourceType = "Microsoft.DocumentDb/databaseAccounts"
}
Get-AzResource @parameters
    | Select-Object -ExpandProperty Properties
    | Select-Object -ExpandProperty keyVaultKeyUri

{
  "$schema": "https://schema.management.azure.com/schemas/2015-01-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "accountName": {
      "type": "string"
    },
    "location": {
      "type": "string"
    },
    "keyVaultKeyUri": {
      "type": "string"
    }
  },
  "resources": [
    {
      "type": "Microsoft.DocumentDB/databaseAccounts",
      "name": "[parameters('accountName')]",
      "apiVersion": "2019-12-12",
      "kind": "GlobalDocumentDB",
      "location": "[parameters('location')]",
      "properties": {
        "locations": [
          {
            "locationName": "[parameters('location')]",
            "failoverPriority": 0,
            "isZoneRedundant": false
          }
        ],
        "databaseAccountOfferType": "Standard",
        "keyVaultKeyUri": "[parameters('keyVaultKeyUri')]"
      }
    }
  ]
}

# Variable for resource group name
$RESOURCE_GROUP_NAME = "<resource-group-name>"

# Variable for location
$LOCATION = "<azure-region>"

# Variable for account name
$ACCOUNT_NAME = "<globally-unique-account-name>"

# Variable for key URI in the key vault
$KEY_VAULT_KEY_URI="https://<key-vault-name>.vault.azure.net/keys/<key-name>"

$parameters = @{
    ResourceGroupName = $RESOURCE_GROUP_NAME
    TemplateFile = "deploy.json"
    accountName = $ACCOUNT_NAME
    location = $LOCATION
    keyVaultKeyUri = $KEY_VAULT_KEY_URI
}
New-AzResourceGroupDeployment @parameters

# Variable for resource group name
resourceGroupName="<resource-group-name>"

# Variable for location
location="<azure-region>"

# Variable for account name
accountName="<globally-unique-account-name>"

# Variable for key URI in the key vault
keyVaultKeyUri="https://<key-vault-name>.vault.azure.net/keys/<key-name>"

az cosmosdb create \
    --resource-group $resourceGroupName \
    --name $accountName \
    --locations regionName=$location \
    --key-uri $keyVaultKeyUri

az cosmosdb show \
    --resource-group $resourceGroupName \
    --name $accountName \
    --query "keyVaultKeyUri"

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

Эта политика доступа гарантирует, что ваши ключи шифрования будут доступны вашей учетной записи Azure Cosmos DB. Политика доступа реализуется путем предоставления доступа к определенному удостоверению Microsoft Entra. Поддерживается два типа идентичностей.

• Для предоставления доступа к службе Azure Cosmos DB можно использовать первичное удостоверение Azure Cosmos DB.
• Для предоставления доступа именно к вашей учетной записи можно использовать управляемое удостоверение учетной записи Azure Cosmos DB.

Использование ключей, управляемых клиентом, с непрерывным резервным копированием

Учетную запись непрерывного резервного копирования можно создать с помощью Azure CLI или шаблона Azure Resource Manager.

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

После создания учетной записи вы можете преобразовать удостоверение в системное управляемое удостоверение.

Кроме того, пользователь может сначала создать системное удостоверение с периодическим режимом резервного копирования, а затем перенести учетную запись в режим непрерывного резервного копирования с помощью этих инструкций . Перенос учетной записи Azure Cosmos DB из периодического в режим непрерывного резервного копирования

# Variables for resource group and account name
resourceGroupName="<resource-group-name>"
accountName="<azure-cosmos-db-account-name>"

# Variable for location
location="<azure-region>"

# Variable for key URI in the key vault
keyVaultKeyUri="https://<key-vault-name>.vault.azure.net/keys/<key-name>"

# Variables for identities
identityId="<identity-resource-id>"

az cosmosdb create \
    --resource-group $resourceGroupName \
    --name $accountName \
    --locations regionName=$location \
    --key-uri $keyVaultKeyUri
    --assign-identity $identityId \
    --default-identity "UserAssignedIdentity=$identityId" \
    --backup-policy-type "Continuous"

{
  "type": "Microsoft.DocumentDB/databaseAccounts",
  "identity": {
    "type": "UserAssigned",
    "userAssignedIdentities": {
      "<identity-resource-id>": {}
    }
  },
  // ...
  "properties": {
    "backupPolicy": {
      "type": "Continuous"
    },
    "defaultIdentity": "UserAssignedIdentity=<identity-resource-id>""keyVaultKeyUri": "<key-vault-key-uri>"
    // ...
  }
}

Восстановление постоянной учетной записи с настроенной управляемой идентичностью

Удостоверение, назначенное пользователем, требуется в запросе на восстановление, так как управляемые удостоверения исходной учетной записи (удостоверения, назначаемые пользователем и системой) не могут быть автоматически перенесены в целевую учетную запись базы данных.

Ключи, управляемые клиентом, и двойное шифрование

Данные, которые хранятся в учетной записи базы данных Azure Cosmos DB при использовании ключей, управляемых клиентом, шифруются дважды:

• Единожды с использованием шифрования по умолчанию, выполненного ключами, управляемыми компанией Microsoft.
• После прохождения дополнительного шифрования с помощью ключей, управляемых клиентом.

Двойное шифрование относится только к основному хранилищу транзакций Azure Cosmos DB. Некоторые функции включают внутреннюю репликацию данных на второй уровень хранилища, где двойное шифрование не предоставляется, даже при использовании ключей, управляемых клиентом. К этим функциям относятся:

• Azure Synapse Link
• Непрерывное резервное копирование с восстановлением до точки во времени

Ротация ключей

Ротация ключа, управляемого клиентом, используемого для учетной записи Azure Cosmos DB, может выполняться двумя способами.

• Создайте новую версию используемого ключа из Azure Key Vault.

  

• Замените ключ, используемый в настоящий момент, на другой, изменив URI ключа в своей учетной записи. В портал Azure перейдите к учетной записи Azure Cosmos DB и выберите шифрование данных в меню слева:

  

  Затем замените универсальный код ресурса (URI) ключа новым ключом, который вы хотите использовать, и нажмите Сохранить.

  

  Вот как выполнить ту же задачу в PowerShell.

  # Variable for resource group name
  $RESOURCE_GROUP_NAME = "<resource-group-name>"
  
  # Variable for account name
  $ACCOUNT_NAME = "<globally-unique-account-name>"
  
  # Variable for new key URI in the key vault
  $NEW_KEY_VAULT_KEY_URI="https://<key-vault-name>.vault.azure.net/keys/<new-key-name>"
  
  $parameters = @{
      ResourceGroupName = $RESOURCE_GROUP_NAME 
      Name = $ACCOUNT_NAME
      ResourceType = "Microsoft.DocumentDb/databaseAccounts"
  }
  $ACCOUNT = Get-AzResource @parameters
  
  $ACCOUNT.Properties.keyVaultKeyUri = $NEW_KEY_VAULT_KEY_URI
  
  $ACCOUNT | Set-AzResource -Force
  

Предыдущий ключ или его версия могут быть отключены после того, как в журнал аудита Azure Key Vault перестанут добавляться сведения о действиях Azure Cosmos DB с ключом или его версией. Если после смены ключей пройдет 24 часа, не выполняйте другие действия с предыдущим ключом или версией ключа.

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

Обработка ошибок

Если с управляемыми клиентом ключами в Azure Cosmos DB возникли какие-либо ошибки, Azure Cosmos DB возвращает сведения об ошибке вместе с кодом подсостояния HTTP в ответе. Код подсостояния HTTP можно использовать для отладки первопричины проблемы. Список поддерживаемых кодов подсостояния HTTP см. в статье Коды состояния HTTP для Azure Cosmos DB.

Часто задаваемые вопросы

Здесь часто задаются вопросы о настройке ключей, управляемых клиентом, в Azure Cosmos DB.

Взимается ли дополнительная плата за включение ключей, управляемых клиентом?

Нет, плата за включение этой функции не взимается.

Как управляемые клиентом ключи влияют на планирование ресурсов?

Единицы запроса, потребляемые операциями базы данных, увеличиваются, отражая дополнительные операции по обработке, необходимые для шифрования и расшифровки данных при использовании управляемых клиентом ключей. Увеличение потребления RU может немного повысить использование выделенной емкости. Используйте эту таблицу для руководства:

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

Все данные, хранящиеся в учетной записи Azure Cosmos DB, шифруются с помощью ключей, управляемых клиентом, за исключением следующих метаданных:

• Имена учетных записей Azure Cosmos DB, баз данных и контейнеров

• имена хранимых процедур;

• пути свойств, объявленные в политиках индексирования;

• значения ключей разделов ваших контейнеров.

Поддерживаются ли управляемые клиентом ключи для существующих учетных записей Azure Cosmos DB?

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

Можно ли использовать ключи, управляемые клиентом, в сочетании с аналитическим хранилищем Azure Cosmos DB?

Да, Azure Synapse Link поддерживает только настройку ключей, управляемых клиентом, с помощью управляемого удостоверения учетной записи Azure Cosmos DB. Перед тем как включить Azure Synapse Link в учетной записи, в политике доступа к Azure Key Vault необходимо использовать управляемое удостоверение учетной записи Azure Cosmos DB. Инструкции по включению управляемого удостоверения и его использованию в политике доступа см. в руководстве по доступу к Azure Key Vault из базы данных Azure Cosmos DB с помощью управляемого удостоверения.

Планируется ли поддержка большей детализации по сравнению с ключами уровня учетной записи?

В настоящее время нет, но рассматривается возможность поддержки ключей уровня контейнера.

Как узнать, включены ли ключи, управляемые клиентом, в учетной записи Azure Cosmos DB?

В портал Azure перейдите к учетной записи Azure Cosmos DB и просмотрите запись шифрования данных в меню слева. Если эта запись существует, ключи, управляемые клиентом, включены в вашей учетной записи:

Вы также можете программно получить сведения об учетной записи Azure Cosmos DB и найти наличие keyVaultKeyUri свойства.

Как ключи, управляемые клиентом, влияют на периодические резервные копирования?

Azure Cosmos DB регулярно выполняет автоматическое резервное копирование данных, хранящихся в вашей учетной записи. В результате этой операции создается резервная копия зашифрованных данных.

Для успешного восстановления периодического резервного копирования необходимы приведенные ниже условия.

• Ключ шифрования, который вы использовали во время резервного копирования, является обязательным и должен быть доступен в Azure Key Vault. Это условие требует, чтобы ключ не отзывался, и та его версия, которая использовалась во время резервного копирования, была по-прежнему активна.
• Прежде чем восстанавливать данные, если вы использовали управляемое удостоверение, назначаемое системой в политике доступа, временно предоставьте доступ удостоверению первой стороны Azure Cosmos DB. Это требование обусловлено тем, что управляемое удостоверение, назначаемое системой, относится к учетной записи и не может быть повторно использовано в целевой учетной записи. После полного восстановления данных в целевой учетной записи вы можете настроить желаемую конфигурацию удостоверения и удалить удостоверение первой стороны из политики доступа Key Vault.

Как ключи, управляемые клиентом, влияют на непрерывное резервное копирование?

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

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

• Добавьте идентификатор, назначенный пользователем, в учетную запись Cosmos DB и предоставьте доступ в соответствии с политикой доступа к хранилищу ключей.
• Установите назначенное пользователем удостоверение в качестве удостоверения по умолчанию с помощью Azure CLI или ARM (Azure Resource Manager).

az cosmosdb update --resource-group MyResourceGroup --name MyAccountName --default-identity UserAssignedIdentity=/subscriptions/MySubscriptionId/resourcegroups/MyResourceGroup/providers/Microsoft.ManagedIdentity/userAssignedIdentities/MyUserAssignedIdentity

Необходимые условия для успешного выполнения восстановления из точки во времени:

• Ключ шифрования, который вы использовали во время резервного копирования, является обязательным и должен быть доступен в Azure Key Vault. Это требование означает, что ключ не отзывается и та его версия, которая использовалась во время резервного копирования, по-прежнему активна.
• Необходимо убедиться, что управляемое удостоверение, назначаемое пользователем, первоначально использовавшееся в исходной учетной записи, по-прежнему объявлено в политике доступа Key Vault.

Как отозвать ключ шифрования?

Отзыв ключа выполняется путем отключения его последней версии.

Кроме того, чтобы отозвать все ключи из хранилища Azure Key Vault, можно удалить политику доступа, предоставленную принципалу Azure Cosmos DB.

Какие операции доступны после отзыва управляемого клиентом ключа?

Единственная операция, возможная после отзыва ключа шифрования, — это удаление учетной записи.

Назначьте новое управляемое удостоверение для восстановленной учетной записи базы данных, чтобы продолжать доступ или восстановить доступ к этой учетной записи базы данных.

Назначаемое пользователем удостоверение связано с указанной учетной записью Cosmos DB. Каждый раз, когда мы назначаем такое удостоверение учетной записи, ARM перенаправляет запрос в управляемые служебные удостоверения для установления этого подключения. В настоящее время мы переносим информацию об удостоверении пользователя из исходной учетной записи базы данных в целевую учетную запись базы данных во время восстановления (как для непрерывного, так и для периодического восстановления резервной копии) в случае использования CMK и назначаемого пользователем удостоверения.

Так как метаданные удостоверения привязаны к учетной записи базы данных-источника, а процесс восстановления не переназначает удостоверения на целевую учетную запись базы данных. Это приведет к тому, что восстановленные учетные записи базы данных будут находиться в плохом состоянии и становятся недоступными после удаления исходной учетной записи и истечения срока продления удостоверения.

Шаги для назначения новой управляемой идентичности:

1. Создайте управляемое удостоверение, назначаемое пользователем.
2. Предоставьте этому удостоверению доступ к ключу KeyVault.
3. Назначьте новое удостоверение этой восстановленной учетной записи базы данных.

Следующие шаги

• Ознакомьтесь с дополнительными сведениями о шифровании данных в Azure Cosmos DB.