Autorización del acceso a una aplicación de búsqueda mediante Microsoft Entra ID

Ahora, las aplicaciones de búsqueda basadas en Azure AI Search pueden usar la Plataforma de identidad de Microsoft para accesos autenticados y autorizados. En Azure, el proveedor de identidades es Microsoft Entra ID. Una ventaja clave del uso de Microsoft Entra ID es que ya no necesita almacenar las credenciales y las claves de API en el código. Microsoft Entra autentica la entidad de seguridad (un usuario, grupo o entidad de servicio) que ejecuta la aplicación. Si la autenticación se realiza correctamente, Microsoft Entra ID devuelve el token de acceso a la aplicación y, a continuación, aplicación y la aplicación puede usar dicho token para autorizar las solicitudes de Azure AI Search.

Este artículo le muestra cómo configurar su cliente para Microsoft Entra ID:

• Para la autenticación, cree una identidad administrada para la aplicación. También es posible usar un tipo diferente de objeto de entidad de seguridad, pero en este artículo se usan identidades administradas porque eliminan la necesidad de administrar las credenciales.

• Para la autorización, asigne un rol de Azure a la identidad administrada que conceda permisos para ejecutar consultas o administrar trabajos de indexación.

• Actualice el código de cliente para llamar a TokenCredential(). Por ejemplo, puede empezar a trabajar con searchClient(endpoint, new DefaultAzureCredential()) para autenticarse a través de un identificador de Microsoft Entra ID mediante Azure.Identity.

Configuración del acceso basado en roles para el plano de datos

Se aplica a: Colaborador de datos de índice de búsqueda, Lector de datos de índice de búsqueda y Colaborador de servicio de búsqueda.

En este paso, configure su servicio de búsqueda para que reconozca un encabezado Authorization en solicitudes de datos que proporcionen un token de acceso de OAuth2.

Azure Portal

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

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

   

3. Elija una opción de Control de acceso de API. Se recomienda la opción Ambos si quiere flexibilidad o necesita migrar aplicaciones.

   Opción	Descripción
   Clave de API	(predeterminado) Requiere un administrador o claves de API de consulta en el encabezado de solicitud para la autorización. No se usa ningún rol.
   Control de acceso basado en rol	Requiere la pertenencia a una asignación de roles para completar la tarea, según se describe en el paso siguiente. También requiere un encabezado de autorización.
   Ambos	Las solicitudes son válidas mediante una clave de API o el control de acceso basado en roles.

El cambio es efectivo inmediatamente, pero espere unos segundos antes de las pruebas.

Todas las llamadas de red de las operaciones del servicio de búsqueda y el contenido respetan la opción que seleccione: claves de API, token de portador o una si de ellas selecciona Ambos.

Al habilitar el control de acceso basado en roles en el portal, el modo de error es "http401WithBearerChallenge" si se produce un error en la autorización.

REST API

Use la API de REST de administración Crear o actualizar servicio para configurar su servicio.

Todas las llamadas a la API REST de administración se autentican mediante Microsoft Entra ID, con permisos de colaborador o de propietario. Para obtener ayuda para configurar solicitudes autenticadas en un cliente de REST, consulte Administración de Búsqueda de Azure AI 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"
               }
           }
       }
   }
   

Creación de una entidad administrada

En este paso, cree una identidad administrada para la aplicación cliente.

1. Inicie sesión en Azure Portal.

2. Busque Identidades administradas.

3. Seleccione Crear.

4. Asigne un nombre a la identidad administrada y seleccione una región. Seleccione Crear.

   

Asignación de un rol a la identidad administrada

A continuación, conceda acceso al servicio de búsqueda a su identidad administrada del cliente. Azure AI Search tiene varios roles integrados. También puede crear un rol personalizado.

Se recomienda conceder permisos mínimos. Si la aplicación solo necesita controlar las consultas, debe asignar el rol de Lector de datos de índice de búsqueda. Como alternativa, si el cliente necesitase acceso de lectura y escritura para un índice de búsqueda, debería usar el rol Colaborador de datos de índice de búsqueda.

1. Inicie sesión en Azure Portal.

2. Vaya al servicio de búsqueda.

3. Seleccione Control de acceso (IAM) en el panel de navegación izquierdo.

4. Seleccione Agregar>Agregar asignación de roles.

   

5. Seleccione un rol aplicable:

   • Propietario

   • Colaborador

   • Lector

   • Colaborador del servicio Search

   • Colaborador de datos de índice de búsqueda

   • Lector de datos de índice de búsqueda

     Nota:

     Propietario, Colaborador, Lector y Colaborador del servicio de búsqueda son roles de plano de control y no proporcionan acceso a los datos de índices de búsqueda. Para el acceso a datos, elija el rol Colaborador de datos de índice de búsqueda o Lector de datos de índice de búsqueda. Para obtener más información sobre el ámbito y el propósito de cada rol, consulte roles integrados usados en la búsqueda.

6. En la pestaña Miembros, seleccione la identidad administrada que desea conceder acceso al servicio de búsqueda.

7. En la pestaña Revisión y asignación, seleccione Revisión y asignación para asignar el rol.

Puede asignar varios roles, como Colaborador del servicio de búsqueda y Colaborador de datos del índice de búsqueda, si la aplicación necesita acceso completo a los servicios de búsqueda, objetos y contenido.

También puede asignar roles mediante PowerShell.

Configuración de la autenticación de Microsoft Entra en su cliente

Una vez que tenga una identidad administrada y una asignación de roles en el servicio de búsqueda, estará listo para agregar código a la aplicación para autenticar la entidad de seguridad y adquirir un token de OAuth 2.0.

Use las siguientes bibliotecas cliente para el control de acceso basado en roles:

• azure.search.documents (Azure SDK para .NET)
• azure-search-documents (Azure SDK para Java)
• azure/search-documents (Azure SDK para JavaScript)
• azure.search.documents (Azure SDK para Python)

Nota:

Para obtener más información sobre el flujo de concesión de código OAuth 2.0 que usa Microsoft Entra ID, consulte Autorización del acceso a aplicaciones web de Microsoft Entra mediante el flujo de concesión de código OAuth 2.0.

SDK de .NET

Las instrucciones siguientes hacen referencia a un ejemplo de C# existente para mostrar los cambios de código.

1. Como punto de partida, clone el código fuente de la sección C# de Inicio rápido: Búsqueda de texto completo mediante los SDK de Azure.

   El ejemplo actualmente usa la autenticación basada en claves y AzureKeyCredential para crear SearchClient y SearchIndexClient, pero puede realizar un pequeño cambio para cambiar a la autenticación basada en roles.

2. Actualice el paquete NuGet Azure.Search.Documents a la versión 11.4 o posterior.

3. Importe la biblioteca Azure.Identity para obtener acceso a otras técnicas de autenticación.

4. En lugar de usar AzureKeyCredential al comienzo de Main() en Program.cs, use DefaultAzureCredential como en el fragmento de código siguiente:

   // Create a SearchIndexClient to send create/delete index commands
   SearchIndexClient adminClient = new SearchIndexClient(serviceEndpoint, new DefaultAzureCredential());
   // Create a SearchClient to load and query documents
   SearchClient srchclient = new SearchClient(serviceEndpoint, indexName, new DefaultAzureCredential());
   

Pruebas locales

Las identidades administradas asignadas por el usuario solo funcionan en entornos de Azure. Si ejecutase este código localmente, DefaultAzureCredential revertirá a la autenticación con sus credenciales. Asegúrese también de proporcionarse el acceso necesario al servicio de búsqueda si planea ejecutar el código localmente.

1. Compruebe que la cuenta tenga asignaciones de roles para ejecutar todas las operaciones en el ejemplo de inicio rápido. Para crear y consultar un índice, use "Lector de datos de índice de búsqueda" y "Colaborador de datos de índice de búsqueda".

2. Vaya a Herramientas>Opciones>Azure Service Authentication para elegir la cuenta de inicio de sesión de Azure.

Ahora debería poder ejecutar el proyecto desde Visual Studio en el sistema local utilizando el control de acceso basado en roles para la autorización.

Nota:

La documentación de Azure.Identity incluye más detalles sobre DefaultAzureCredential y el uso de la autenticación de Microsoft Entra con SDK de Azure para .NET. DefaultAzureCredential está diseñado para simplificar la introducción al SDK mediante el control de escenarios comunes con comportamientos predeterminados razonables. Los desarrolladores que quieran tener más control o cuyo escenario no esté servido por la configuración predeterminada deben usar otros tipos de credenciales.

REST API

El uso de un SDK de Azure simplifica el flujo de OAuth 2.0, pero también puede programar directamente con el protocolo de la aplicación. En Plataforma de identidad de Microsoft y flujo de credenciales de cliente de OAuth 2.0 puede encontrar detalles completos.

1. Comience obteniendo un token de la Plataforma de identidad de Microsoft:

   POST /[tenant id]/oauth2/v2.0/token HTTP/1.1
   Host: login.microsoftonline.com
   Content-Type: application/x-www-form-urlencoded
   
   client_id=[client id]
   &scope=https%3A%2F%2Fsearch.azure.com%2F.default
   &client_secret=[client secret]
   &grant_type=client_credentials
   

   El ámbito necesario es "https://search.azure.com/.default".

2. Ahora que tiene un token, está listo para emitir una solicitud al servicio de búsqueda.

   GET https://[service name].search.windows.net/indexes/[index name]/docs?[query parameters]
   Content-Type: application/json   
   Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...
   

Consulte también

• Uso del control de acceso basado en roles de Azure en Azure AI Search
• Autorización del acceso a aplicaciones web de Microsoft Entra mediante el flujo de concesión de código OAuth 2.0
• Integración con Microsoft Entra ID
• Roles personalizados en los recursos de Azure