Conexión a Azure AI Search mediante la autenticación de claves

Artículo
04/26/2024

Azure AI Search ofrece autenticación basada en claves que puede usar en las conexiones al servicio de búsqueda. Una clave de API es una cadena única compuesta de 52 números y letras generados aleatoriamente. Se acepta una solicitud realizada a un punto de conexión de servicio de búsqueda si la solicitud y la clave de API son válidas.

La autenticación basada en claves es el valor predeterminado. Puede deshabilitarlo si opta por la autenticación basada en roles.

Nota:

Una nota rápida sobre la terminología clave. Una clave de API es una GUID que se usa para la autenticación. Un término independiente, clave de documento, hace referencia a una cadena única en el contenido indexado que se usa para identificar de forma única documentos en un índice de búsqueda.

Tipos de claves de API

Hay dos tipos de claves que se usan para autenticar una solicitud:

Tipo	Nivel de permiso	Máximo	Cómo se creó
Administración	Acceso completo (lectura y escritura) para todas las operaciones de contenido	2 ¹	Cuando se crea el servicio, se generan dos claves de administración, a las que se hace referencia como claves principal y secundaria en el portal. También se pueden volver a generar individualmente a petición.
Consultar	Acceso de solo lectura, con ámbito a la colección de documentos de un índice de búsqueda	50	Se genera una clave de consulta con el servicio. Un administrador de servicios de búsqueda puede crear más a petición.

¹ Tener dos le permite la rotación de una clave mientras se usa la segunda clave para un acceso continuado al servicio.

Visualmente, no hay distinción entre las claves de administración y de consulta. Ambas claves son cadenas formadas por 52 caracteres alfanuméricos generados aleatoriamente. Si necesita saber qué tipo de clave se especifica en la aplicación, puede comprobar los valores de las claves en el portal.

Uso de claves de API en conexiones

Las claves de API se usan para las solicitudes del plano de datos (contenido), como crear o acceder a un índice o a cualquier otra solicitud representada en las API de REST de búsqueda. Tras la creación del servicio, una clave de API es el único mecanismo de autenticación para las operaciones del plano de datos, pero puede reemplazar o complementar la autenticación de claves con roles de Azure si no puede usar claves codificadas de forma rígida en el código.

Las claves de administrador se usan para crear, modificar o eliminar objetos. Las claves de administrador también se usan para obtener definiciones de objetos e información del sistema.

Las claves de consulta se distribuyen normalmente a las aplicaciones cliente que emiten consultas.

Cómo se usan las claves de API en las llamadas REST:

Establezca una clave de administrador en el encabezado de solicitud. No puede pasar claves de administrador en el URI o en el cuerpo de la solicitud. Las claves de administrador se usan para la operación create-read-update-delete y en las solicitudes emitidas al propio servicio de búsqueda, como LIST Indexes o GET Service Statistics.

Este es un ejemplo de uso de clave de API de administración en una solicitud de creación de índice:

### Create an index
POST {{baseUrl}}/indexes?api-version=2023-11-01  HTTP/1.1
  Content-Type: application/json
  api-key: {{adminApiKey}}

    {
        "name": "my-new-index",  
        "fields": [
            {"name": "docId", "type": "Edm.String", "key": true, "filterable": true},
            {"name": "Name", "type": "Edm.String", "searchable": true }
         ]
   }

Establezca una clave de consulta en un encabezado de solicitud para POST o en el URI para GET. Las claves de consulta se usan para las operaciones destinadas a la colección de index/docs: Buscar documentos, Autocompletar, Sugerir o GET Document.

Este es un ejemplo de uso de la clave de API de consulta en una solicitud de documentos de búsqueda (GET):

### Query an index
GET /indexes/my-new-index/docs?search=*&api-version=2023-11-01&api-key={{queryApiKey}}

Nota:

Se considera una práctica poco segura pasar datos confidenciales, como una api-key en el identificador URI de la solicitud. Por este motivo, Azure AI Search solo acepta una clave de consulta como un api-key en la cadena de consulta. Como regla general, se recomienda pasar la api-key como un encabezado de solicitud.

Cómo se usan las claves de API en PowerShell:

Establezca las claves de API en el encabezado de solicitud mediante la siguiente sintaxis:

$headers = @{
'api-key' = '<YOUR-ADMIN-OR-QUERY-API-KEY>'
'Content-Type' = 'application/json' 
'Accept' = 'application/json' }

Puede encontrar un ejemplo de script en el que se muestra el uso de claves de API para varias operaciones en Inicio rápido: Creación de un índice de Azure AI Search en PowerShell mediante las API de REST.

Permisos para ver o administrar claves de API

Los permisos para ver y administrar claves de API se transmiten a través de asignaciones de roles. Los miembros de los roles siguientes pueden ver y regenerar las claves:

Propietario
Colaborador
Colaborador del servicio Search
Administrador y coadministrador (clásico)

Los siguientes roles no tienen acceso a las claves de API:

Lector
Colaborador de datos de índice de búsqueda
Lector de datos de índice de búsqueda

Encontrar las claves existentes

Puede ver y administrar las claves de API en Azure Portal, o a través de PowerShell, la CLI de Azureo la API de REST.

Inicie sesión en Azure Portal y encuentre su servicio de búsqueda.
En Configuración, seleccione Claves para ver las claves de administrador y consulta.

Instalación del módulo Az.Search:
```
Install-Module Az.Search
```

Devolver claves de administrador:

Get-AzSearchAdminKeyPair -ResourceGroupName <resource-group-name> -ServiceName <search-service-name>

Devolver claves de consulta:

Get-AzSearchQueryKey -ResourceGroupName <resource-group-name> -ServiceName <search-service-name>

Use los siguientes comandos para devolver claves de API de administración y consulta, respectivamente:

az search admin-key show --resource-group <myresourcegroup> --service-name <myservice>

az search query-key list --resource-group <myresourcegroup> --service-name <myservice>

Use Enumerar claves de administrador o Enumerar claves de consulta en la API de REST de administración para devolver claves de API.

Debe tener una asignación de roles válida para devolver o actualizar las claves de API. Consulte Administración del servicio Azure AI Search con las API de REST para obtener instrucciones sobre cómo cumplir los requisitos de rol mediante las API de REST.

POST https://management.azure.com/subscriptions/{{subscriptionId}}/resourceGroups/{{resource-group}}/providers//Microsoft.Search/searchServices/{{search-service-name}}/listAdminKeys?api-version=2023-11-01

Creación de claves de consulta

Las claves de consulta se usan para el acceso de solo lectura a los documentos dentro de un índice para las operaciones destinadas a una colección de documentos. Las consultas de búsqueda, filtro y sugerencias son todas las operaciones que toman una clave de consulta. Cualquier operación de solo lectura que devuelve definiciones de objetos o datos del sistema, como una definición del índice o el estado del indexador, requiere una clave de administración.

Restringir el acceso y las operaciones en las aplicaciones cliente es esencial para proteger los activos de búsqueda en el servicio. Use siempre una clave de consulta en lugar de una clave de administración para cualquier consulta originada desde una aplicación cliente.

Inicie sesión en Azure Portal y encuentre su servicio de búsqueda.
En Configuración, seleccione Claves para ver las claves de API.
En Administrar claves de consulta, use la clave de consulta ya generada para el servicio o cree nuevas claves de consulta. La clave de consulta predeterminada no se denomina, pero se pueden denominar otras generadas para la capacidad de administración.

Use Crear claves de consulta en la API de REST de administración.

Debe tener una asignación de roles válida para crear o administrar claves de API. Consulte Administración del servicio Azure AI Search con las API de REST para obtener instrucciones sobre cómo cumplir los requisitos de rol mediante las API de REST.

POST https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Search/searchServices/{searchServiceName}/createQueryKey/{name}?api-version=2023-11-01

Regeneración de claves de administración

Se crean dos claves de administración para cada servicio para que pueda rotar una clave principal mientras usa la clave secundaria para la continuidad empresarial.

En Configuración, seleccione Clavesy, a continuación, copie la clave secundaria.
Para todas las aplicaciones, actualice la configuración de la clave de API para usar la clave secundaria.
Regenere la clave principal
Actualice todas las aplicaciones para usar la nueva clave principal.

Si regenera las claves al mismo tiempo sin querer, se producirá un error HTTP 403 Prohibido en todas las solicitudes de cliente que usen esas claves. Sin embargo, el contenido no se elimina ni se bloquea permanentemente.

Todavía puede acceder al servicio a través del portal o mediante programación. Las funciones de administración están operativas a través de un identificador de suscripción que no es una clave de API de servicio y, por tanto, siguen estando disponibles aunque las claves de API no lo estén.

Después de crear nuevas claves a través del portal o del nivel de administración, el acceso se restaura al contenido (índices, indexadores, orígenes de datos, mapas de sinónimos) una vez que proporcione esas claves en las solicitudes.

Protección de las claves de API

Use asignaciones de roles para restringir el acceso a las claves de API.

No es posible usar el cifrado de claves administradas por el cliente para cifrar las claves de API. Solo los datos confidenciales dentro del propio servicio de búsqueda (por ejemplo, el contenido del índice o las cadenas de conexión en las definiciones de objetos de origen de datos) pueden cifrarse con CMK.

Vaya a la página del servicio de búsqueda de Azure Portal.
En el panel de navegación izquierdo, seleccione Control de acceso (IAM) y después seleccione la pestaña Asignaciones de rol.
En el filtro Rol, seleccione los roles que tienen permiso para ver o administrar claves (Propietario, Colaborador, Colaborador del servicio de búsqueda). Las entidades de seguridad resultantes asignadas a esos roles tienen permisos clave en el servicio de búsqueda.
Como medida de precaución, compruebe también la pestaña Administradores clásicos para determinar si los administradores y coadministradores tienen acceso.

procedimientos recomendados

Use solo las claves de API si la divulgación de datos no es un riesgo (por ejemplo, al usar datos de ejemplo) y si está trabajando detrás de un firewall. La exposición de las claves de API es un riesgo para los datos y para el uso no autorizado del servicio de búsqueda.
Compruebe siempre el código, los ejemplos y el material de entrenamiento antes de publicar para asegurarse de que no ha dejado las claves de API válidas detrás.
En el caso de las cargas de trabajo de producción, cambie a Microsoft Entra ID y acceso basado en rol. O bien, si desea seguir usando claves de API, asegúrese de supervisar siempre quién tiene acceso a las claves de API y regenere las claves de API con regularidad.