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

Примечание

Поиск с использованием ИИ Azure доступна через портал Azure, REST API и Azure SDKs. Он также лежит в основе Foundry IQ — управляемого слоя знаний, который преобразует корпоративный контент в многократно используемые базы знаний с учетом разрешений доступа для агентов на портале Microsoft Foundry.

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

Вращение ключей по определяемому клиентом расписанию
Отключение или отмена ключей для блокировки доступа к зашифрованным содержимым (кэшированные ключи могут сохраняться до 60 минут).
Аудит использования ключа с помощью ведения журнала Azure Key Vault

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

Azure Key Vault
Azure Key Vault управляемый HSM (аппаратный модуль безопасности). Управляемый модуль HSM в Azure Key Vault — это сертифицированный FIPS 140-2 уровня 3 HSM. Чтобы перейти с Azure Key Vault на HSM, обновите ключи и выберите управляемый HSM для хранения.

В этой статье объясняется, как настроить CMK для дополнительной защиты зашифрованных данных в Поиск с использованием ИИ Azure.

Важно

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

Необходимые условия

Поиск с использованием ИИ Azure на платном уровне (базовом или более высоком, в любом регионе).
Azure Key Vault и хранилище ключей с поддержкой soft-delete и защиты от очистки. Или Azure Key Vault Управляемый HSM. Этот ресурс может находиться в любой подписке и в другом клиенте. В этих инструкциях предполагается единственное присутствие арендатора. Сведения о кросс-тенантной настройке см. в разделе Настройка ключей, управляемых клиентом в разных тенантах.
Если вы планируете настроить CMK уровня обслуживания, используйте REST API управления поиском версии 2026-03-01-preview или более поздней версии. Чтобы проверить, наследует ли объект ключ уровня обслуживания, используйте API плоскости данных версии 2026-05-01-preview или более поздней версии.
Возможность настройки разрешений для доступа к ключам и назначения ролей. Чтобы создать ключи, необходимо быть Офицером по шифрованию Key Vault в Azure Key Vault или Офицером по шифрованию Managed HSM в управляемом HSM Azure Key Vault.

Чтобы назначать роли, необходимо быть подписчиком с доступом владельца, администратора доступа пользователей, администратора управления доступом на основе ролей или иметь назначение в пользовательской роли с разрешениями Microsoft.Authorization/roleAssignments/write.

Настройка CMK для объектов Поиск с использованием ИИ Azure

Объекты с зашифрованными данными, которые можно настроить с помощью ключа, управляемого клиентом (CMK), включают индексы, списки синонимов, индексаторы, источники данных, векторизаторы и наборы навыков. Шифрование является вычислительным образом дорогостоящим для расшифровки, поэтому шифруется только конфиденциальное содержимое.

Шифрование выполняется поверх:

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

Добавление управляемого клиентом ключа к объекту должно произойти при создании объекта. Важно помнить:

Невозможно ретроактивно добавить CMK в существующий объект. Если вы хотите добавить ключ, управляемый клиентом, в существующий объект, необходимо удалить и повторно создать этот объект с включенным шифрованием.
После настройки CMK шифрование происходит каждый раз, когда служба записывает данные, включая как данные в состоянии покоя (долгосрочное хранение), так и временные закэшированные данные (краткосрочное хранение). Для таких объектов, как источники данных, индексаторы и наборы навыков, определение объекта шифруется. Для индексов сами индексированные документы (а не только схема индекса) шифруются.
Хотя вы не можете добавить шифрование в существующий объект, вы можете изменить все части определения шифрования объекта, включая переход на другое хранилище ключей или хранилище HSM, если ресурс находится в одном клиенте.
Шифрование с помощью CMK необратимо. Вы можете повернуть ключи и изменить конфигурацию CMK, но шифрование индекса длится в течение всего времени существования индекса. После шифрования с помощью CMK индекс доступен только в том случае, если служба поиска имеет доступ к ключу. Если вы отмените доступ к ключу, удалив или изменив назначение ролей, индекс недоступен, и служба не может быть масштабирована до тех пор, пока индекс не будет удален или доступ к ключу восстановлен. При удалении или смене ключей последний ключ кэшируется до 60 минут.
Если вам требуется CMK для вашей службы поиска, задайте политику принудительного применения.
Принудительное применение CMK с помощью Политика Azure и конфигурации CMK уровня обслуживания (которая по-прежнему находится в предварительной версии) являются независимыми параметрами. В зависимости от ваших потребностей можно использовать любой из этих вариантов. Конфигурация CMK уровня обслуживания применяет ключ по умолчанию к новым объектам, а Политика Azure обеспечивает контроль, чтобы все объекты соответствовали вашим требованиям к шифрованию. Если вы включите политику принудительного применения CMK без ключа уровня обслуживания, все объекты с поддержкой CMK должны указывать собственный ключ шифрования во время создания. Запросы на создание объектов, которые пропускают конфигурацию CMK, завершаются неудачей.

Активировать CMK на уровне сервиса для новых объектов по умолчанию (предварительная версия)

Примечание

Эта функция сейчас доступна в предварительной версии. Эта предварительная версия предоставляется без соглашения об уровне обслуживания и не рекомендуется для рабочих задач в производственной среде. Некоторые функции могут не поддерживаться или могут иметь ограниченные возможности. Дополнительные сведения см. в разделе Supplemental Terms of Use for Microsoft Azure Previews.

Начиная с выпуска 2026-03-01-preview, вы можете настроить управляемый клиентом ключ на уровне обслуживания в самой службе Поиск с использованием ИИ Azure. Эта функция позволяет настроить ключ один раз и применить его ко всем вновь созданным объектам по умолчанию. Эта защита обеспечивает безопасность конфиденциальных данных в службе поиска с помощью ключа, который вы управляете, без необходимости указывать ключевые сведения при каждом создании объекта. В api предварительной версии уровня данных 2026-05-01-preview свойство isServiceLevelKey помогает определить, encryptionKey наследует ли объект ключ уровня обслуживания или использует явный ключ уровня объекта.

Включение CMK на уровне сервиса означает следующее:

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

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

Выберите CMK на уровне службы или на уровне объекта

Используйте CMK уровня обслуживания по умолчанию, чтобы применить один ключ ко всем объектам. Ключ настраивается один раз и новые объекты наследуют эту защиту автоматически.

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

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

Шаг 1. Создание ключа шифрования

Используйте Azure Key Vault или Azure Key Vault управляемый модуль HSM для создания ключа. шифрование Поиск с использованием ИИ Azure поддерживает ключи RSA размером 2048, 3072 и 4096. Дополнительные сведения о поддерживаемых типах ключей см. в разделе "Сведения о ключах".

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

Обязательные операции: оболочка, распаковка, шифрование и расшифровка.

Azure Key Vault
Управляемый аппаратный модуль безопасности (HSM)

Вы можете создать хранилище ключей с помощью портала Azure, Azure CLI или Azure PowerShell.

Перейдите в хранилище ключей на портале Azure.
Выберитеключи> слева и нажмите кнопку "Создать или импортировать".
В области "Создание ключа" в списке параметров выберите "Создать ", чтобы создать новый ключ.
Введите имя ключа и примите значения по умолчанию для других свойств ключей.
При необходимости установите политику ротации ключей для включения автоматической ротации.
Нажмите кнопку "Создать", чтобы начать развертывание.
После создания ключа получите его идентификатор ключа. Выберите ключ, выберите текущую версию и скопируйте идентификатор ключа. Он состоит из URI значения ключа, имени ключа и версии ключа. Вам нужен идентификатор, чтобы определить зашифрованный индекс в Поиск с использованием ИИ Azure. Помните, что необходимые операции: оболочка, распаковка, шифрование и расшифровка.

Шаг 2. Создание субъекта безопасности

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

Используйте управляемое удостоверение и роли. Вы можете использовать управляемое системой удостоверение или управляемое пользователем удостоверение. Управляемое удостоверение позволяет службе поиска проходить проверку подлинности через Microsoft Entra ID без хранения учетных данных (ApplicationID или ApplicationSecret) в коде. Жизненный цикл управляемого удостоверения этого типа привязан к жизненному циклу службы поиска, который может иметь только одно управляемое удостоверение, назначаемое системой. Для получения дополнительной информации о том, как работают управляемые удостоверения, см. раздел Что такое управляемые удостоверения для ресурсов Azure.

Активируйте управляемую идентификацию, назначаемую системой, для вашего поискового сервиса. Это операция с двумя щелчками: включение и сохранение.

Шаг 3. Предоставление разрешений

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

Рекомендуется использовать управление доступом на основе ролей вместо модели разрешений политики доступа. Для получения дополнительных сведений или действий по миграции начните с Azure управления доступом на основе ролей (Azure RBAC) и политик доступа (устаревшая версия).

Перейдите в хранилище ключей на портале Azure.
Выберите элемент управления доступом (IAM) и выберите "Добавить назначение ролей".
Выберите роль:
- В Azure Key Vault выберите пользователь шифрования службы Key Vault.
- На управляемом HSM выберите пользователя шифрования службы Managed HSM Crypto Service Encryption.
Выберите управляемые удостоверения, выберите участников и выберите управляемое удостоверение службы поиска. Если вы тестируете локально, назначьте эту роль себе тоже.
Выберите "Рецензирование и назначение".

Подождите несколько минут, пока назначение роли станет операционным.

Брандмауэр Key Vault и доступ к виртуальной сети для CMK

Поиск с использованием ИИ Azure должен иметь доступ к ключу шифрования в Azure Key Vault.

Если в хранилище ключей используется брандмауэр или ограничения виртуальной сети, настройте один из следующих вариантов:

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

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

Если брандмауэр блокирует доступ и обход доверенных служб не включен, Поиск с использованием ИИ Azure не удается получить ключ и операции, зависящие от CMK, завершаются сбоем.

Шаг 4. Добавление сведений ключа шифрования в объекты Поиск с использованием ИИ Azure

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

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

Уровень обслуживания: путем настройки ключа, управляемого клиентом на уровне обслуживания, этот ключ применяется по умолчанию ко всем вновь созданным объектам поиска. Он не применяется к существующим объектам поиска.

Уровень объекта: при создании нового объекта можно также определить новый уникальный ключ на уровне объекта. Это определение ключа на уровне объекта переопределяет ключ на уровне службы по умолчанию.

Предостережение

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

Чтобы настроить CMK на объекте, используйте портал Azure, Search Service REST API или Azure SDK.

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

Индексы
Источники данных
Индексаторы

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

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

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

Вызовите API создания, чтобы указать свойство encryptionKey :
Вставьте конструкцию encryptionKey в определение объекта. Это свойство является свойством первого уровня на том же уровне, что и имя и описание. Если вы используете одно и то же хранилище, ключ и версию, можно вставить конструкцию encryptionKey в каждое определение объекта.

Если ваш идентификатор ключа — https://contoso-keyvault.vault.azure.net/keys/contoso-cmk/aaaaaaaa-0b0b-1c1c-2d2d-333333333333, то URI — https://contoso-keyvault.vault.azure.net, имя ключа — contoso-cmk, а версия — aaaaaaaa-0b0b-1c1c-2d2d-333333333333.
```
{
  "encryptionKey": {
    "keyVaultUri": "<YOUR-KEY-VAULT-URI>",
    "keyVaultKeyName": "<YOUR-ENCRYPTION-KEY-NAME>",
    "keyVaultKeyVersion": "<YOUR-ENCRYPTION-KEY-VERSION>",
    "identity" : { 
        "@odata.type": "#Microsoft.Azure.Search.DataUserAssignedIdentity",
        "userAssignedIdentity" : "/subscriptions/<your-subscription-ID>/resourceGroups/<your-resource-group-name>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<your-managed-identity-name>"
    }
  }
}
```
В первом примере показан ключ шифрования для службы поиска, которая подключается с помощью управляемого удостоверения:
```
{
  "encryptionKey": {
    "keyVaultUri": "<YOUR-KEY-VAULT-URI>",
    "keyVaultKeyName": "<YOUR-ENCRYPTION-KEY-NAME>",
    "keyVaultKeyVersion": "<YOUR-ENCRYPTION-KEY-VERSION>"
  }
}
```
Второй пример включает accessCredentials, необходимый, если вы зарегистрировали приложение в Microsoft Entra ID:
```
{
  "encryptionKey": {
    "keyVaultUri": "<YOUR-KEY-VAULT-URI>",
    "keyVaultKeyName": "<YOUR-ENCRYPTION-KEY-NAME>",
    "keyVaultKeyVersion": "<YOUR-ENCRYPTION-KEY-VERSION>",
    "accessCredentials": {
      "applicationId": "<YOUR-APPLICATION-ID>",
      "applicationSecret": "<YOUR-APPLICATION-SECRET>"
    }
  }
}
```
Убедитесь, что ключ шифрования существует путем выдачи GET для объекта.
Убедитесь, что объект работает, выполняя задачу, например запрос индекса, зашифрованного.

После создания зашифрованного объекта в службе поиска его можно использовать как любой другой объект своего типа. Шифрование прозрачно для пользователя и разработчика.

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

Конфигурация CMK для объектов поиска поддерживается в пакетах Azure SDK, включая Azure SDK для .NET, Azure SDK для Java, Azure SDK для JavaScript и Azure SDK для Python.

В следующем примере показано представление на Python директивы encryptionKey в определении объекта. Это же определение применяется к индексам, источникам данных, наборам навыков, индексаторам и сопоставлениям синонимов. Чтобы попробовать этот пример в службе поиска и хранилище ключей, скачайте записную книжку из azure-search-python-samples.

Установите некоторые пакеты.

! pip install python-dotenv
! pip install azure-core
! pip install azure-search-documents==11.5.1
! pip install azure-identity

Создайте индекс с ключом шифрования.

from azure.search.documents.indexes import SearchIndexClient
from azure.search.documents.indexes.models import (
  SimpleField,
  SearchFieldDataType,
  SearchableField,
  SearchIndex,
  SearchResourceEncryptionKey,
)
from azure.identity import DefaultAzureCredential

endpoint = "<PUT YOUR AZURE SEARCH SERVICE ENDPOINT HERE>"
credential = DefaultAzureCredential()

index_name = "test-cmk-index"
index_client = SearchIndexClient(endpoint=AZURE_SEARCH_SERVICE, credential=credential)
fields = [
  SimpleField(name="Id", type=SearchFieldDataType.String, key=True),
  SearchableField(name="Description", type=SearchFieldDataType.String),
]

encryption_key = SearchResourceEncryptionKey()
encryption_key.vault_uri = "<PUT YOUR KEY VAULT URI HERE>"
encryption_key.key_name = "<PUT YOUR KEY VAULT KEY NAME HERE>"
encryption_key.key_version = "<PUT YOUR ALPHANUMERIC KEY VERSION HERE>"

index = SearchIndex(name=index_name, fields=fields, encryption_key=encryption_key)
result = index_client.create_or_update_index(index)
print(f"{result.name} created")

Получите определение индекса для проверки наличия конфигурации ключа шифрования.

index_name = "test-cmk-index"
index_client = SearchIndexClient(endpoint=AZURE_SEARCH_SERVICE, credential=credential)  

result = index_client.get_index(index_name)  
print(f"{result}")

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

from azure.search.documents import SearchClient

# Create a documents payload
documents = [
    {
    "@search.action": "upload",
    "Id": "1",
    "Description": "The hotel is ideally located on the main commercial artery of the city in the heart of New York. A few minutes away is Time's Square and the historic centre of the city, as well as other places of interest that make New York one of America's most attractive and cosmopolitan cities."
    },
    {
    "@search.action": "upload",
    "Id": "2",
    "Description": "The hotel is situated in a  nineteenth century plaza, which has been expanded and renovated to the highest architectural standards to create a modern, functional and first-class hotel in which art and unique historical elements coexist with the most modern comforts."
    },
    {
    "@search.action": "upload",
    "Id": "3",
    "Description": "The hotel stands out for its gastronomic excellence under the management of William Dough, who advises on and oversees all of the Hotel's restaurant services."
    },
    {
    "@search.action": "upload",
    "Id": "4",
    "Description": "The hotel is located in the heart of the historic center of Sublime in an extremely vibrant and lively area within short walking distance to the sites and landmarks of the city and is surrounded by the extraordinary beauty of churches, buildings, shops and monuments. Sublime Palace is part of a lovingly restored 1800 palace."
    }
]

search_client = SearchClient(endpoint=AZURE_SEARCH_SERVICE, index_name=index_name, credential=credential)
try:
    result = search_client.upload_documents(documents=documents)
    print("Upload of new document succeeded: {}".format(result[0].succeeded))
except Exception as ex:
    print (ex)

    index_client = SearchClient(endpoint=AZURE_SEARCH_SERVICE, credential=credential)

Выполните запрос, чтобы убедиться, что индекс работает.

from azure.search.documents import SearchClient

query = "historic"  

search_client = SearchClient(endpoint=AZURE_SEARCH_SERVICE, credential=credential, index_name=index_name)

results = search_client.search(  
    query_type='simple',
    search_text=query, 
    select=["Id", "Description"],
    include_total_count=True
    )

for result in results:  
    print(f"Score: {result['@search.score']}")
    print(f"Id: {result['Id']}")
    print(f"Description: {result['Description']}")

Выходные данные запроса должны создавать результаты, аналогичные следующему примеру.

Score: 0.6130029
Id: 4
Description: The hotel is located in the heart of the historic center of Sublime in an extremely vibrant and lively area within short walking distance to the sites and landmarks of the city and is surrounded by the extraordinary beauty of churches, buildings, shops and monuments. Sublime Palace is part of a lovingly restored 1800 palace.
Score: 0.26286605
Id: 1
Description: The hotel is ideally located on the main commercial artery of the city in the heart of New York. A few minutes away is Time's Square and the historic centre of the city, as well as other places of interest that make New York one of America's most attractive and cosmopolitan cities.

Так как зашифрованное содержимое расшифровывается до обновления данных или запросов, вы не увидите визуальные доказательства шифрования. Чтобы проверить работу шифрования, проверьте журналы ресурсов.

Важно

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

Настройка CMK на уровне обслуживания (предварительная версия)

Чтобы включить конфигурацию CMK на уровне службы, используйте REST API управления поиском или пакет Azure SDK, обновленный для поддержки REST API управления поиском версии 2026-03-01-preview или более поздней. Портал Azure пока не поддерживает эту функцию. Если включить CMK на уровне обслуживания, вы не добавляете шифрование к существующим объектам, но по умолчанию применяете один и тот же ключ ко всем вновь созданным объектам в службе, если только не указан другой ключ уровня объекта для переопределения по умолчанию уровня обслуживания.

В настоящее время портал Azure не поддерживает шифрование на уровне обслуживания. Используйте REST API напрямую.

Чтобы настроить шифрование с помощью CMK на уровне службы поиска, используйте службы — создание или обновление с PATCH целью обновления существующей службы поиска или PUT создания новой. Версия API должна быть 2026-03-01-preview или более поздней для поддержки конфигурации уровня обслуживания.

В этом примере обязательно замените {{subscription-id}} на ваш идентификатор подписки, {{resource-group}} на имя группы ресурсов, {{search-service}} на имя службы поиска и {{token}} на маркер доступа соответственно. Определение ключа использует ту же схему, что и CMK на уровне объекта, и поддерживаются все три варианта удостоверения (назначаемое системой управляемое удостоверение, назначаемое пользователем управляемое удостоверение или зарегистрированное приложение).

PATCH https://management.azure.com/subscriptions/{{subscription-id}}/resourceGroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service}}?api-version=2026-03-01-preview
Authorization: Bearer {{token}}
Content-Type: application/json

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

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

{
  "encryptionWithCmk": {
    "serviceLevelEncryptionKey": {
      "keyVaultUri": "<YOUR-KEY-VAULT-URI>",
      "keyVaultKeyName": "<YOUR-ENCRYPTION-KEY-NAME>",
      "keyVaultKeyVersion": "<YOUR-ENCRYPTION-KEY-VERSION>"
    }
  }
}

Пример использования управляемого пользователем удостоверения:

{
  "encryptionWithCmk": {
    "serviceLevelEncryptionKey": {
      "keyVaultUri": "<YOUR-KEY-VAULT-URI>",
      "keyVaultKeyName": "<YOUR-ENCRYPTION-KEY-NAME>",
      "keyVaultKeyVersion": "<YOUR-ENCRYPTION-KEY-VERSION>",
      "identity": {
        "@odata.type": "#Microsoft.Azure.Search.DataUserAssignedIdentity",
        "userAssignedIdentity": "/subscriptions/<your-subscription-ID>/resourceGroups/<your-resource-group-name>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<your-managed-identity-name>"
      }
    }
  }
}

Пример использования идентификатора приложения:

{
  "encryptionWithCmk": {
    "serviceLevelEncryptionKey": {
          "keyVaultUri": "<YOUR-KEY-VAULT-URI>",
          "keyVaultKeyName": "<YOUR-ENCRYPTION-KEY-NAME>",
          "keyVaultKeyVersion": "<YOUR-ENCRYPTION-KEY-VERSION>",
          "accessCredentials": {
                  "applicationId": "<YOUR-APPLICATION-ID>",
                  "applicationSecret": "<YOUR-APPLICATION-SECRET>"
      }       
    }
  }
}

Проверьте, наследует ли объект поиска CMK на уровне службы

Чтобы проверить, использует ли объект поиска ключ, управляемый клиентом, настроенный на уровне обслуживания как стандартный или уникальный управляемый клиентом ключ, настроенный на уровне объекта, проверьте наследуемое состояние шифрования с помощью isServiceLevelKey свойства.

В настоящее время портал Azure не поддерживает шифрование на уровне обслуживания. Используйте REST API напрямую.

В версии 2026-05-01-previewAPI плоскости данных используйте вызов объекта GET для проверки encryptionKey.isServiceLevelKey.

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

GET https://{{search-service}}.search.windows.net/indexes/{{index-name}}?api-version=2026-05-01-preview
api-key: {{admin-api-key}}

{
  "name": "hotels-cmk",
  "fields": [
    {
      "name": "id",
      "type": "Edm.String",
      "key": true,
      "searchable": false,
      "retrievable": true
    }
  ],
  "encryptionKey": {
    "keyVaultUri": "<YOUR-KEY-VAULT-URI>",
    "keyVaultKeyName": "<YOUR-ENCRYPTION-KEY-NAME>",
    "keyVaultKeyVersion": "<YOUR-ENCRYPTION-KEY-VERSION>",
    "isServiceLevelKey": true
  }
}

Если isServiceLevelKey это trueтак, объект наследует ключ уровня обслуживания и не имеет явного переопределения на уровне объекта.

Чтобы отделить жизненный цикл для определенного объекта, задайте явный ключ уровня объекта и задайте значение isServiceLevelKeyfalse в запросе на создание или обновление.

PUT https://{{search-service}}.search.windows.net/indexes/{{index-name}}?api-version=2026-05-01-preview
api-key: {{admin-api-key}}
Content-Type: application/json

{
  "name": "regulated-index",
  "fields": [
    {
      "name": "id",
      "type": "Edm.String",
      "key": true,
      "searchable": false,
      "retrievable": true
    }
  ],
  "encryptionKey": {
    "keyVaultUri": "<YOUR-KEY-VAULT-URI>",
    "keyVaultKeyName": "<YOUR-ENCRYPTION-KEY-NAME>",
    "keyVaultKeyVersion": "<YOUR-ENCRYPTION-KEY-VERSION>",
    "isServiceLevelKey": false
  }
}

Благодаря этому переопределению жизненный цикл ключа на уровне объекта отвязывается от значения по умолчанию на уровне службы. Ключ уровня объекта можно повернуть независимо, не изменяя ключ уровня обслуживания, используемый другими объектами.

Чтобы вернуть объект к наследованию CMK на уровне службы, обновите объект, установив для параметра isServiceLevelKey значение true и не указывая сведения о ключе уровня объекта.

PUT https://{{search-service}}.search.windows.net/indexes/{{index-name}}?api-version=2026-05-01-preview
api-key: {{admin-api-key}}
Content-Type: application/json

{
  "name": "regulated-index",
  "fields": [
    {
      "name": "id",
      "type": "Edm.String",
      "key": true,
      "searchable": false,
      "retrievable": true
    }
  ],
  "encryptionKey": {
    "isServiceLevelKey": true
  }
}

После этого обновления объект поиска снова наследует ключ уровня обслуживания. Если вы указываете явный ключ на уровне объекта, устанавливать значение isServiceLevelKey равным false необязательно, поскольку явное определение ключа переопределяет наследование на уровне службы.

Шаг 5. Тестирование шифрования

Чтобы проверить работу шифрования, отмените ключ шифрования, запросите индекс (он должен быть неиспользуемым), а затем восстановите ключ шифрования.

Используйте портал Azure для этой задачи. Убедитесь, что у вас есть назначение роли, которое предоставляет доступ на чтение к ключу.

На странице Azure Key Vault выберите Objects>Keys.
Выберите созданный ключ и нажмите кнопку "Удалить".
На странице Поиск с использованием ИИ Azure выберите Search management>Indexes.
Выберите индекс и используйте обозреватель поиска для выполнения запроса. Вы должны получить ошибку.
Вернитесь на страницу Azure Key Vault Objects>Keys.
Выберите "Управление удаленными ключами".
Выберите ключ и нажмите кнопку "Восстановить".
Вернитесь к индексу в Поиск с использованием ИИ Azure и повторно запустите запрос. Результаты поиска должны отображаться. Если вы не видите немедленные результаты, подождите минуту и повторите попытку.

Настройка политики для обеспечения соблюдения требований CMK

Политики Azure помогают применять организационные стандарты и оценивать соответствие в масштабах организации. Поиск с использованием ИИ Azure имеет две дополнительные встроенные политики, связанные с CMK. Эти политики применяются к новым и существующим службам поиска.

Эффект Описание

AuditIfNotExists Проверяет соответствие политике: у объектов определен ключ, управляемый клиентом, и содержимое зашифровано. Этот эффект применяется к существующим службам с содержимым. Он вычисляется каждый раз при создании или обновлении объекта или в соответствии с расписанием оценки. Подробнее...

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

Эффект	Описание
AuditIfNotExists	Проверяет соответствие политике: у объектов определен ключ, управляемый клиентом, и содержимое зашифровано. Этот эффект применяется к существующим службам с содержимым. Он вычисляется каждый раз при создании или обновлении объекта или в соответствии с расписанием оценки. Подробнее...
Отрицать	Проверяет применение политик: установлено ли в службе поиска SearchEncryptionWithCmk`Enabled`. Этот эффект применяется только к новым службам, которые должны быть созданы с включенным шифрованием. Существующие службы остаются операционными, но их нельзя обновить, если только вы не исправите эту службу. Ни один из инструментов, используемых для предоставления услуг, не раскрывает это свойство, поэтому следует учитывать, что установка политики ограничивает вас только программной настройкой.

Назначить политику

На портале Azure перейдите к встроенной политике и выберите Assign.
- AuditIfExists
- Отрицать
Ниже приведен пример политики AuditIfExists на портале Azure:
Задайте область политики , выбрав подписку и группу ресурсов. Исключите все службы поиска, для которых политика не должна применяться.
Примите или измените значения по умолчанию. Выберите "Просмотр и создание", а затем нажмите кнопку "Создать".

Включение принудительного применения политик CMK

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

Создание соответствующей службы поиска

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

Ни портал Azure, ни средства командной строки (Azure CLI и Azure PowerShell) изначально не предоставляют это свойство, но вы можете использовать Management REST API для подготовки службы поиска с определением политики CMK.

REST API управления

В этом примере из Управление службой Поиск с использованием ИИ Azure с использованием REST API, изменённое для включения свойства SearchEncryptionWithCmk.

### Create a search service (provide an existing resource group)
@resource-group = my-rg
@search-service-name = my-search
PUT https://management.azure.com/subscriptions/{{subscriptionId}}/resourceGroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}?api-version=2025-05-01 HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

    {
        "location": "North Central US",
        "sku": {
            "name": "basic"
        },
        "properties": {
            "replicaCount": 1,
            "partitionCount": 1,
            "hostingMode": "default",
            "encryptionWithCmk": {
                "enforcement": "Enabled"
        }
      }
    }

Обновление существующей службы поиска

Для существующих служб поиска, которые теперь не соответствуют требованиям, исправьте их с помощью команды Services — Update API или Azure CLI az resource update. Исправление служб восстанавливает возможность обновления свойств службы поиска.

REST API управления
Azure CLI

PATCH https://management.azure.com/subscriptions/<your-subscription-Id>/resourceGroups/<your-resource-group-name>/providers/Microsoft.Search/searchServices/<your-search-service-name>?api-version=2025-05-01

{
  "properties": {
      "encryptionWithCmk": {
          "enforcement": "Enabled"
      }
  }
}

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

az resource update --name SEARCH-SERVICE-PLACEHOLDER --resource-group RESOURCE-GROUP-PLACEHOLDER --resource-type searchServices --namespace Microsoft.Search --set properties.encryptionWithCmk.enforcement=Enabled

Ответ должен содержать следующее утверждение:

"encryptionWithCmk": {
      "encryptionComplianceStatus": "NonCompliant",
      "enforcement": "Enabled"
    }
...

"Несоответствующий" означает, что служба поиска имеет существующие объекты, которые не шифруются cmK. Чтобы обеспечить соответствие требованиям, повторно создайте каждый объект, указав ключ шифрования.

Ротация или обновление ключей шифрования

Используйте следующие инструкции, чтобы повернуть ключи или перейти от Azure Key Vault к аппаратной модели безопасности (HSM).

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

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

Если вы настроили CMK на уровне обслуживания, смена ключа уровня обслуживания применяется к вновь созданным объектам. Объекты, которые уже наследуют предыдущий ключ уровня обслуживания, автоматически выбирают новый ключ, поэтому их не нужно обновлять. Однако если у вас есть объекты, настроенные с помощью ключа уровня объекта, который также требуется повернуть, необходимо обновить эти объекты, чтобы использовать новый ключ.

Ключи кэшируются в течение 60 минут. Помните это при тестировании и смещении ключей.

Определите ключ, используемый картой индексов или синонимов.
Создайте новый ключ в хранилище ключей, но оставьте исходный ключ доступным. На этом шаге можно перейти из хранилища ключей в HSM.
Обновите свойства encryptionKey в индексе или карте синонимов, чтобы использовать новые значения. Можно обновить только объекты, созданные с помощью этого свойства, чтобы использовать другое значение.
Отключите или удалите предыдущий ключ в хранилище ключей. Мониторинг доступа к ключу для проверки использования нового ключа.

По соображениям производительности служба поиска кэширует ключ до нескольких часов. Если вы отключите или удалите ключ без предоставления нового, запросы продолжают работать на временной основе до истечения срока действия кэша. Однако после того как служба поиска больше не сможет расшифровать содержимое, вы получите следующее сообщение: "Access forbidden. The query key used might have been revoked - please retry."

советы по Key Vault

Если вы не знакомы с Azure Key Vault, ознакомьтесь с этим кратким руководством, чтобы узнать о основных задачах: Set и получить секрет из Azure Key Vault с помощью PowerShell.
Используйте столько хранилищ ключей, сколько вам нужно. Управляемые ключи могут находиться в разных хранилищах ключей. Служба поиска может иметь несколько зашифрованных объектов, каждый из которых зашифрован с помощью другого ключа шифрования, управляемого клиентом, хранящегося в разных хранилищах ключей.
Используйте тот же клиент Azure, чтобы получить управляемый ключ с помощью назначений ролей и подключиться через системное или управляемое пользователем удостоверение. Дополнительные сведения о создании клиента см. в разделе "Настройка нового клиента".
Если ваше Azure Key Vault защищено брандмауэром, обязательно включите параметр Разрешить доверенным службам Microsoft обходить этот брандмауэр, чтобы Поиск с использованием ИИ Azure могла получить доступ к ключу.
Включите защиту от окончательной очистки и мягкое удаление в хранилище ключей. Из-за характера шифрования с помощью ключей, управляемых клиентом, никто не сможет получить данные, если ключ Azure Key Vault удален. Чтобы предотвратить потерю данных, вызванную случайным удалением ключей Key Vault, необходимо включить защиту обратимого удаления и очистки в key vault. Мягкое удаление включено по умолчанию, поэтому проблемы возникнут, только если вы намеренно его отключите. Защита очистки не включена по умолчанию, но требуется для шифрования с помощью CMK в Поиск с использованием ИИ Azure.
Включите ведение журнала в хранилище ключей, чтобы отслеживать использование ключей.
Включите авторотацию ключей или следуйте строгим процедурам во время обычной смены ключей хранилища ключей и секретов приложений и регистрации. Всегда обновляйте все зашифрованное содержимое , чтобы использовать новые секреты и ключи перед удалением старых. Если вы пропустите этот шаг, содержимое не может быть расшифровано.

Работа с зашифрованным содержимым

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

Рекомендуется включить ведение журнала в рамках конфигурации хранилища ключей.

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

FAQs

Можно ли изменить объект поиска между ключом, управляемым клиентом, определенным на уровне обслуживания, и ключом, управляемым клиентом, определенным на уровне объекта?

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

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

Если вы не знакомы с архитектурой безопасности Azure, ознакомьтесь с документацией по безопасности Azure и, в частности, этой статье:

Шифрование данных в состоянии покоя

Обратная связь

Были ли сведения на этой странице полезными?

Last updated on 2026-07-09