Configuración de claves administradas por el cliente para Búsqueda de Azure AI datos cifrados

La habilitación de claves administradas por el cliente (CMK) agrega seguridad adicional al cifrado predeterminado en reposo cuando se utilizan claves administradas por Microsoft. Al habilitar CMK, se controlan las claves de cifrado que se usan para proteger los datos, incluida la capacidad de:

Rotación de claves según un horario definido por el cliente
Deshabilitar o revocar claves para bloquear el acceso al contenido cifrado (las claves almacenadas en caché pueden persistir hasta 60 minutos).
Auditar el uso de claves a través del registro de Azure Key Vault

Puede crear, almacenar y administrar claves mediante:

Azure Key Vault
HSM administrado de Azure Key Vault (módulo de seguridad de hardware). Un HSM administrado Azure Key Vault es un HSM validado por FIPS 140-2 nivel 3. Para migrar de Azure Key Vault a HSM, rotate las claves y elija HSM administrado para el almacenamiento.

En este artículo se explica cómo configurar CMK para una protección adicional de los datos cifrados en Búsqueda de Azure AI.

Importante

Agregar una clave administrada por el cliente (CMK) se aplica al cifrado de los datos en reposo. Si necesita proteger los datos en uso, considere la posibilidad de usar la computación confidencial.

Requisitos previos

Búsqueda de Azure AI en un nivel facturable (básico o superior, en cualquier región).
Azure Key Vault y un almacén de claves con la eliminación suave y la protección de purga habilitadas. O bien, Azure Key Vault Managed HSM. Este recurso puede estar en cualquier suscripción y en una entidad diferente. En estas instrucciones se supone un único usuario. Para la configuración entre entidades, vea Configurar claves administradas por el cliente en distintas entidades.
Capacidad de configurar permisos para el acceso a claves y asignar roles. Para crear claves, debe ser Key Vault Crypto Officer en Azure Key Vault o Managed HSM Crypto Officer en Azure Key Vault Managed HSM.

Para asignar roles, debe ser Propietario, Administrador de acceso de usuario, Administrador de control de acceso basado en roles o estar asignado a un rol personalizado con permisos Microsoft.Authorization/roleAssignments/write.

Configuración de CMK en objetos de Búsqueda de Azure AI

Los objetos con datos cifrados que se pueden configurar con una clave administrada por el cliente (CMK) incluyen índices, listas de sinónimos, indexadores, orígenes de datos, vectorizadores y conjuntos de aptitudes. El cifrado es computacionalmente costoso de descifrar, por lo que solo se cifra el contenido confidencial.

El cifrado se realiza a través de:

Todo el contenido dentro de índices y listas de sinónimos.
Contenido confidencial en indexadores, orígenes de datos, conjuntos de habilidades y vectorizadores. Contenido confidencial hace referencia a cadenas de conexión, descripciones, identidades, claves y entradas de usuario. Por ejemplo, los conjuntos de aptitudes tienen claves de Foundry Tools y algunas aptitudes aceptan entradas de usuario, como entidades personalizadas. En ambos casos, las claves y las entradas de usuario se cifran. Las referencias a recursos externos (como orígenes de datos de Azure o modelos de Azure OpenAI) también se cifran.

La adición de una clave administrada por el cliente a un objeto debe producirse cuando el objeto se crea recientemente. Es importante tener en cuenta lo siguiente:

No se puede agregar CMK de forma retroactiva a un objeto existente. Si desea agregar una clave administrada por el cliente a un objeto existente, debe eliminar y volver a crear ese objeto con el cifrado habilitado.
Una vez configurado CMK, el cifrado se produce cada vez que el servicio escribe datos, incluidos ambos datos en reposo (almacenamiento a largo plazo) o datos almacenados en caché temporal (almacenamiento a corto plazo). Para objetos como orígenes de datos, indexadores y conjuntos de aptitudes, la definición de objeto se cifra. En el caso de los índices, los propios documentos indexados (no solo el esquema de índice) se cifran.
Aunque no se puede agregar cifrado a un objeto existente, una vez configurado un objeto para el cifrado, puede cambiar todas las partes de su definición de cifrado, incluido el cambio a otro almacén de claves o almacenamiento HMS siempre que el recurso esté en el mismo inquilino.
El cifrado con una CMK es irreversible. Puede rotar las claves y cambiar la configuración de CMK, pero el cifrado de índice dura durante la vigencia del índice. Después del cifrado con CMK, solo se puede acceder a un índice si el servicio de búsqueda tiene acceso a la clave. Si revoca el acceso a la clave eliminando o cambiando la asignación de roles, el índice no se puede usar y el servicio no se puede escalar hasta que se elimine el índice o se restaure el acceso a la clave. Si elimina o gira las claves, la clave más reciente se almacena en caché durante un máximo de 60 minutos.
Si necesita CMK en el servicio de búsqueda, establezca una directiva de cumplimiento.
La aplicación de CMK mediante Azure Policy y la configuración de CMK de nivel de servicio (que todavía está en versión preliminar) son configuraciones independientes. Puede usar cualquiera de los dos o ambos, en función de sus necesidades. La configuración de CMK a nivel de servicio aplica una clave predeterminada a los nuevos objetos, mientras que el cumplimiento de la política de Azure garantiza que todos los objetos cumplan con los requisitos de cifrado. Si habilita una directiva de cumplimiento de CMK sin una clave de nivel de servicio, todos los objetos habilitados para CMK deben especificar su propia clave de cifrado en el momento de la creación. Se produce un error en las solicitudes de creación de objetos que omiten la configuración de CMK.

Habilitar CMK de nivel de servicio en nuevos objetos de forma predeterminada (versión preliminar)

Nota

Esta característica está actualmente en versión preliminar. Esta versión preliminar se proporciona sin un contrato de nivel de servicio y no se recomienda para cargas de trabajo de producción. Es posible que algunas características no se admitan o que tengan funcionalidades restringidas. Para obtener más información, vea Supplemental Terms of Use for Microsoft Azure Previews.

A partir de la versión 2026-03-01-preview, tiene la capacidad de configurar una clave administrada por el cliente en el nivel de servicio en el propio servicio Búsqueda de Azure AI. Esta característica permite configurar la clave una vez en el nivel de servicio y aplicarla a todos los objetos recién creados de forma predeterminada. Esto garantiza que todos los datos confidenciales del servicio de búsqueda están protegidos por una clave que controla, sin tener que especificar información de clave cada vez que se crea un objeto. En el plano de datos 2026-05-01-preview API, la isServiceLevelKey propiedad de encryptionKey ayuda a determinar si un objeto hereda la clave de nivel de servicio o usa una clave de nivel de objeto explícita.

Habilitar CMK en el nivel de servicio significa:

Todos los objetos new creados en el servicio Búsqueda de Azure AI usan automáticamente la clave administrada por el cliente de nivel de servicio de forma predeterminada, por lo que ya no es necesario especificar explícitamente los detalles de la clave de cifrado cada vez que se crea un objeto.
Esta característica es opcional y puede seguir configurando CMK por objeto. También puede invalidar la clave de nivel de servicio para objetos individuales y rotar la clave de nivel de servicio de forma independiente, lo que le permite usar claves diferentes para distintos objetos según sea necesario.

También puede rotar esta clave predeterminada especificando una nueva clave, específica del objeto que está creando. La clave de nivel de objeto que especifique invalidará la clave de nivel de servicio predeterminada para ese objeto.

Elegir entre CMK de nivel de servicio y de nivel de objeto

Use CMK de nivel de servicio de forma predeterminada para aplicar una sola clave en todos los objetos. La clave se configura una vez y los nuevos objetos heredan esa protección automáticamente.

Use CMK de nivel de objeto para cargas de trabajo que requieran un ciclo de vida de clave independiente. Las configuraciones de CMK de nivel de objeto existentes siguen funcionando sin cambios. CMK de nivel de servicio simplifica la administración de claves, pero no reemplaza CMK de nivel de objeto.

Un patrón empresarial común es configurar una clave de nivel de servicio para la mayoría de los objetos (índices, indexadores, orígenes de datos, conjuntos de aptitudes, vectorizadores y mapas de sinónimos). Las cargas de trabajo con requisitos de cumplimiento más estrictos pueden configurar una clave de nivel de objeto para administrar el acceso, la rotación y la revocación de forma independiente.

Paso 1: Crear una clave de cifrado

Usa Azure Key Vault o HSM administrado de Azure Key Vault para crear una clave. Búsqueda de Azure AI cifrado admite claves RSA de tamaños 2048, 3072 y 4096. Para obtener más información sobre los tipos de clave admitidos, vea Acerca de las claves.

Se recomienda revisar estas sugerencias antes de empezar.

Las operaciones necesarias son Wrap, Unwrap, Encrypt y Decrypt.

Azure Key Vault
HSM administrado

Puede crear un almacén de claves mediante el portal de Azure, CLI de Azure o Azure PowerShell.

Vaya al almacén de claves en el portal Azure.
Seleccione Claves de objetos> a la izquierda y, a continuación, seleccione Generar o importar.
En el panel Crear una clave , en la lista de opciones, elija Generar para crear una clave.
Escriba un nombre para la clave y acepte los valores predeterminados para otras propiedades de clave.
Opcionalmente, establezca una directiva de rotación de claves para habilitar la rotación automática.
Seleccione Crear para iniciar la implementación.
Una vez creada la clave, obtenga su identificador de clave. Seleccione la clave, seleccione la versión actual y, a continuación, copie el identificador de clave. Se compone del URI del valor de clave, el nombre de clave y la versión de clave. Necesita el identificador para definir un índice cifrado en Búsqueda de Azure AI. Recuerde que las operaciones necesarias son Wrap, Unwrap, Encrypt y Decrypt.

Paso 2: Crear una entidad de seguridad

Cree una entidad de seguridad que use el servicio de búsqueda para acceder a la clave de cifrado. Puede usar una identidad administrada y una asignación de roles, o puede registrar una aplicación y hacer que el servicio de búsqueda proporcione el identificador de aplicación en las solicitudes.

Utilice una identidad administrada y funciones. Puede usar una identidad administrada por el sistema o una identidad administrada por el usuario. Una identidad administrada permite que el servicio de búsqueda se autentique a través de Microsoft Entra ID, sin almacenar credenciales (ApplicationID o ApplicationSecret) en el código. El ciclo de vida de este tipo de identidad administrada está vinculado al ciclo de vida del servicio de búsqueda, que solo puede tener una identidad administrada asignada por el sistema. Para obtener más información sobre cómo funcionan las identidades administradas, consulte ¿Qué son las identidades administradas para los recursos de Azure.

Habilite la identidad administrada asignada por el sistema para el servicio de búsqueda. Se trata de una operación de dos clics: habilitar y guardar.

Paso 3: Concesión de permisos

Si configuró el servicio de búsqueda para usar una identidad administrada, asigne roles que le proporcionen acceso a la clave de cifrado.

Se recomienda el control de acceso basado en roles en lugar del modelo de permisos de la política de acceso. Para obtener más información o pasos de migración, comience con Azure Role-Based Access Control (Azure RBAC) vs. directivas de acceso (clásicas).

Vaya al almacén de claves en el portal Azure.
Seleccione Control de acceso (IAM) y seleccione Agregar asignación de roles.
Seleccione un rol:
- En Azure Key Vault, seleccione Key Vault Usuario de cifrado de servicios criptográficos.
- En HSM administrado, seleccione Usuario de cifrado de servicio criptográfico de HSM administrado.
Seleccione identidades administradas, seleccione miembros y, a continuación, seleccione la identidad administrada del servicio de búsqueda. Si estás probando localmente, asígnate este rol también.
Seleccione Revisar y asignar.

Espere unos minutos para que la asignación de roles se ponga en funcionamiento.

Key Vault firewall y acceso a la red virtual para CMK

Búsqueda de Azure AI debe poder acceder a la clave de cifrado en el Azure Key Vault.

Si el almacén de claves usa un firewall o restricciones de red virtual, configure una de las siguientes opciones:

Permitir el acceso desde redes seleccionadas que incluyan el servicio de búsqueda.
Habilite Permitir que los servicios de Microsoft de confianza omitan este firewall.

Cuando la excepción para servicios de confianza está habilitada, Búsqueda de Azure AI puede acceder a la clave como servicio de confianza mediante una identidad administrada, incluso cuando el acceso a la red pública está restringido.

Si el firewall bloquea el acceso y la excepción para servicios de confianza no está habilitada, Búsqueda de Azure AI no puede recuperar la clave y las operaciones que dependen de CMK fallan.

Paso 4: Agregar información de clave de cifrado a Búsqueda de Azure AI objetos

Al crear un objeto cifrado, escriba el URI del almacén de claves, el nombre de clave y la versión de la clave. Si usa una aplicación de Microsoft Entra ID para la autenticación, escriba también el identificador y el secreto de la aplicación.

Puede configurar nuevos objetos de búsqueda con una clave administrada por el cliente en el nivel de servicio o en el nivel de objeto. Al configurar CMK en el nivel de servicio, se aplica la misma clave de forma predeterminada a todos los objetos recién creados en el servicio, a menos que especifique una clave de nivel de objeto diferente para invalidar el valor predeterminado de nivel de servicio.

Especifique la clave administrada por el cliente en la definición de objeto al crear un objeto cifrado. Este objeto puede ser un índice, indexador, origen de datos, conjunto de aptitudes, vectorizador o mapa de sinónimos.

Para configurar CMK en un objeto, use el portal de Azure, Search Service REST API o un SDK de Azure.

Al crear un nuevo objeto en el portal de Azure, puede especificar una clave administrada por el cliente predefinida en un almacén de claves. El portal de Azure le permite habilitar el cifrado con una CMK para:

Índices
Orígenes de datos
Indexadores

Para usar el portal de Azure, debe existir el almacén de claves y la clave, y debe completar los pasos anteriores para el acceso autorizado a la clave.

En el portal de Azure, los conjuntos de aptitudes se definen en la vista JSON. Use el código JSON que se muestra en los ejemplos de la API REST para proporcionar una clave administrada por el cliente en un conjunto de aptitudes.

Vaya al servicio de búsqueda en el portal Azure.
En Administración de búsquedas, seleccione Índices, Indexadores o Orígenes de datos.
Agregue un nuevo objeto. En la definición de objeto, seleccione cifrado administrado por Microsoft.
Seleccione Claves administradas por el cliente y elija su suscripción, almacén, clave y versión.

Llame a las API de creación para especificar la propiedad encryptionKey :

Inserte la construcción encryptionKey en la definición de objeto. Esta propiedad es una propiedad de primer nivel, en el mismo nivel que el nombre y la descripción. Si usa el mismo almacén, clave y versión, puede pegar la misma construcción de la propiedad encryptionKey en la definición de cada objeto.

Si el identificador de clave es https://contoso-keyvault.vault.azure.net/keys/contoso-cmk/aaaaaaaa-0b0b-1c1c-2d2d-333333333333, el URI es https://contoso-keyvault.vault.azure.net, el nombre de clave es contoso-cmky la versión es 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>"
    }
  }
}

En el primer ejemplo se muestra un encryptionKey para un servicio de búsqueda que se conecta mediante una identidad administrada:

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

El segundo ejemplo incluye accessCredentials, necesario si registró una aplicación en 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>"
    }
  }
}

Compruebe que la clave de cifrado existe mediante la emisión de un GET en el objeto .
Compruebe que el objeto está operativo realizando una tarea, como consultar un índice cifrado.

Después de crear el objeto cifrado en el servicio de búsqueda, puede usarlo como lo haría con cualquier otro objeto de su tipo. El cifrado es transparente para el usuario y el desarrollador.

Ninguno de estos detalles del almacén de claves se considera secreto y se puede recuperar fácilmente navegando a la página de Azure Key Vault pertinente en Azure portal.

La configuración de CMK en objetos de búsqueda se admite en paquetes de SDK de Azure, incluidos SDK de Azure para .NET, SDK de Azure para Java, SDK de Azure para JavaScript y SDK de Azure para Python.

En el ejemplo siguiente se muestra la representación Python de un encryptionKey en una definición de objeto. La misma definición se aplica a índices, orígenes de datos, conjuntos de aptitudes, indexadores y mapas de sinónimos. Para probar este ejemplo en el servicio de búsqueda y el almacén de claves, descargue el cuaderno de azure-search-python-samples.

Instale algunos paquetes.

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

Cree un índice que tenga una clave de cifrado.

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=endpoint, credential=credential)
fields = [
SimpleField(name="Id", type=SearchFieldDataType.String, key=True),
SearchableField(name="Description", type=SearchFieldDataType.String)
]

scoring_profiles = []
suggester = []
encryption_key = SearchResourceEncryptionKey(
key_name="<PUT YOUR KEY VAULT NAME HERE>",
key_version="<PUT YOUR ALPHANUMERIC KEY VERSION HERE>",
vault_uri
)

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

Obtenga la definición de índice para comprobar que existe la configuración de la clave de cifrado.

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

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

Cargue el índice con algunos documentos. Todo el contenido del campo se considera confidencial y se cifra en el disco mediante la clave administrada por el cliente.

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.message)

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

Ejecute una consulta para confirmar que el índice está operativo.

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

La salida de la consulta debe generar resultados similares al ejemplo siguiente.

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.

Dado que el contenido cifrado se descifra antes de la actualización de datos o las consultas, no verá evidencia visual del cifrado. Para comprobar que el cifrado funciona, compruebe los registros de recursos.

Importante

El contenido cifrado en Búsqueda de Azure AI está configurado para usar una clave específica con una version específica. Si cambia la clave o la versión, el objeto debe actualizarse para usarlo antes de eliminar el anterior. Si no lo hace, el objeto no se puede usar. No podrá descifrar el contenido si se pierde la clave.

Configuración de CMK en el nivel de servicio (versión preliminar)

Para habilitar la configuración de CMK a nivel de servicio, recomendamos que utilice la API REST de Search Management o un paquete del SDK de Azure que se haya actualizado para admitir la versión 2026-03-01-preview o posterior. Esta característica aún no se admite en el portal de Azure. Al habilitar CMK en el nivel de servicio no se agrega cifrado a los objetos existentes, pero se aplica la misma clave de forma predeterminada a todos los objetos recién creados en el servicio, a menos que especifique una clave de nivel de objeto diferente para invalidar el valor predeterminado de nivel de servicio.

Actualmente, el portal de Azure no admite el cifrado de nivel de servicio. Use la API REST directamente.

Para configurar el cifrado con una CMK en el nivel de servicio del servicio de búsqueda, use Servicios: Crear o actualizar con PATCH para actualizar un servicio de búsqueda existente o PUT para crear uno nuevo. La versión de la API debe ser 2026-03-01-preview o posterior para admitir la configuración de nivel de servicio.

En este ejemplo, asegúrese de reemplazar {{subscription-id}}, {{resource-group}}, {{search-service}}y {{token}} por el identificador de suscripción, el nombre del grupo de recursos, el nombre del servicio de búsqueda y el token de acceso, respectivamente. La definición de clave usa el mismo esquema que CMK de nivel de objeto y se admiten las tres opciones de identidad (identidad administrada asignada por el sistema, identidad administrada asignada por el usuario o aplicación registrada).

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

Consulte los ejemplos siguientes para insertar la construcción encryptionKey en el nivel de servicio para distintos tipos de identidad.

Ejemplo de uso de la identidad administrada asignada por el sistema:

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

Ejemplo de uso de la identidad administrada por el usuario:

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

Ejemplo de uso del identificador de aplicación:

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

Comprobar si un objeto de búsqueda hereda la CMK del nivel de servicio

Para comprobar si un objeto de búsqueda usa una clave administrada por el cliente configurada en el nivel de servicio como una clave administrada por el cliente predeterminada o única configurada en el nivel de objeto, puede comprobar el estado de cifrado heredado mediante la isServiceLevelKey propiedad .

Actualmente, el portal de Azure no admite el cifrado de nivel de servicio. Use la API REST directamente.

En la versión 2026-05-01-previewde la API del plano de datos , use una llamada de objeto GET para inspeccionar encryptionKey.isServiceLevelKey.

El fragmento de código siguiente es un ejemplo. Deberá actualizarlo con los valores específicos del caso de uso.

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

Cuando isServiceLevelKey es true, el objeto hereda la clave del nivel de servicio y no tiene una anulación explícita de nivel de objeto.

Para desacoplar el ciclo de vida de un objeto específico, establezca una clave de nivel de objeto explícita y establezca isServiceLevelKeyfalse en en una solicitud de creación o actualización.

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

Con esta anulación, el ciclo de vida de la clave de objeto se desacopla del valor predeterminado del nivel de servicio. Puede rotar la clave de nivel de objeto de forma independiente sin cambiar la clave de nivel de servicio usada por otros objetos.

Para devolver un objeto a la herencia de CMK de nivel de servicio, actualice el objeto con isServiceLevelKey establecido en true y omita los detalles de clave de nivel de objeto.

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

Después de esta actualización, el objeto de búsqueda hereda de nuevo la clave de nivel de servicio. Cuando se proporciona una clave de nivel de objeto explícita, establecer isServiceLevelKey en false es opcional porque la definición de clave explícita invalida la herencia de nivel de servicio.

Paso 5: Probar el cifrado

Para comprobar que el cifrado funciona, revoque la clave de cifrado, consulte el índice (debe ser inutilizable) y, a continuación, restablezca la clave de cifrado.

Use el portal de Azure para esta tarea. Asegúrese de que tiene una asignación de roles con acceso de lectura a la clave.

En la página Azure Key Vault, seleccione Objects>Keys.
Seleccione la clave que ha creado y, a continuación, seleccione Eliminar.
En la página Búsqueda de Azure AI, seleccione Search management>Indexes.
Seleccione el índice y use el Explorador de búsqueda para ejecutar una consulta. Debería recibir un error.
Vuelva a la página Azure Key Vault Objects>Keys.
Seleccione Administrar claves eliminadas.
Seleccione la clave y, a continuación, seleccione Recuperar.
Vuelva al índice en Búsqueda de Azure AI y vuelva a ejecutar la consulta. Debería ver los resultados de la búsqueda. Si no ve resultados inmediatos, espere un minuto e inténtelo de nuevo.

Establecer una política para hacer cumplir el cumplimiento de CMK

Las políticas de Azure ayudan a aplicar los estándares organizacionales y a evaluar el cumplimiento a escala. Búsqueda de Azure AI tiene dos directivas integradas opcionales relacionadas con CMK. Estas directivas se aplican a los servicios de búsqueda nuevos y existentes.

Efecto Descripción

AuditIfNotExists Comprueba el cumplimiento de directivas: los objetos tienen definida una clave administrada por el cliente y es el contenido cifrado. Este efecto se aplica a los servicios existentes con contenido. Se evalúa cada vez que se crea o actualiza un objeto, o según la programación de evaluación. Aprende más...

Denegar Comprueba la aplicación de directivas: el servicio de búsqueda tiene SearchEncryptionWithCmk configurado para Enabled. Este efecto solo se aplica a los nuevos servicios, que se deben crear con el cifrado habilitado. Los servicios existentes permanecen operativos, pero no se pueden actualizar a menos que aplique un parche al servicio. Ninguna de las herramientas que se usan para aprovisionar servicios expone esta propiedad, por lo que tenga en cuenta que establecer la directiva le limita a configurar mediante programación.

Efecto	Descripción
AuditIfNotExists	Comprueba el cumplimiento de directivas: los objetos tienen definida una clave administrada por el cliente y es el contenido cifrado. Este efecto se aplica a los servicios existentes con contenido. Se evalúa cada vez que se crea o actualiza un objeto, o según la programación de evaluación. Aprende más...
Denegar	Comprueba la aplicación de directivas: el servicio de búsqueda tiene SearchEncryptionWithCmk configurado para `Enabled`. Este efecto solo se aplica a los nuevos servicios, que se deben crear con el cifrado habilitado. Los servicios existentes permanecen operativos, pero no se pueden actualizar a menos que aplique un parche al servicio. Ninguna de las herramientas que se usan para aprovisionar servicios expone esta propiedad, por lo que tenga en cuenta que establecer la directiva le limita a configurar mediante programación.

Asignar una directiva

En el portal de Azure, vaya a una directiva integrada y seleccione Assign.
- AuditIfExists
- Denegar
Este es un ejemplo de la directiva AuditIfExists en el portal de Azure:
Establezca el ámbito de directiva seleccionando la suscripción y el grupo de recursos. Excluya los servicios de búsqueda para los que no se debe aplicar la directiva.
Acepte o modifique los valores predeterminados. Seleccione Revisar y crear y, a continuación, seleccione Crear.

Habilitación de la aplicación de directivas de CMK

Al asignar una directiva a un grupo de recursos en su suscripción, surte efecto inmediatamente. Las directivas de auditoría marcan recursos no compatibles, pero las directivas de denegación impiden la creación y actualización de servicios de búsqueda no compatibles. En esta sección se explica cómo crear un servicio de búsqueda compatible o actualizar un servicio para que sea compatible. Para poner objetos en cumplimiento, comience en el paso uno de este artículo.

Creación de un servicio de búsqueda compatible

Para los nuevos servicios de búsqueda, créelos con SearchEncryptionWithCmk establecido en Enabled.

Ni el portal de Azure ni las herramientas de línea de comandos (el CLI de Azure y el Azure PowerShell) proporcionan esta propiedad de forma nativa, pero puede usar API REST de Administración para aprovisionar un servicio de búsqueda con una definición de directiva cmK.

API REST de administración

Este ejemplo procede de Administrar el servicio de Búsqueda de Azure AI con las API REST, modificados para incluir la propiedad 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"
        }
      }
    }

Actualización de un servicio de búsqueda existente

Para los servicios de búsqueda existentes que ahora no son compatibles, repaquelos mediante Services - Update API o el comando CLI de Azure az resource update. Aplicar revisiones a los servicios restaura la capacidad de actualizar las propiedades del servicio de búsqueda.

API REST de administración
CLI de Azure

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

Ejecute el comando siguiente, sustituyendo los valores válidos para el servicio de búsqueda y el grupo de recursos.

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

La respuesta debe incluir la siguiente instrucción:

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

"No compatible" significa que el servicio de búsqueda tiene objetos existentes que no están cifrados con CMK. Para lograr el cumplimiento, vuelva a crear cada objeto y especifique una clave de cifrado.

Rotación o actualización de claves de cifrado

Siga estas instrucciones para rotar las claves o migrar de Azure Key Vault al modelo de seguridad de hardware (HSM).

Para la rotación de claves, use las funcionalidades de rotación automática de Azure Key Vault. Si usa la autorización, omita la versión de clave en las definiciones de objeto. Se usa la clave más reciente, en lugar de una versión específica.

Al cambiar una clave o su versión, actualice cualquier objeto que use la clave para usar los nuevos valores antes de eliminar los valores antiguos. De lo contrario, el objeto se vuelve inutilizable porque no se puede descifrar.

Si ha configurado CMK en el nivel de servicio, la rotación de la clave de nivel de servicio se aplicará a los objetos que se creen a partir de ahora. Los objetos que ya heredaron la clave de nivel de servicio anterior seleccionan automáticamente la nueva clave, por lo que no es necesario actualizarlas. Sin embargo, si tenía objetos configurados con una clave de nivel de objeto que también desea rotar, deberá actualizar esos objetos para que usen la nueva clave.

Las claves se almacenan en caché durante 60 minutos. Recuerde esto al probar y rotar las claves.

Determine la clave usada por un índice o mapa de sinónimos.
Cree una nueva clave en el almacén de claves, pero deje la clave original disponible. En este paso, puede cambiar del almacén de claves a HSM.
Actualice las propiedades encryptionKey en un índice o mapa de sinónimos para usar los nuevos valores. Solo los objetos creados originalmente con esta propiedad se pueden actualizar para usar un valor diferente.
Deshabilite o elimine la clave anterior en el almacén de claves. Supervise el acceso a la clave para comprobar que se está usando la nueva clave.

Por motivos de rendimiento, el servicio de búsqueda almacena en caché la clave durante hasta varias horas. Si deshabilita o elimina la clave sin proporcionar una nueva, las consultas seguirán funcionando temporalmente hasta que expire la memoria caché. Sin embargo, una vez que el servicio de búsqueda ya no puede descifrar el contenido, recibirá este mensaje: "Access forbidden. The query key used might have been revoked - please retry."

sugerencias de Key Vault

Si no está familiarizado con Azure Key Vault, consulte este inicio rápido para obtener información sobre las tareas básicas: Set y recuperar un secreto de Azure Key Vault mediante PowerShell.
Use tantos almacenes de claves como necesite. Las claves administradas pueden estar en almacenes de claves diferentes. Un servicio de búsqueda puede tener varios objetos cifrados, cada uno cifrado con una clave de cifrado administrada por el cliente diferente, almacenada en almacenes de claves diferentes.
Use el mismo tenant de Azure para que puedas recuperar tu clave administrada mediante asignaciones de roles y mediante una identidad gestionada por el sistema o por el usuario. Para obtener más información sobre cómo crear un inquilino, consulte Configuración de un nuevo inquilino.
Si Azure Key Vault está protegido con un cortafuegos, asegúrese de habilitar Permitir que los servicios de Microsoft de confianza omitan este cortafuegos para que Búsqueda de Azure AI pueda acceder a la clave.
Habilite la protección contra purga y la eliminación temporal en un almacén de claves. Debido a la naturaleza del cifrado con claves administradas por el cliente, nadie puede recuperar los datos si se elimina la clave de Azure Key Vault. Para evitar la pérdida de datos causada por las eliminaciones accidentales de claves de Key Vault, debe habilitar las opciones de eliminación temporal y de protección de purgas en el almacén de claves. La supresión suave está habilitada de forma predeterminada, así que solo enfrentarás problemas si la deshabilitas a propósito. La protección de purga no está habilitada de forma predeterminada, pero es necesaria para el cifrado con una CMK en Búsqueda de Azure AI.
Habilite el registro en el almacén de claves para poder supervisar el uso de claves.
Habilite la rotación automática de claves o siga unos procedimientos estrictos durante la rotación rutinaria de las claves del almacén de claves y de los secretos y el registro de aplicaciones. Actualice siempre todo el contenido cifrado para usar nuevos secretos y claves antes de eliminar los antiguos. Si pierde este paso, no se puede descifrar el contenido.

Trabajar con contenido cifrado

Con CMK, es posible que observe latencia para la indexación y las consultas debido al trabajo adicional de cifrado y descifrado. Búsqueda de Azure AI no registra la actividad de cifrado, pero puede supervisar el acceso a las claves a través del registro del almacén de claves.

Se recomienda habilitar el registro como parte de la configuración del almacén de claves.

Cree un área de trabajo de Log Analytics.
Agregue un ajuste de diagnóstico en Key Vault que utilice el espacio de trabajo para la retención de datos.
Seleccione audit o allLogs para la categoría, asigne un nombre a la configuración de diagnóstico y guárdelo.

Pasos siguientes

Si no está familiarizado con la arquitectura de seguridad de Azure, revise la documentación de seguridad de Azure y, en particular, en este artículo:

Cifrado de datos en reposo

Comentarios

¿Le ha resultado útil esta página?

Last updated on 2026-06-03