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

ПРИМЕНИМО К: Nosql Mongodb Кассандра Гремлин Таблица

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

Уровни шифрования данных клиента

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

Примечание

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

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

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

    Запись

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

    Регистрация поставщика ресурсов Microsoft.DocumentDB

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

Важно!

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

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

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

Включение обратимого удаления и защиты от очистки для нового экземпляра Azure Key Vault

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

Добавление политики доступа к экземпляру Azure Key Vault

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

    Пункт

  2. Нажмите + Добавить политику доступа.

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

    Выбор нужных разрешений

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

  5. Выполните поиск субъекта Azure Cosmos DB и выберите его (для удобства поиск можно выполнить по идентификатору приложения: 57506a73-e302-42a9-b869-6f12d9ec29e9 в регионах Azure для государственных организаций и a232010e-820c-4083-83bb-3ace5fc29d0b во всех остальных регионах Azure). Если субъект Azure Cosmos DB отсутствует в списке, может потребоваться повторная регистрация поставщика ресурсов Microsoft.DocumentDB, как описано в разделе Регистрация поставщика ресурсов в этой статье.

    Примечание

    При этом в политике доступа к Azure Key Vault регистрируется собственное удостоверение Azure Cosmos DB. Чтобы заменить это собственное удостоверение на управляемое удостоверение учетной записи Azure Cosmos DB, см. раздел Использование управляемого удостоверения в политике доступа к Azure Key Vault.

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

    Выбор субъекта Azure Cosmos DB

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

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

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

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

    Запись

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

    Создание ключа

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

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

    Копирование идентификатора ключа

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

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

При создании учетной записи Azure Cosmos DB на портале Azure на шаге Шифрование выберите Управляемый клиентом ключ. В поле URI ключа вставьте URI или идентификатор ключа Azure Key Vault, скопированный на предыдущем шаге.

Настройка параметров CMK на портале Azure

Использование Azure PowerShell

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

  • Передайте скопированный ранее универсальный код ресурса (URI) ключа Azure Key Vault в свойство keyVaultKeyUri в PropertyObject.

  • В качестве версии API используйте 2019-12-12 или более новую.

Важно!

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

$resourceGroupName = "myResourceGroup"
$accountLocation = "West US 2"
$accountName = "mycosmosaccount"

$failoverLocations = @(
    @{ "locationName"="West US 2"; "failoverPriority"=0 }
)

$CosmosDBProperties = @{
    "databaseAccountOfferType"="Standard";
    "locations"=$failoverLocations;
    "keyVaultKeyUri" = "https://<my-vault>.vault.azure.net/keys/<my-key>";
}

New-AzResource -ResourceType "Microsoft.DocumentDb/databaseAccounts" `
    -ApiVersion "2019-12-12" -ResourceGroupName $resourceGroupName `
    -Location $accountLocation -Name $accountName -PropertyObject $CosmosDBProperties

Чтобы после создания учетной записи проверить, включены ли управляемые клиентом ключи, получите URI ключа Azure Key Vault:

Get-AzResource -ResourceGroupName $resourceGroupName -Name $accountName `
    -ResourceType "Microsoft.DocumentDb/databaseAccounts" `
    | Select-Object -ExpandProperty Properties `
    | Select-Object -ExpandProperty keyVaultKeyUri

Использование шаблона Azure Resource Manager

При создании учетной записи Azure Cosmos DB с помощью шаблона azure Resource Manager:

  • Передайте скопированный ранее универсальный код ресурса (URI) ключа Azure Key Vault в свойство keyVaultKeyUri в объекте properties.

  • В качестве версии API используйте 2019-12-12 или более новую.

Важно!

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

{
    "$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')]"
            }
        }
    ]
}

Разверните шаблон, используя следующий скрипт PowerShell:

$resourceGroupName = "myResourceGroup"
$accountName = "mycosmosaccount"
$accountLocation = "West US 2"
$keyVaultKeyUri = "https://<my-vault>.vault.azure.net/keys/<my-key>"

New-AzResourceGroupDeployment `
    -ResourceGroupName $resourceGroupName `
    -TemplateFile "deploy.json" `
    -accountName $accountName `
    -location $accountLocation `
    -keyVaultKeyUri $keyVaultKeyUri

Использование Azure CLI

При создании учетной записи Azure Cosmos DB с помощью Azure CLI передайте универсальный код ресурса (URI) ключа Key Vault Azure, скопированного ранее в параметре --key-uri .

resourceGroupName='myResourceGroup'
accountName='mycosmosaccount'
keyVaultKeyUri = 'https://<my-vault>.vault.azure.net/keys/<my-key>'

az cosmosdb create \
    -n $accountName \
    -g $resourceGroupName \
    --locations regionName='West US 2' failoverPriority=0 isZoneRedundant=False \
    --key-uri $keyVaultKeyUri

Чтобы после создания учетной записи проверить, включены ли управляемые клиентом ключи, получите URI ключа Azure Key Vault:

az cosmosdb show \
    -n $accountName \
    -g $resourceGroupName \
    --query keyVaultKeyUri

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

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

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

Использование управляемого удостоверения, назначаемого системой

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

  1. Если управляемое удостоверение, назначаемое системой, не было настроено во время создания учетной записи, включите назначенное системой управляемое удостоверение в своей учетной записи и копируйте назначенный principalId.

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

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

    • Указать это свойство в шаблоне Azure Resource Manager вашей учетной записи.

      {
          "type": " Microsoft.DocumentDB/databaseAccounts",
          "properties": {
              "defaultIdentity": "SystemAssignedIdentity",
              // ...
          },
          // ...
      }
      
    • Обновить учетную запись с помощью Azure CLI:

          resourceGroupName='myResourceGroup'
          accountName='mycosmosaccount'
      
          az cosmosdb update --resource-group $resourceGroupName --name $accountName --default-identity "SystemAssignedIdentity"
      
  4. При необходимости можно удалить собственное удостоверение Azure Cosmos DB из политики доступа Azure Key Vault.

Использование управляемого удостоверения, назначаемого пользователем

  1. При создании политики доступа в учетной записи Azure Key Vault, как описано выше, используйте Object ID нужного управляемого удостоверения вместо собственного удостоверения Azure Cosmos DB.

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

    • С помощью шаблона Azure Resource Manager:

      {
          "type": "Microsoft.DocumentDB/databaseAccounts",
          "identity": {
              "type": "UserAssigned",
              "userAssignedIdentities": {
                  "<identity-resource-id>": {}
              }
          },
          // ...
          "properties": {
              "defaultIdentity": "UserAssignedIdentity=<identity-resource-id>",
              "keyVaultKeyUri": "<key-vault-key-uri>"
              // ...
          }
      }
      
    • С помощью Azure CLI.

      resourceGroupName='myResourceGroup'
      accountName='mycosmosaccount'
      keyVaultKeyUri = 'https://<my-vault>.vault.azure.net/keys/<my-key>'
      
      az cosmosdb create \
          -n $accountName \
          -g $resourceGroupName \
          --key-uri $keyVaultKeyUri
          --assign-identity <identity-resource-id>
          --default-identity "UserAssignedIdentity=<identity-resource-id>"  
      

Использование CMK с непрерывным резервным копированием

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

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

Создание учетной записи непрерывного резервного копирования с помощью Azure CLI

resourceGroupName='myResourceGroup'
accountName='mycosmosaccount'
keyVaultKeyUri = 'https://<my-vault>.vault.azure.net/keys/<my-key>'

az cosmosdb create \
    -n $accountName \
    -g $resourceGroupName \
    --key-uri $keyVaultKeyUri \
    --locations regionName=<Location> \
    --assign-identity <identity-resource-id> \
    --default-identity "UserAssignedIdentity=<identity-resource-id>" \
    --backup-policy-type Continuous 

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

При создании учетной записи Azure Cosmos DB с помощью шаблона azure Resource Manager:

  • Передайте скопированный ранее универсальный код ресурса (URI) ключа Azure Key Vault в свойство keyVaultKeyUri в объекте properties.
  • В качестве версии API используйте 2021-11-15 или выше.

Важно!

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

 {
    "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 при использовании ключей, управляемых клиентом, шифруются дважды:

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

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

Смена ключей

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

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

    Снимок экрана с пунктом

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

    Снимок экрана с пунктом меню

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

    Снимок экрана с пунктом

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

    $resourceGroupName = "myResourceGroup"
    $accountName = "mycosmosaccount"
    $newKeyUri = "https://<my-vault>.vault.azure.net/keys/<my-new-key>"
    
    $account = Get-AzResource -ResourceGroupName $resourceGroupName -Name $accountName `
        -ResourceType "Microsoft.DocumentDb/databaseAccounts"
    
    $account.Properties.keyVaultKeyUri = $newKeyUri
    
    $account | Set-AzResource -Force
    

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

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

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

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

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

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

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

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

Operation type (Тип операции) Увеличение количества единиц запроса
Точечные операции чтения (получение элементов по их идентификаторам) +5 % на операцию
Любая операция записи +6 % на операцию
Приблизительно + 0,06 ЕЗ на индексированное свойство
Запросы, канал изменений для чтения или канал с конфликтами +15 % на операцию

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

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

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

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

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

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

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

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

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

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

Запись меню шифрования данных

Вы также можете программным способом получить сведения об учетной записи Azure Cosmos DB и найти наличие keyVaultKeyUri свойства . Сведения о том, как это можно сделать в PowerShell и с помощью Azure CLI, см. выше.

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

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

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

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

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

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

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

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

Важно!

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

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

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

Отключение версии ключа

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

Удаление политики доступа для субъекта-Azure Cosmos DB

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

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

Дальнейшие действия