Habilitar o deshabilitar el control de acceso basado en roles en Azure AI Search

Si desea utilizar el control de acceso basado en funciones de Azure para las conexiones a Azure AI Search, en este artículo se explica cómo habilitarlo para su servicio de búsqueda.

El acceso basado en roles para las operaciones del plano de datos es opcional, pero recomendable. La alternativa es autenticación basada en claves, que es el valor predeterminado.

Las funciones de administración de servicios (plano de control) están integradas y no pueden habilitarse ni deshabilitarse.

Nota:

El plano de datos se refiere a las operaciones contra el punto de conexión del servicio de búsqueda, como la indexación o las consultas, o cualquier otra operación especificada en la API de REST de búsqueda o en las bibliotecas de cliente Azure SDK equivalentes.

Requisitos previos

• Propietario, Administrador de acceso de usuario, o un rol personalizado con permisos Microsoft.Authorization/roleAssignments/write.

• Un servicio de búsqueda en cualquier región, en cualquier nivel, incluido el gratuito.

Habilitación del acceso basado en roles para las operaciones del plano de datos

Cuando habilita roles para el plano de datos, el cambio es efectivo inmediatamente, pero espere unos segundos antes de asignar roles.

El modo de error predeterminado es http401WithBearerChallenge. Como alternativa, puede establecer el modo de error en http403.

Una vez habilitado el acceso basado en roles, el servicio de búsqueda reconoce un encabezado de autorización en las solicitudes del plano de datos que proporcionan un token de acceso OAuth2.

Azure Portal

1. Inicie sesión en Azure Portal y abra la página del servicio de búsqueda.

2. Seleccione Configuración, y luego seleccione Teclas en el panel de navegación izquierdo.

   

3. Elija Control basado en roles o Ambos si actualmente está utilizando claves y necesita tiempo para realizar la transición de los clientes al control de acceso basado en roles.

   Opción	Descripción
   Clave de API	(valor predeterminado). Requiere claves de API en el encabezado de solicitud para la autorización.
   Control de acceso basado en rol	Requiere la pertenencia a una asignación de roles para completar la tarea. También requiere un encabezado de autorización en la solicitud.
   Ambos	Las solicitudes son válidas mediante una clave de API o un control de acceso basado en rol, pero si proporciona ambos en la misma solicitud, se usa la clave de API.

4. Como administrador, si elige un enfoque de solo roles, asignar roles de plano de datos a su cuenta de usuario para restaurar el acceso administrativo completo a través de las operaciones del plano de datos en Azure Portal. Los roles incluyen Colaborador del servicio Search, Colaborador de datos de índice de búsqueda y Lector de datos de índice de búsqueda. Necesita los tres roles si desea acceso equivalente.

   A veces, las asignaciones de roles pueden tardar entre cinco y diez minutos en surtir efecto. Hasta ese momento, aparece el mensaje siguiente en las páginas del portal usadas para las operaciones del plano de datos.

   

CLI de Azure

Ejecute este script solo para admitir roles:

az search service update `
  --name YOUR-SEARCH-SERVICE-NAME `
  --resource-group YOUR-RESOURCE-GROUP-NAME `
  --disable-local-auth

O bien, ejecute este script para admitir tanto claves como roles:

az search service update `
  --name YOUR-SEARCH-SERVICE-NAME `
  --resource-group YOUR-RESOURCE-GROUP-NAME `
  --aad-auth-failure-mode http401WithBearerChallenge `
  --auth-options aadOrApiKey

Para obtener más información, consulte Administrar el servicio Azure AI Search con Azure CLI.

Azure PowerShell

Ejecute este comando para establecer el tipo de autenticación en solo roles:

Set-AzSearchService `
  -Name YOUR-SEARCH-SERVICE-NAME `
  -ResourceGroupName YOUR-RESOURCE-GROUP-NAME `
  -DisableLocalAuth 1

O bien, ejecute este comando para admitir tanto claves como roles:

Set-AzSearchService `
  -Name YOUR-SEARCH-SERVICE-NAME `
  -ResourceGroupName YOUR-RESOURCE-GROUP-NAME `
  -AuthOption AadOrApiKey

Para obtener más información, consulte Administrar el servicio Azure AI Search con PowerShell.

REST API

Use la API REST de administración Crear o actualizar servicio para configurar el servicio para el control de acceso basado en roles.

Todas las llamadas a la API de REST de administración se autentican a través de Microsoft Entra ID. Para obtener ayuda para configurar solicitudes autenticadas, consulte Administración de Azure AI Search mediante REST.

1. Obtenga la configuración del servicio para que pueda revisar la configuración actual.

   GET https://management.azure.com/subscriptions/{{subscriptionId}}/providers/Microsoft.Search/searchServices?api-version=2023-11-01
   

2. Use PATCH para actualizar la configuración del servicio. Las siguientes modificaciones habilitan tanto las claves como el acceso basado en roles. Si desea una configuración solo con roles, consulte Deshabilitar las claves de API.

   En "Propiedades", establezca "authOptions" como "aadOrApiKey". La propiedad "disableLocalAuth" debe ser false para establecer "authOptions".

   También puede establecer aadAuthFailureMode para especificar si se devuelve 401 en lugar de 403 cuando se produzca un error en la autenticación. Los valores válidos son "http401WithBearerChallenge" o "http403".

   PATCH https://management.azure.com/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}?api-version=2023-11-01
   {
       "properties": {
           "disableLocalAuth": false,
           "authOptions": {
               "aadOrApiKey": {
                   "aadAuthFailureMode": "http401WithBearerChallenge"
               }
           }
       }
   }
   

Deshabilitar el control de acceso basado en roles

Es posible deshabilitar el control de acceso basado en roles para las operaciones del plano de datos y utilizar en su lugar la autenticación basada en claves. Puede hacerlo como parte de un flujo de trabajo de prueba, por ejemplo, para descartar problemas de permisos.

Invierta los pasos que siguió anteriormente para habilitar el acceso basado en roles.

1. Inicia sesión en Azure Portal y abre la página del servicio de búsqueda.

2. Seleccione Configuración, y luego seleccione Teclas en el panel de navegación izquierdo.

3. Seleccione API Keys (Claves de API).

Deshabilitación de la autenticación de clave de API

El acceso mediante clave, o autenticación local, puede deshabilitarse en su servicio si utiliza exclusivamente las funciones integradas y la autenticación de Microsoft Entra. Deshabilitar las claves de API hace que el servicio de búsqueda rechace todas las solicitudes relacionadas con datos que pasan una clave de API en el encabezado.

Las claves API de administración pueden deshabilitarse, pero no eliminarse. Las claves de API de consulta se pueden eliminar.

Se requieren permisos de Propietario o Colaborador para deshabilitar las características de seguridad.

Azure Portal

1. En Azure Portal, vaya al servicio de búsqueda.

2. En el panel de navegación izquierdo, seleccione Claves.

3. Seleccione Control de acceso basado en roles.

El cambio es efectivo inmediatamente, pero espere unos segundos antes de las pruebas. Suponiendo que tenga permiso para asignar roles como miembro con el rol Propietario, Administrador de servicios o Coadministrador, puede usar características del portal para probar el acceso basado en roles.

CLI de Azure

Para deshabilitar la autenticación basada en claves, establezca -disableLocalAuth en true. Esta es la misma sintaxis que el script "habilitar solo roles" presentado en la sección anterior.

az search service update `
  --name YOUR-SEARCH-SERVICE-NAME `
  --resource-group YOUR-RESOURCE-GROUP-NAME `
  --disable-local-auth

Para volver a habilitar la autenticación de claves, establezca -disableLocalAuth en falso. El servicio de búsqueda reanuda la aceptación de las claves de API en la solicitud automáticamente (suponiendo que se especifiquen).

Para obtener más información, consulte Administrar el servicio Azure AI Search con Azure CLI.

Azure PowerShell

Para deshabilitar la autenticación basada en claves, establezca DisableLocalAuth en true. Esta es la misma sintaxis que el script "habilitar solo roles" presentado en la sección anterior.

Set-AzSearchService `
  -Name YOUR-SEARCH-SERVICE-NAME `
  -ResourceGroupName YOUR-RESOURCE-GROUP-NAME `
  -DisableLocalAuth 1

Para volver a habilitar la autenticación de claves, establezca DisableLocalAuth en falso. El servicio de búsqueda reanuda la aceptación de las claves de API en la solicitud automáticamente (suponiendo que se especifiquen).

Para obtener más información, consulte Administrar el servicio Azure AI Search con PowerShell.

REST API

Para deshabilitar la autenticación basada en claves, establezca "disableLocalAuth" en true.

1. Obtenga la configuración del servicio para que pueda revisar la configuración actual.

   GET https://management.azure.com/subscriptions/{{subscriptionId}}/providers/Microsoft.Search/searchServices?api-version=2023-11-01
   

2. Use PATCH para actualizar la configuración del servicio. La siguiente modificación establece "authOptions" en null.

   PATCH https://management.azure.com/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}?api-version=2023-11-01
   {
       "properties": {
           "disableLocalAuth": true
       }
   }
   

Para volver a habilitar la autenticación de claves, establezca "disableLocalAuth" en falso. El servicio de búsqueda reanuda la aceptación de las claves de API en la solicitud automáticamente (suponiendo que se especifiquen).

Limitaciones

• El control de acceso basado en rol puede aumentar la latencia de algunas solicitudes. Cada combinación única de recursos de servicio (índice, indexador, etc.) y la entidad de servicio desencadena una comprobación de autorización. Estas comprobaciones de autorización pueden agregar hasta 200 milisegundos de latencia por solicitud.

• En raras ocasiones, cuando las solicitudes se originan a partir de un gran número de entidades de servicio diferentes, todas dirigidas a recursos de servicio diferentes (índices, indexadores, etc.), es posible que las comprobaciones de autorización den lugar a una limitación. La limitación solo se produciría si se usaran cientos de combinaciones únicas de recursos del servicio Search y entidades de servicio en un segundo.

---

Pasos siguientes

Configurar roles para el acceso a un servicio de búsqueda