Conexión a Búsqueda de Azure AI mediante el control de acceso basado en roles

Azure proporciona un sistema de autorización de control de acceso basado en roles global para todos los servicios que se ejecutan en la plataforma. En Búsqueda de Azure AI, puede asignar roles de Azure para:

• Administración del servicio
• Desarrollo o acceso de escritura a un servicio de búsqueda
• Acceso de solo lectura para consultas
• Acceso con ámbito a un solo índice

No se admite el acceso por usuario a través de los resultados de búsqueda (a veces denominado seguridad de nivel de fila o seguridad de nivel de documento) a través de asignaciones de roles. Una solución alternativa es crear filtros de seguridad que recortan los resultados por identidad del usuario y quitar los documentos para los que el solicitante no debe tener acceso. Consulte este ejemplo de chat de Enterprise con RAG para obtener una demostración.

Las asignaciones de roles son acumulativas y generalizadas en todas las herramientas y bibliotecas cliente. Puede asignar roles mediante cualquiera de los enfoques admitidos que se describen en la documentación del control de acceso basado en roles de Azure.

El acceso basado en roles es opcional, pero se recomienda. La alternativa es autenticación basada en claves, que es el valor predeterminado.

Requisitos previos

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

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

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.

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

Los roles para la administración del servicio (plano de control) son obligatorios. Los roles para las operaciones del plano de datos son opcionales. Debe habilitar el acceso basado en roles para poder asignar roles Colaborador del servicio de búsqueda, Colaborador de datos de índice de búsqueda o Lector de datos de índice de búsqueda para las operaciones de datos.

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

Plano de datos hace referencia a operaciones con relación al punto de conexión del servicio de búsqueda, como la indexación o las consultas, así como cualquier otra operación que se especifique en la API de REST de búsqueda o bibliotecas cliente equivalentes.

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 Control basado en roles o Ambos si desea flexibilidad.

   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.

El cambio es efectivo inmediatamente, pero espere unos segundos antes de asignar roles.

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

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

El cambio es efectivo inmediatamente, pero espere unos segundos antes de asignar roles.

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

Roles integrados usados en Búsqueda de Azure AI

Los siguientes son roles integrados. Si estos roles no son suficientes, cree un rol personalizado.

Role	Plano	Descripción
Propietario	Control y datos	Acceso total al plano de control del recurso de búsqueda, incluida la capacidad de asignar roles de Azure. Solo el rol Propietario puede habilitar o deshabilitar las opciones de autenticación o administrar roles para otros usuarios. Los administradores de suscripciones son miembros de manera predeterminada. En el plano de datos, este rol tiene el mismo acceso que el rol Colaborador del servicio de búsqueda. Incluye acceso a todas las acciones del plano de datos, excepto a la capacidad de consultar o indexar documentos.
Colaborador	Control y datos	El mismo nivel de acceso al plano de control que Propietario, menos la capacidad de asignar roles o cambiar opciones de autenticación. En el plano de datos, este rol tiene el mismo acceso que el rol Colaborador del servicio de búsqueda. Incluye acceso a todas las acciones del plano de datos, excepto a la capacidad de consultar o indexar documentos.
Lector	Control y datos	Acceso de lectura en todo el servicio, incluidas las métricas de búsqueda, las métricas de contenido (almacenamiento consumido, número de objetos) y las definiciones de objetos de los recursos del plano de datos (índices, indizadores, etc.). Sin embargo, no puede leer claves de API ni leer contenido dentro de los índices.
Colaborador del servicio Search	Control y datos	Acceso de lectura y escritura a definiciones de objetos (índices, alias, mapas de sinónimos, indizadores, orígenes de datos y conjuntos de aptitudes). Este rol es para los desarrolladores que crean objetos y para los administradores que administran servicios de búsqueda y sus objetos, pero sin acceso al contenido del índice. Use este rol para crear, eliminar y enumerar índices, obtener definiciones de índice, obtener información del servicio (estadísticas y cuotas), analizadores de pruebas, crear y administrar mapas de sinónimos, indexadores, orígenes de datos y conjuntos de aptitudes. Consulte Microsoft.Search/searchServices/* para obtener la lista de permisos.
Colaborador de datos de índice de búsqueda	Data	Acceso de lectura y escritura al contenido en índices. Este rol está pensado para desarrolladores o propietarios de índices que necesitan importar, actualizar o consultar la colección de documentos de un índice. Este rol no admite la creación o administración de índices. De forma predeterminada, este rol es para todos los índices de un servicio de búsqueda. Consulte Conceder acceso a un único índice para restringir el ámbito.
Lector de datos de índice de búsqueda	Data	Acceso de solo lectura para consultar índices de búsqueda. Este rol está pensado para aplicaciones y usuarios que ejecutan consultas. Este rol no admite el acceso de lectura a las definiciones de objetos. Por ejemplo, no puede leer una definición de índice de búsqueda ni obtener estadísticas del servicio de búsqueda. De forma predeterminada, este rol es para todos los índices de un servicio de búsqueda. Consulte Conceder acceso a un único índice para restringir el ámbito.

Nota:

Si deshabilita el acceso basado en roles de Azure, los roles integrados del plano de control (Propietario, Colaborador, Lector) seguirán estando disponibles. Al deshabilitar el acceso basado en roles, solo se quitan los permisos relacionados con datos asociados a esos roles. Si los roles del plano de datos se deshabilitan, el Colaborador del servicio de búsqueda será equivalente al Colaborador del plano de control.

Asignación de roles

En esta sección, asigne roles para:

• Administración del servicio
• Desarrollo o acceso de escritura a un servicio de búsqueda
• Acceso de solo lectura para consultas

Asignación de roles para la administración de servicios

Como administrador de servicios, puede crear y configurar un servicio de búsqueda y realizar todas las operaciones del plano de control descritas en la API de REST de administración o bibliotecas cliente equivalentes. En función del rol, también puede realizar la mayoría de las tareas de la API de REST de búsqueda en el plano de datos.

Azure Portal

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 (acceso total a todas las operaciones del plano de datos y del plano de control, excepto los permisos de consulta)
   • Colaborador (igual que propietario, excepto los permisos para asignar roles)
   • Lector (aceptable para la supervisión y visualización de métricas)

6. En la pestaña Miembros, seleccione la identidad de grupo o usuario de Microsoft Entra.

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

PowerShell

Al usar PowerShell para asignar roles, indique el nombre de usuario o grupo de Azure y el ámbito de la asignación para llamar a New-AzRoleAssignment.

En este ejemplo, se crea una asignación de roles con el ámbito de un servicio de búsqueda:

New-AzRoleAssignment -SignInName <email> `
    -RoleDefinitionName "Reader" `
    -Scope  "/subscriptions/<subscription>/resourceGroups/<resource-group>/providers/Microsoft.Search/searchServices/<search-service>"

Asignación de roles para el desarrollo

Las asignaciones de roles son globales en el servicio de búsqueda. Para permisos de ámbito a un único índice, use PowerShell o la CLI de Azure para crear un rol personalizado.

Importante

Si configura el acceso basado en rol para un servicio o índice y también proporciona una clave de API en la solicitud, el servicio de búsqueda usa la clave de API para autenticarse.

Azure Portal

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:

   • Colaborador del servicio de búsqueda (operaciones create-read-update-delete en índices, indexadores, conjuntos de aptitudes y otros objetos de nivel superior)
   • Colaborador de datos de índice de búsqueda (carga de documentos y ejecución de trabajos de indexación)
   • Lector de datos de índice de búsqueda (consultar un índice)

   Otra combinación de roles que proporciona acceso completo es Colaborador o Propietario, además del Lector de datos de índice de búsqueda.

6. En la pestaña Miembros, seleccione la identidad de grupo o usuario de Microsoft Entra.

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

8. Repita el proceso para los demás roles. La mayoría de los desarrolladores necesitan los tres.

PowerShell

Al usar PowerShell para asignar roles, indique el nombre de usuario o grupo de Azure y el ámbito de la asignación para llamar a New-AzRoleAssignment.

En este ejemplo, se crea una asignación de roles con el ámbito de un servicio de búsqueda:

New-AzRoleAssignment -SignInName <email> `
    -RoleDefinitionName "Search Index Data Contributor" `
    -Scope  "/subscriptions/<subscription>/resourceGroups/<resource-group>/providers/Microsoft.Search/searchServices/<search-service>"

En este ejemplo, se crea una asignación de roles con el ámbito de un índice específico:

New-AzRoleAssignment -SignInName <email> `
    -RoleDefinitionName "Search Index Data Contributor" `
    -Scope  "/subscriptions/<subscription>/resourceGroups/<resource-group>/providers/Microsoft.Search/searchServices/<search-service>/indexes/<index-name>"

Asignación de roles para consultas de solo lectura

Use el rol Lector de datos de índice de búsqueda para aplicaciones y procesos que solo necesitan acceso de lectura a un índice. Se trata de un rol muy específico. Concede acceso GET o POST a la colección de documentos de un índice de búsqueda para buscar, autocompletar y sugerencias.

No admite operaciones GET o LIST en un índice u otros objetos de nivel superior o estadísticas de servicio GET.

Azure Portal

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 el rol lector de datos del índice de búsqueda.

6. En la pestaña Miembros, seleccione la identidad de grupo o usuario de Microsoft Entra. Si va a configurar permisos para otro servicio, es posible que esté usando una identidad administrada por el usuario o un sistema. Elija esa opción si la asignación de roles es para una identidad de servicio.

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

PowerShell

Al usar PowerShell para asignar roles, indique el nombre de usuario o grupo de Azure y el ámbito de la asignación para llamar a New-AzRoleAssignment.

1. Obtenga el identificador de suscripción, el grupo de recursos del servicio de búsqueda y el nombre del servicio de búsqueda.

2. Obtenga el identificador de objeto del servicio de Azure, como Azure OpenAI.

    Get-AzADServicePrincipal -SearchString <YOUR AZURE OPENAI RESOURCE NAME>
   

3. Obtenga la definición de roles y revise los permisos para asegurarse de que este es el rol que desea.

   Get-AzRoleDefinition -Name "Search Index Data Reader"
   

4. Cree la asignación de roles, sustituyendo los valores válidos para los marcadores de posición.

   New-AzRoleAssignment -ObjectId YOUR-AZURE-OPENAI-OBJECT-ID -RoleDefinitionName "Search Index Data Reader" -Scope /subscriptions/YOUR-SUBSCRIPTION-ID/resourcegroups/YOUR-RESOURCE-GROUP/providers/Microsoft.Search/searchServices/YOUR-SEARCH-SERVICE-NAME
   

5. Este es un ejemplo de una asignación de roles cuyo ámbito es un índice específico:

   New-AzRoleAssignment -ObjectId YOUR-AZURE-OPENAI-OBJECT-ID `
       -RoleDefinitionName "Search Index Data Reader" `
       -Scope /subscriptions/YOUR-SUBSCRIPTION-ID/resourcegroups/YOUR-RESOURCE-GROUP/providers/Microsoft.Search/searchServices/YOUR-SEARCH-SERVICE-NAME/indexes/YOUR-INDEX-NAME
   

Prueba de asignaciones de roles

Use un cliente para probar las asignaciones de roles. Recuerde que los roles son acumulativos y que los roles heredados cuyo ámbito es la suscripción o el nivel de grupo de recursos no se pueden eliminar ni denegar en el nivel de recurso (servicio de búsqueda).

Asegúrese de registrar la aplicación cliente en Microsoft Entra ID y de tener asignaciones de roles en vigor antes de probar el acceso.

Azure Portal

1. Inicie sesión en Azure Portal.

2. Vaya al servicio de búsqueda.

3. En la página Información general, seleccione la pestaña Índices:

   • Los colaboradores del servicio de búsqueda pueden ver y crear cualquier objeto, pero no pueden cargar documentos ni consultar índices. Para comprobar los permisos, cree un índice de búsqueda.

   • Los colaboradores de datos de índice de búsqueda pueden cargar documentos. No hay ninguna opción de carga de documentos en el portal fuera del Asistente para importar datos, pero puede restablecer y ejecutar un indexador para confirmar los permisos de carga de documentos.

   • Los lectores de datos de índice de búsqueda pueden consultar el índice. Para comprobar los permisos, use el Explorador de búsqueda. Debería poder enviar consultas y ver los resultados, pero no debería poder ver la definición de índice ni crear uno.

REST API

En este enfoque se supone que Visual Studio Code tiene una extensión de cliente de REST.

1. Abra un shell de comandos para la CLI de Azure e inicie sesión en su suscripción de Azure.

   az login
   

2. Obtenga el id. de inquilino y el id. de suscripción. El identificador se usa como una variable en un paso futuro.

   az account show
   

3. Obtén un token de acceso.

   az account get-access-token --query accessToken --output tsv
   

4. En un nuevo archivo de texto de Visual Studio Code, pegue estas variables:

   @baseUrl = PASTE-YOUR-SEARCH-SERVICE-URL-HERE
   @index-name = PASTE-YOUR-INDEX-NAME-HERE
   @token = PASTE-YOUR-TOKEN-HERE
   

5. Pegue y, a continuación, envíe una solicitud que use las variables que ha especificado. Para el rol "Lector de datos de índice de búsqueda", puede enviar una consulta. Puede usar cualquier versión de API compatible.

   POST https://{{baseUrl}}/indexes/{{index-name}}/docs/search?api-version=2023-11-01 HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}
   
       {
            "queryType": "simple",
            "search": "motel",
            "filter": "",
            "select": "HotelName,Description,Category,Tags",
            "count": true
        }
   

Para obtener más información sobre cómo adquirir un token para un entorno específico, consulte Administración de un servicio de Búsqueda de Azure AI con API de REST y bibliotecas de autenticación de la plataforma de identidad de Microsoft.

.NET

1. Use el paquete Azure.Search.Documents.

2. Use Azure.Identity para .NET para la autenticación de tokens. Microsoft recomienda DefaultAzureCredential() para la mayoría de los escenarios.

3. Este es un ejemplo de una conexión de cliente mediante DefaultAzureCredential().

   // 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());
   

4. Este es otro ejemplo de uso de una credencial de secreto de cliente:

   var tokenCredential =  new ClientSecretCredential(aadTenantId, aadClientId, aadSecret);
   SearchClient srchclient = new SearchClient(serviceEndpoint, indexName, tokenCredential);
   

Python

1. Use azure.search.documents (Azure SDK para Python).

2. Use Azure.Identity para Python para la autenticación de tokens.

3. Use DefaultAzureCredential si el cliente de Python es una aplicación que se ejecuta en el lado servidor. Habilite la autenticación interactiva si la aplicación se ejecuta en un explorador.

4. Este es un ejemplo:

   from azure.search.documents import SearchClient
   from azure.identity import DefaultAzureCredential
   
   credential = DefaultAzureCredential()
   endpoint = "https://<mysearch>.search.windows.net"
   index_name = "myindex"
   client = SearchClient(endpoint=endpoint, index_name=index_name, credential=credential)
   

JavaScript

1. Use la versión 11.3 de @azure/search-documents (Azure SDK para JavaScript).

2. Use Azure.Identity para JavaScript para la autenticación de tokens.

3. Si usa React, utilice InteractiveBrowserCredential para la autenticación de Microsoft Entra en Search. Consulte Cuándo usar @azure/identity para obtener más información.

Java

1. Use azure-search-documents (Azure SDK para Java).

2. Use Azure.Identity para Java para la autenticación de tokens.

3. Microsoft recomienda DefaultAzureCredential para las aplicaciones que se ejecutan en Azure.

Prueba como usuario actual

Si ya es Colaborador o Propietario del servicio de búsqueda, puede presentar un token de portador de la identidad de usuario para la autenticación en Azure AI Search.

1. Obtenga un token de portador para el usuario actual mediante la CLI de Azure:

   az account get-access-token --scope https://search.azure.com/.default
   

   O mediante PowerShell:

   Get-AzAccessToken -ResourceUrl https://search.azure.com
   

2. En un nuevo archivo de texto de Visual Studio Code, pegue estas variables:

   @baseUrl = PASTE-YOUR-SEARCH-SERVICE-URL-HERE
   @index-name = PASTE-YOUR-INDEX-NAME-HERE
   @token = PASTE-YOUR-TOKEN-HERE
   

3. Pegue y, a continuación, envíe una solicitud para confirmar el acceso. Esta es una que consulta el índice hotels-quickstart.

   POST https://{{baseUrl}}/indexes/{{index-name}}/docs/search?api-version=2023-11-01 HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}
   
       {
            "queryType": "simple",
            "search": "motel",
            "filter": "",
            "select": "HotelName,Description,Category,Tags",
            "count": true
        }
   

Concesión de acceso a un único índice

En algunos escenarios, es posible que desee limitar el acceso de una aplicación a un único recurso, como un índice.

El portal no admite actualmente asignaciones de roles en este nivel de granularidad, pero se puede realizar con PowerShell o la CLI de Azure.

En PowerShell, use New-AzRoleAssignment, proporcionando el nombre de usuario o grupo de Azure y el ámbito de la asignación.

1. Cargue los módulos Azure y AzureAD y conéctese a su cuenta de Azure:

   Import-Module -Name Az
   Import-Module -Name AzureAD
   Connect-AzAccount
   

2. Agregue una asignación de roles limitada a un índice individual:

   New-AzRoleAssignment -ObjectId <objectId> `
       -RoleDefinitionName "Search Index Data Contributor" `
       -Scope  "/subscriptions/<subscription>/resourceGroups/<resource-group>/providers/Microsoft.Search/searchServices/<search-service>/indexes/<index-name>"
   

Crear un rol personalizado

Si los roles integrados no proporcionan la combinación adecuada de permisos, puede crear un rol personalizado para admitir las operaciones que necesita.

En este ejemplo se clona el rol Lector de datos de índice de búsqueda y, luego, se agrega la posibilidad de enumerar los índices por el nombre. Normalmente, enumerar los índices de un servicio de búsqueda se considera un derecho administrativo.

Azure Portal

Estos pasos se derivan del artículo Creación o actualización de roles personalizados de Azure mediante Azure Portal. La clonación a partir de un rol existente se admite en una página del servicio de búsqueda.

Estos pasos crean un rol personalizado que aumenta los derechos de consulta de búsqueda para incluir índices de enumeración por nombre. Normalmente, la enumeración de índices se considera una función de administrador.

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

2. En el panel de navegación izquierdo, seleccione Access Control (IAM).

3. En la barra de acciones, seleccione Roles.

4. Haga clic con el botón derecho en Lector de datos de índice de búsqueda (u otro rol) y seleccione Clonar para abrir el Asistente para crear un rol personalizado.

5. En la pestaña Aspectos básicos, proporcione un nombre para el rol personalizado, como "Explorador de datos de índice de búsqueda" y, luego, seleccione Siguiente.

6. En la pestaña "Permisos", seleccione Agregar permiso.

7. En la pestaña "Agregar permisos", busque y seleccione el icono Búsqueda de Microsoft.

8. Establezca los permisos del rol personalizado. En la parte superior de la página, con la selección de Acciones predeterminada:

   • En Microsoft.Search/operations, seleccione Leer: Enumerar todas las operaciones disponibles.
   • En Microsoft.Search/searchServices/indexes, seleccione Leer : Leer índice.

9. En la misma página, cambie a Acciones de datos y, en Microsoft.Search/searchServices/indexes/documents, seleccione Leer: Leer documentos.

   El código JSON resultante tendrá un aspecto similar al siguiente:

   {
    "properties": {
        "roleName": "search index data explorer",
        "description": "",
        "assignableScopes": [
            "/subscriptions/0000000000000000000000000000000/resourceGroups/free-search-svc/providers/Microsoft.Search/searchServices/demo-search-svc"
        ],
        "permissions": [
            {
                "actions": [
                    "Microsoft.Search/operations/read",
                    "Microsoft.Search/searchServices/indexes/read"
                ],
                "notActions": [],
                "dataActions": [
                    "Microsoft.Search/searchServices/indexes/documents/read"
                ],
                "notDataActions": []
            }
        ]
      }
    }
   

10. Seleccione Revisar y crear para crear el rol. Ahora puede asignar usuarios y grupos al rol.

Azure PowerShell

En el ejemplo de PowerShell se muestra la sintaxis JSON para crear un rol personalizado que es un clon del Lector de datos de índice de búsqueda, pero con la posibilidad de enumerar todos los índices por nombre.

1. Revise la lista de permisos atómicos para determinar cuáles necesita. En este ejemplo, necesitará lo siguiente:

   "Microsoft.Search/operations/read",
   "Microsoft.Search/searchServices/read",
   "Microsoft.Search/searchServices/indexes/read"
   

2. Configure una sesión de PowerShell para crear el rol personalizado. Para instrucciones detalladas, consulte Azure PowerShell.

3. Proporcione la definición de roles como un documento JSON. El ejemplo siguiente muestra la sintaxis para crear un rol personalizado con PowerShell.

{
  "Name": "Search Index Data Explorer",
  "Id": "88888888-8888-8888-8888-888888888888",
  "IsCustom": true,
  "Description": "List all indexes on the service and query them.",
  "Actions": [
      "Microsoft.Search/operations/read",
      "Microsoft.Search/searchServices/read"
  ],
  "NotActions": [],
  "DataActions": [
      "Microsoft.Search/searchServices/indexes/read"
  ],
  "NotDataActions": [],
  "AssignableScopes": [
    "/subscriptions/{subscriptionId1}"
  ]
}

Nota:

Si el ámbito asignable está a nivel de índice, la acción de datos debe ser "Microsoft.Search/searchServices/indexes/documents/read".

REST API

1. Revise la lista de permisos atómicos para determinar cuáles necesita.

2. Consulte Creación o actualización de roles personalizados de Azure con la API REST para obtener los pasos.

3. Clone o cree un rol, o use JSON para especificar el rol personalizado (consulte la pestaña PowerShell para la sintaxis JSON).

CLI de Azure

1. Revise la lista de permisos atómicos para determinar cuáles necesita.

2. Consulte Creación o actualización de roles personalizados de Azure con la CLI de Azure para obtener los pasos.

3. Clone o cree un rol, o use JSON para especificar el rol personalizado (consulte la pestaña PowerShell para la sintaxis JSON).

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

El acceso a claves o la autenticación local se pueden deshabilitar en el servicio si usa los roles integrados 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.

Nota:

Las claves de API de administrador solo se pueden deshabilitar, no eliminar. Las claves de API de consulta se pueden eliminar.

Para deshabilitar características se necesitan permisos de Propietario o Colaborador.

Para deshabilitar la autenticación basada en claves, use Azure Portal o la API REST de administración.

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.

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 modificación siguiente establecerá "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
       }
   }
   

Las solicitudes que incluyen solo una clave de API, sin token de portador, producen el error HTTP 401.

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

Acceso condicional

Se recomienda el Acceso condicional de Microsoft Entra en caso de necesitar aplicar directivas organizativas, como la autenticación multifactor.

Para habilitar una directiva de acceso condicional para Búsqueda de Azure AI, siga estos pasos:

1. Inicie sesión en Azure Portal.

2. Busque Acceso condicional de Microsoft Entra.

3. Seleccione Directivas.

4. Seleccione Nueva directiva.

5. En la sección Aplicaciones en la nube o acciones de la directiva, agregue Azure AI Search como una aplicación en la nube en función de cómo quiera configurar la directiva.

6. Actualice los parámetros restantes de la directiva. Por ejemplo, especifique a qué usuarios y grupos se aplica esta directiva.

7. Guarde la directiva.

Importante

Si el servicio de búsqueda tiene asignada una identidad administrada, el servicio de búsqueda específico se mostrará como una aplicación en la nube que se puede incluir o excluir como parte de la directiva de acceso condicional. Las directivas de acceso condicional no se pueden aplicar en un servicio de búsqueda específico. En su lugar, asegúrese de seleccionar la aplicación general en la nube Azure AI Search.

Solución de problemas de control de acceso basado en rol

Al desarrollar aplicaciones que usan el control de acceso basado en rol para la autenticación, pueden producirse algunos problemas comunes:

• Si el token de autorización procede de una identidad administrada y los permisos adecuados se asignaron recientemente, es posible que estas asignaciones de permisos tarden varias horas en surtir efecto.

• La configuración predeterminada de un servicio de búsqueda es la autenticación basada en claves. Si no ha cambiado la configuración de clave predeterminada a Control de acceso basado en rol o Ambos, todas las solicitudes que usan la autenticación basada en roles se deniegan automáticamente independientemente de los permisos subyacentes.