Configuración de claves administradas por el cliente para el cifrado de datos en Azure AI Search
Azure AI Search cifra automáticamente los datos en reposo con claves administradas por el servicio. Si se necesita más protección, puede complementar el cifrado predeterminado con otro nivel de cifrado mediante las claves que se crean y administran en Azure Key Vault.
En este artículo se describen los pasos necesarios para configurar el cifrado de claves administradas por el cliente (CMK) o "Bring Your Own Key" (BYOK).
Nota:
Si un índice está cifrado con CMK, solo es accesible si el servicio de búsqueda tiene acceso a la clave. Si se revoca el acceso, 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.
Objetos cifrados con CMK
El cifrado de CMK se aprueba en objetos individuales. Si necesita una CMK en el servicio de búsqueda, establezca una directiva de cumplimiento.
El cifrado con una CMK empieza a estar operativo cuando se crea un objeto. No se pueden cifrar los objetos que ya existen. El cifrado con una CMK sucede cada vez que se guarda un objeto en disco, ya sea datos en reposo de almacenamiento a largo plazo o datos temporales de almacenamiento a corto plazo. Con una CMK, el disco nunca ve datos sin cifrar.
Los objetos que se pueden cifrar incluyen índices, listas de sinónimos, indizadores, orígenes de datos y conjuntos de aptitudes. El cifrado es intensivo a nivel computacional de descifrar, por lo que solo se cifra el contenido confidencial.
El cifrado se realiza a través del siguiente contenido:
Todo el contenido dentro de índices y listas de sinónimos.
Contenido confidencial en indexadores, orígenes de datos, conjuntos de aptitudes y vectorizadores. Este contenido consta solo de los campos que almacenan cadenas de conexión, descripciones, identidades, claves y entradas de usuario. Por ejemplo, los conjuntos de aptitudes tienen las claves de los servicios de Azure AI y algunas aptitudes aceptan entradas de usuario, como entidades personalizadas. En ambos casos, se cifran las claves y las entradas de usuario en las aptitudes. Las referencias a recursos externos (como orígenes de datos de Azure o modelos de Azure OpenAI) también se cifran.
Cifrado doble completo
Al poner en marcha el cifrado con una CMK, el contenido se cifra dos veces. En el caso de los objetos y campos mencionados en la sección anterior, el contenido se cifra primero con la CMK y, en segundo lugar, con la clave administrada por Microsoft. El contenido se cifra por doble partida en discos de datos para el almacenamiento a largo plazo y en discos temporales usados para el almacenamiento a corto plazo.
La habilitación del cifrado CMK aumenta el tamaño del índice y reduce el rendimiento de las consultas. Según las observaciones hechas hasta la fecha, puede esperar un aumento de entre un 30 y un 60 por ciento en los tiempos de consultas, aunque el rendimiento real variará según la definición de los índices y los tipos de consultas. Debido a que se reduce el rendimiento, se recomienda habilitar esta característica solo en los objetos que realmente la necesitan.
Aunque el cifrado doble ya está disponible en todas las regiones, la compatibilidad se implementó en dos fases:
La primera implementación se realizó el 1 de agosto de 2020 e incluyó las cinco regiones que figuran a continuación. Los servicios de búsqueda creados en las siguientes regiones admiten el uso de CMK en los discos de datos, pero no en los discos temporales:
- Oeste de EE. UU. 2
- Este de EE. UU.
- Centro-sur de EE. UU.
- US Gov - Virginia
- US Gov: Arizona
La segunda implementación, que tuvo lugar el 13 de mayo de 2021, incorporó cifrado para discos temporales y un cifrado con CMK ampliado a todas las regiones admitidas.
Si usa CMK desde un servicio creado durante la primera implementación y también quiere disponer de cifrado con CMK en los discos temporales, deberá crear un nuevo servicio de búsqueda en la región de su elección y volver a implementar el contenido. Para determinar la fecha de creación del servicio, consulte Cómo comprobar la fecha de creación del servicio.
Requisitos previos
Azure AI Search en un nivel de servicio facturable (básico o superior, en cualquier región).
Azure Key Vault en la misma suscripción que Azure AI Search. Puede crear un almacén de claves mediante Azure Portal, la CLI de Azure o Azure PowerShell. El almacén de claves debe tener la eliminación temporal y la protección contra purgas habilitada.
Un cliente de búsqueda que puede crear un objeto cifrado, como un cliente REST, Azure PowerShell o un SDK de Azure (Python, .NET, Java, JavaScript).
Limitaciones
No se admite el modelo de seguridad de hardware (HSM) administrado de Azure Key Vault.
No se admite ninguna suscripción cruzada. Azure Key Vault y Búsqueda de Azure AI deben estar en la misma suscripción.
Sugerencias de Key Vault
Si no tiene experiencia con Azure Key Vault, revise este inicio rápido para obtener información sobre las tareas básicas: Establecimiento y recuperación de un secreto de Azure Key Vault mediante PowerShell.
Estas son algunas sugerencias para usar Key Vault:
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 distinta, en almacenes de claves diferentes.
Use el mismo inquilino para recuperar la clave administrada mediante la conexión a través de un sistema o una identidad administrada por el usuario. Este comportamiento requiere que ambos servicios compartan el mismo inquilino. Para obtener más información sobre cómo crear un inquilino, consulte Configurar un nuevo inquilino.
Habilitar la protección de purga y la eliminación temporal. Debido a la naturaleza del cifrado con claves administradas por el cliente, nadie puede recuperar sus 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 eliminación temporal está habilitada de manera predeterminada, por lo que solo tendrá problemas si la deshabilita intencionadamente. La protección de purga no está habilitada de forma predeterminada, pero es necesaria para el cifrado con claves administradas por el cliente de Azure AI Search.
Habilite el registro en el almacén de claves para poder supervisar la utilización de las claves.
Habilitar la autorización de claves o seguir procedimientos estrictos durante el giro rutinario 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 omite este paso, el contenido no se puede descifrar.
Paso 1: Crear una clave en Key Vault
Omita la generación de claves si ya tiene una clave en Azure Key Vault que quiere usar, pero recopile el identificador de clave. Necesita esta información al crear un objeto cifrado.
Antes de agregar la clave, asegúrese de que se le ha asignado el rol Key Vault Crypto Officer.
El cifrado de Búsqueda de Azure AI admite claves RSA de tamaños 2048, 3072 y 4096. Para más información sobre los tipos de clave admitidos, consulte Acerca de las claves.
Inicie sesión en Azure Portal y abra la página de información general del almacén de claves.
Seleccione Objetos>Claves a la izquierda y, a continuación, seleccione Generar e 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.
Seleccione la clave, seleccione la versión actual y tome nota del 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.
Paso 2: Crear una entidad de seguridad
Tiene varias opciones para configurar el acceso de Búsqueda de Azure AI a la clave de cifrado en tiempo de ejecución. El enfoque más sencillo consiste en recuperar la clave mediante la identidad administrada del servicio de búsqueda. Puede usar una identidad administrada por el usuario o por el sistema. De esta forma, se pueden omitir los pasos para el registro de aplicaciones y los secretos de aplicación. Como alternativa, puede crear y registrar una aplicación de Microsoft Entra y hacer que el servicio de búsqueda proporcione el id. de aplicación en las solicitudes.
Se recomienda usar una identidad administrada. Una identidad administrada permite que el servicio de búsqueda se autentique en Azure Key Vault sin almacenar las credenciales (ApplicationID o ApplicationSecret) en el código. El ciclo de vida de este tipo de identidad administrada está ligado al ciclo de vida del servicio de búsqueda, que solo puede tener una identidad administrada asignada por el sistema. Para más información sobre cómo funcionan las identidades administradas, consulte Qué son las identidades administradas de recursos de Azure.
- Identidad administrada por el sistema
- Identidad administrada por el usuario (versión preliminar)
- Registro de una aplicación
Habilite la identidad administrada asignada por el sistema para el servicio de búsqueda.
Paso 3: Conceder permisos
Azure Key Vault admite la autorización mediante controles de acceso basados en roles. Se recomienda este enfoque sobre las directivas de acceso del almacén de claves. Para obtener más información, consulte Proporcionar acceso a claves, certificados y secretos de Key Vault mediante roles de Azure.
En este paso, asigne el rol Usuario de cifrado del servicio criptográfico de Key Vault al servicio de búsqueda. Si está probando localmente, asígnele este rol también.
Inicie sesión en Azure Portal y busque el almacén de claves.
Seleccione Control de acceso (IAM) y Agregar asignación de roles.
Seleccione Usuario de cifrado del servicio criptográfico de Key Vault y, a continuación, seleccione Siguiente.
Seleccione identidades administradas, seleccione miembros y, a continuación, seleccione la identidad administrada del servicio de búsqueda.
Seleccione Revisar y asignar.
Espere unos minutos a que la asignación de roles sea operativa.
Paso 4: Cifrar contenido
Las claves de cifrado se agregan al crear un objeto. Para agregar una clave administrada por el cliente en un índice, mapa de sinónimos, indexador, origen de datos o conjunto de aptitudes, use Azure Portal, una API de REST de Search, o un SDK de Azure para crear un objeto que tenga habilitado el cifrado. Para agregar cifrado mediante el SDK de Azure, consulte el ejemplo de Python en este artículo.
Llame a las API de creación para especificar la propiedad encryptionKey:
Inserte la construcción encryptionKey en la definición del objeto. Es una propiedad de primer nivel, el mismo que el del 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.
En el primer ejemplo se muestra una propiedad 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>" } }En el segundo ejemplo se incluye la propiedad accessCredentials, necesaria 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.
Una vez que cree el objeto cifrado en el servicio de búsqueda, puede usarlo como 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 pueden recuperar fácilmente; para ello, debe ir a la página pertinente de Azure Key Vault en Azure Portal.
Importante
El contenido cifrado de Azure AI Search está configurado para utilizar una clave específica de Azure Key Vault con una versión 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.
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 Azure Portal para esta tarea.
En la página Azure Key Vault, seleccione Objetos>Claves.
Seleccione la clave que acaba de crear y, a continuación, seleccione Eliminar.
En la página Búsqueda de Azure AI, seleccione Buscar administración>Índices.
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 Objetos>Claves.
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.
Configurar una directiva para aplicar el cumplimiento de CMK
Las directivas de Azure ayudan a aplicar los estándares de la organización y a evaluar el cumplimiento a gran escala. Azure AI Search tiene una directiva integrada para el cumplimiento de CMK en todo el servicio opcional.
En esta sección, establecerá la directiva que define un estándar de CMK para el servicio de búsqueda. A continuación, configurará el servicio de búsqueda para aplicar esta directiva.
Vaya a la directiva integrada en el explorador web. Seleccione Asignar.
Configure el ámbito de la directiva. En la sección Parámetros, desactive Mostrar solo los parámetros... y establezca Efecto en Denegar.
Durante la evaluación de la solicitud, una solicitud que coincide con una definición de directiva de denegación se marca como no compatible. Suponiendo que el estándar del servicio es el cifrado CMK, "denegar" significa que las solicitudes que no especifican el cifrado CMK no son compatibles.
Termine de crear la directiva.
Llame a Servicios: Actualizar API para habilitar la aplicación de directivas de CMK en el nivel de servicio.
PATCH https://management.azure.com/subscriptions/<your-subscription-Id>/resourceGroups/<your-resource-group-name>/providers/Microsoft.Search/searchServices/<your-search-service-name>?api-version=2023-11-01
{
"properties": {
"encryptionWithCmk": {
"enforcement": "Enabled"
}
}
}
Rotar o actualizar claves de cifrado
Se recomienda usar las funcionalidades de rotación automática de Azure Key Vault, pero también puede rotar las claves manualmente.
Al cambiar una clave o su versión, cualquier objeto que use la clave primero debe actualizarse para usar los nuevos valores antes de eliminar los valores antiguos. De lo contrario, el objeto se vuelve inutilizable porque no se puede descifrar.
Determine la clave que usa un índice o asignación de sinónimos.
Cree una nueva clave en el almacén de claves, pero deje la clave original disponible.
Actualice las propiedades de encryptionKey en una asignación de sinónimo o índice para usar los nuevos valores. Solo se pueden actualizar los objetos que se crearon originalmente con esta propiedad 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 la clave en la memoria caché durante varias horas. Si deshabilita o elimina la clave sin proporcionar una nueva, las consultas seguirán funcionando de manera temporal hasta que expire la caché. Sin embargo, una vez que el servicio de búsqueda ya no pueda descifrar el contenido, verá este mensaje: "Prohibido el acceso. Puede que la clave de consulta se haya revocado. Vuelva a intentarlo.”
Trabajo con contenido cifrado
Con el cifrado de clave administrada por el cliente, observará una latencia en la indexación y las consultas debido al trabajo adicional de cifrado o descifrado. Azure AI Search no registra la actividad de cifrado, pero puede supervisar el acceso a la clave mediante el registro del almacén de claves.
Se recomienda habilitar el registro como parte de la configuración del almacén de claves.
Agregue una configuración de diagnóstico en el almacén de claves que use el área 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.
Ejemplo de Python de una configuración de clave de cifrado
En esta sección se muestra la representación de 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="<PUT YOUR KEY VAULT ENDPOINT 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')
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 Cliff 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 Cliff 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á ninguna prueba visual del cifrado. Para comprobar que el cifrado funciona, compruebe los registros de recursos.
Pasos siguientes
Si no está familiarizado con la arquitectura de seguridad de Azure, revise la documentación de Azure Security, y en particular, este artículo: