Conexión a Búsqueda de Azure AI mediante roles

Azure proporciona una autenticación global y un control de acceso basado en roles a través de Microsoft Entra ID para todos los servicios que se ejecutan en la plataforma. En este artículo, aprenda qué roles proporcionan acceso al contenido de búsqueda y a la administración en Azure AI Search.

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

• Un servicio de búsqueda en cualquier región, en cualquier nivel, habilitado para el acceso basado en roles.

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

Asignación de roles en Azure Portal

Los pasos siguientes funcionan para todas las asignaciones de roles.

1. Inicie sesión en Azure Portal.

2. Vaya al servicio de búsqueda.

3. Habilitación de acceso basado en roles.

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

5. Seleccione Agregar>Agregar asignación de roles para iniciar el asistenteAgregar asignación de roles.

   

6. Seleccione un rol. Puede asignar varios mandantes de seguridad, ya sean usuarios o identidades gestionadas a una función en una sola pasada por el asistente, pero tiene que repetir estos pasos para cada función que defina.

7. En la pestaña Miembros, seleccione la identidad de grupo o usuario de Microsoft Entra. Si está configurando permisos para otro servicio de Azure, seleccione una identidad gestionada por el sistema o por el usuario.

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

Roles integrados usados en la búsqueda

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 del servicio Search o en las bibliotecas de cliente Azure SDK equivalentes.

El plano de control hace referencia a la administración de recursos de Azure, como crear o configurar un servicio de búsqueda.

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.

Combine estos roles para obtener permisos suficientes para su caso de uso.

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.

Resumen

Permisos	Lector de datos de índice de búsqueda	Colaborador de datos de índice de búsqueda	Colaborador del servicio Search	Propietario/Colaborador	Lector
Visualización del recurso en Azure Portal	❌	❌	✅	✅	✅
Ver las propiedades de los recursos/métricas/punto de conexión	❌	❌	✅	✅	✅
Enumerar todos los objetos del recurso	❌	❌	✅	✅	✅
Cuotas de acceso y estadísticas de servicio	❌	❌	✅	✅	❌
Leer/consultar un índice	✅	✅	❌	❌	❌
Carga de datos para la indexación	❌	✅	❌	❌	❌
Crear o editar índices o alias	❌	❌	✅	✅	❌
Crear, editar y ejecutar indexadores/fuentes de datos/conjuntos de habilidades	❌	❌	✅	✅	❌
Crear o editar mapas de sinónimos	❌	❌	✅	✅	❌
Crear o editar sesiones de depuración	❌	❌	✅	✅	❌
Creación o administración de implementaciones	❌	❌	✅	✅	❌
Creación o configuración de recursos de Búsqueda de Azure AI	❌	❌	✅	✅	❌
Ver, copiar o regenerar claves en Claves	❌	❌	✅	✅	❌
Ver roles/directivas/definiciones	❌	❌	✅	✅	❌
Establecimiento de opciones de autenticación	❌	❌	✅	✅	❌
Configuración de conexiones privadas	❌	❌	✅	✅	❌
Configuración de la seguridad de red	❌	❌	✅	✅	❌

Los Propietarios y Colaboradores otorgan los mismos permisos, salvo que sólo los Propietarios pueden asignar funciones.

Los propietarios y colaboradores pueden crear, leer, actualizar y eliminar objetos en el portal Azure si las claves API están habilitadas. Azure Portal usa claves en llamadas internas a las API del plano de datos. Si posteriormente configura Búsqueda de Azure AI para que utilice "solo roles", el propietario y el colaborador no podrán gestionar objetos en Azure Portal utilizando solo esas asignaciones de roles. La solución consiste en asignar más funciones, como Lector de datos de índices de búsqueda, Contribuidor de datos de índices de búsqueda y Contribuidor de servicios de búsqueda.

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. Si es propietario o colaborador, también puede realizar la mayoría de las tareas de la API REST de búsqueda de planos de datos en el portal de Azure.

Role	ID
Owner	8e3af657-a8ff-443c-a75c-2fe8c4bcb635
Contributor	b24988ac-6180-42a0-ab88-20f7382dd24c
Reader	acdd72a7-3385-48ef-bd42-f606fba81ae7

Azure Portal

1. Inicie sesión en Azure Portal.

2. Asigne estos roles:

   • 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)

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.

Tarea	Role	ID
Operaciones CRUD	Search Service Contributor	7ca78c08-252a-4471-8644-bb5ff32d4ba0
Carga de documentos, ejecución de trabajos de indexación	Search Index Data Contributor	8ebe5a00-799e-43f5-93ac-243d3dce84a7
Consultar un índice	Search Index Data Reader	1407120a-92aa-4202-b7e9-c0e197c71c8f

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

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. Asigne estos roles:

   • 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)

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.

Role	ID
Search Index Data Reader con PowerShell	1407120a-92aa-4202-b7e9-c0e197c71c8f

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.

Esta sección proporciona los pasos básicos para configurar la asignación de roles y se incluye para mayor claridad, pero se recomienda usar Búsqueda de Azure AI sin claves para obtener instrucciones completas sobre cómo configurar su aplicación para el acceso basado en rol.

Azure Portal

1. Inicie sesión en Azure Portal.

2. Seleccione el rol Lector de datos de índice de búsqueda.

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).

Configure la aplicación para conexiones sin claves y cuente con asignaciones de roles en vigor antes de realizar las pruebas.

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 Azure Portal fuera del Asistente para la importación de 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. Pegue estas variables en un nuevo archivo de texto de Visual Studio Code.

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

5. 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=2024-07-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. Pegue estas variables en un nuevo archivo de texto de Visual Studio Code.

   @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=2024-07-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.

Azure 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. Copie o cree un rol, o use JSON para especificar el rol personalizado (consulte la pestaña PowerShell para ver 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. Consulte la pestaña de PowerShell para ver la sintaxis JSON.

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.

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.

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.