Conexión a Foundry IQ (Búsqueda de Azure AI) mediante roles

Nota:

Foundry IQ (Búsqueda de Azure AI) proporciona API directas de indexación y consulta junto con las API de origen de conocimiento y base de conocimiento de nivel superior para la recuperación administrada. Use el portal de Azure, las API REST o SDK de Azure para configurar estas funcionalidades o conectar agentes a las bases de conocimiento en el portal de Microsoft Foundry.

Foundry IQ (Búsqueda de Azure AI) admite el control de acceso basado en rol a través de Microsoft Entra ID. El acceso basado en roles es opcional, pero se recomienda. La alternativa es autenticación basada en claves, que es el valor predeterminado.

Si asigna varios roles a una entidad de seguridad, se combinan los permisos. Las asignaciones de roles se aplican en todas las herramientas y bibliotecas cliente.

En este artículo se explica cómo asignar roles integrados para la administración de servicios, el desarrollo y el acceso de consulta de solo lectura y de recuperación. También proporciona pasos para crear roles personalizados y probar asignaciones de roles.

Sugerencia

Una entidad de servicio de aplicación o una identidad administrada se pueden autenticar como llamador de búsqueda con la asignación de roles adecuada. Esta autorización de la entidad que realiza la llamada es independiente de la identidad de usuario delegada que se usa para el filtrado nativo de permisos de documento. Consulte Roles de token en tiempo de consulta y flujos de permisos.

Requisitos previos

Roles integrados

Los roles son una colección de permisos que afectan al plano de control o al plano de datos:

  • Plano de control: Operaciones para el aprovisionamiento, la configuración y la administración del servicio. Las operaciones del plano de control incluyen la creación o eliminación de servicios Foundry IQ, la enumeración de claves de API y la administración de la configuración de red y autenticación. Disponible a través de las API REST de Azure Resource Manager, Search Management REST API y bibliotecas cliente de SDK de Azure equivalentes.

  • Plano de datos: Operaciones en el punto de conexión del servicio Foundry IQ. Las operaciones del plano de datos se dividen en dos categorías: administración de objetos y acceso a contenido. Disponible a través de las API REST del servicio Search y las bibliotecas cliente de SDK de Azure equivalentes.

Descripciones de roles

Los siguientes roles integrados conceden permisos a Foundry IQ. Los roles del plano de control siempre están disponibles, mientras que los roles del plano de datos requieren que se habilite el acceso basado en roles en el servicio Foundry IQ. Puede combinar roles integrados para un acceso más amplio o crear un rol personalizado con los permisos específicos que necesita.

Rol Plano Descripción
Owner Control
  • Acceso total al plano de control, incluida la capacidad de asignar roles y cambiar la configuración de autenticación.
  • Los administradores de suscripciones tienen este rol de forma predeterminada.
  • Puede administrar claves de API.
  • No se pueden crear objetos de búsqueda, cargar documentos, índices de consulta ni recuperarlos de bases de conocimiento.
Colaborador Control
  • El mismo nivel de acceso al plano de control que el propietario, salvo la capacidad de asignar roles.
Lector Control
  • Acceso de solo lectura al plano de control.
  • Puede ver las métricas de servicio y las definiciones de objetos.
  • No se pueden ver ni administrar claves de API, cargar documentos, índices de consulta ni recuperar de bases de conocimiento.
Colaborador del servicio de búsqueda Control y datos
  • Acceso total al plano de control. El acceso al plano de datos se limita a la administración de objetos.
  • Puede crear índices, indexadores, conjuntos de aptitudes, bases de conocimiento y otros objetos de búsqueda.
  • Puede recuperar claves de API de administrador y de consulta mediante operaciones del plano de control.
  • No se pueden cargar documentos, índices de consulta ni recuperarse de bases de conocimiento directamente a través del acceso basado en roles.
  • Para obtener la lista de permisos completos, consulte Microsoft.Search/searchServices/*.
Colaborador de datos del índice de búsqueda Datos
  • Acceso a contenido de lectura y escritura
  • Puede cargar documentos, índices de consulta y recuperarse de bases de conocimiento.
  • No se pueden modificar las definiciones de objeto ni recuperar claves de administrador.
Lector de datos de índice de búsqueda Datos
  • Acceso a contenido de solo lectura.
  • Puede consultar índices y recuperar datos de las bases de conocimiento.
  • No se pueden cargar documentos, modificar definiciones de objeto ni recuperar claves de administrador.

Importante

  • El propietario, el colaborador y el colaborador del servicio de búsqueda pueden recuperar claves de administrador, que proporcionan acceso de lectura y escritura completo al plano de datos. Conceda solo estos roles a usuarios de confianza.
  • De forma predeterminada, los roles del plano de datos se aplican a todos los índices del servicio Foundry IQ. Para definir el ámbito de Colaborador de datos de índice de búsqueda o de Lector de datos de índice de búsqueda en un único índice, consulte Concesión de acceso a un único índice.

Resumen de permisos

Use la tabla siguiente para buscar rápidamente qué rol proporciona los permisos que necesita.

Permisos Propietario/Colaborador Lector Colaborador del servicio de búsqueda Colaborador de datos de índice de búsqueda Lector de datos de índice de búsqueda
Creación y configuración de servicios Foundry IQ ✅ ❌ ✅ ❌ ❌
Acceso al servicio en el portal de Azure ✅ ✅ ✅ ❌ ❌
Visualización de las propiedades, las métricas y el punto de conexión del servicio ✅ ✅ ✅ ❌ ❌
Enumerar todos los objetos del servicio ✅ ✅ ✅ ❌ ❌
Cuotas de acceso y estadísticas de servicio ✅ ❌ ✅ ❌ ❌
Visualización, copia y regeneración de claves ✅ ❌ ✅ ❌ ❌
Establecimiento de opciones de autenticación ✅ ❌ ✅ ❌ ❌
Visualización de roles, directivas y definiciones ✅ ✅ ✅ ❌ ❌
Configuración de la seguridad de red y conexiones privadas ✅ ❌ ✅ ❌ ❌
Creación, ejecución y administración de objetos de búsqueda 1 ❌ ❌ ✅ ❌ ❌
Carga de datos para la indexación 2 ❌ ❌ ❌ ✅ ❌
Consultar un índice ❌ ❌ ❌ ✅ ✅
Recuperación de una base de conocimiento ❌ ❌ ❌ ✅ ✅
Omitir filtros de permisos con lectura con privilegios elevados ❌ ❌ ❌ ✅ ❌

1 Incluye índices, indexadores, orígenes de datos, conjuntos de aptitudes, alias, mapas de sinónimos, sesiones de depuración, bases de conocimiento y orígenes de conocimiento. Los indexadores también admiten operaciones de ejecución y restablecimiento.

2 Un propietario o colaborador puede ejecutar el Asistente para importar datos para crear y cargar índices, aunque no puedan cargar documentos en otros clientes. De forma similar, los indexadores pueden escribir en cualquier índice del servicio Foundry IQ, independientemente de las asignaciones de roles por índice. En ambos casos, el servicio Foundry IQ (no el usuario) realiza las acciones del plano de datos mediante sus Microsoft.Search/searchServices/indexes/documents/* permisos.

Asignar roles integrados

En esta sección, ustedes asignarán roles para:

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

Los siguientes roles le permiten crear, configurar y administrar un servicio Foundry IQ. Estos roles son jerárquicos, por lo que debe seleccionar uno en función del nivel de acceso que necesite.

Rol identificación
Owner 8e3af657-a8ff-443c-a75c-2fe8c4bcb635
Colaborador b24988ac-6180-42a0-ab88-20f7382dd24c
Lector acdd72a7-3385-48ef-bd42-f606fba81ae7
  1. Vaya al servicio Foundry IQ en el portal de Azure.

  2. En el panel izquierdo, seleccione Access control (IAM).

  3. Seleccione + Añadir>Añadir asignación de rol.

    Captura de pantalla de la página Control de acceso (IAM) para asignar roles de administración de servicios.

  4. Seleccione un rol: Propietario, Colaborador o Lector.

  5. En la pestaña Members, seleccione la identidad de usuario o grupo de Microsoft Entra. Si va a configurar permisos para otro servicio de Azure, seleccione una identidad administrada asignada por el sistema o asignada por el usuario.

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

Asignación de roles para el desarrollo

Los siguientes roles permiten crear objetos de búsqueda, cargar documentos, índices de consulta y recuperar de bases de conocimiento. Asigne los tres roles para cubrir toda la gama de tareas de desarrollo.

Rol identificación
Search Service Contributor 7ca78c08-252a-4471-8644-bb5ff32d4ba0
Colaborador de datos del índice de búsqueda 8ebe5a00-799e-43f5-93ac-243d3dce84a7
Lector de datos de índice de búsqueda 1407120a-92aa-4202-b7e9-c0e197c71c8f
  1. Vaya al servicio Foundry IQ en el portal de Azure.

  2. En el panel izquierdo, seleccione Access control (IAM).

  3. Seleccione + Añadir>Añadir asignación de rol.

    Captura de pantalla de la página Control de acceso (IAM) para asignar roles de desarrollo.

  4. Seleccione Colaborador del servicio de búsqueda.

  5. En la pestaña Members, seleccione la identidad de usuario o grupo de Microsoft Entra. Si va a configurar permisos para otro servicio de Azure, seleccione una identidad administrada asignada por el sistema o asignada por el usuario.

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

  7. Repita estos pasos para asignar colaborador de datos de índice de búsqueda y lector de datos de índice de búsqueda.

Asignar roles para acceso de solo lectura

Use el siguiente rol para aplicaciones y procesos que solo necesitan acceso de lectura a índices y bases de conocimiento. Las operaciones admitidas incluyen búsqueda, búsqueda, autocompletar y sugerencias para índices y recuperación de bases de conocimiento.

Rol identificación
Lector de datos de índice de búsqueda 1407120a-92aa-4202-b7e9-c0e197c71c8f
  1. Vaya al servicio Foundry IQ en el portal de Azure.

  2. En el panel izquierdo, seleccione Access control (IAM).

  3. Seleccione + Añadir>Añadir asignación de rol.

    Captura de pantalla de la página Control de acceso (IAM) para asignar roles de acceso a datos de solo lectura.

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

  5. En la pestaña Members, seleccione la identidad de usuario o grupo de Microsoft Entra. Si va a configurar permisos para otro servicio de Azure, seleccione una identidad administrada asignada por el sistema o asignada por el usuario.

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

Prueba de asignaciones de roles

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

Antes de continuar, configure la aplicación para las conexiones sin claves y tenga asignaciones de roles en vigor.

  1. Vaya al servicio Foundry IQ en el portal de Azure.

  2. En el panel izquierdo, seleccione Índices de administración> debúsqueda para probar los permisos relacionados con el índice:

    • Los colaboradores del servicio de búsqueda pueden crear, modificar y eliminar objetos de búsqueda, pero no pueden cargar documentos ni ejecutar consultas. 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 de Azure fuera del asistente "Import data", 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 índices. 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 definiciones de índice ni crear índices.

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.

Actualmente, el portal de Azure no admite asignaciones de roles en el nivel de índice. Use la CLI de Azure, PowerShell o la API REST para asignar roles limitados a un único índice.

Operaciones del indexador y de delimitación por índice

Las asignaciones de roles por índice solo se aplican a operaciones de API directas, como consultas o cargas de documentos de usuarios o aplicaciones. Los indexadores no están restringidos por permisos por índice porque funcionan con credenciales de nivel de servicio.

Un usuario con el rol Colaborador del servicio de búsqueda puede crear indizadores que escriban en cualquier índice del servicio Foundry IQ, incluso los índices en los que ese usuario no tenga ninguna asignación de roles por índice.

Aplique el principio de privilegio mínimo a los autores de documentos y a los administradores que pueden cambiar orígenes de datos, indexadores, asignaciones de campos, conjuntos de aptitudes o proyecciones. El acceso de escritura de nivel de índice no establece la propiedad por documento: una clave selecciona un registro para una escritura, no si ese escritor posee su contenido o concede. Para la ingesta de blobs, siga Revisión de la configuración de ingesta.

Los índices independientes no constituyen un aislamiento completo cuando los indexadores de nivel de servicio, las credenciales compartidas o los administradores pueden escribir en ellos. Revise esos privilegios compartidos, así como el acceso directo a los índices, al separar conjuntos de datos con distintos niveles de confianza.

Para un aislamiento estricto de datos entre índices, tenga en cuenta estos enfoques:

  • Utilice servicios de Foundry IQ independientes para equipos o usuarios que requieran aislamiento de nivel de índice.
  • Asigne colaborador del servicio de búsqueda solo a los administradores que administran indizadores.
  • Use el control de acceso de nivel de documento con filtros de seguridad para restringir los resultados de la consulta dentro de un índice compartido.

Crear un rol personalizado

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

En los ejemplos siguientes se clona el Lector de datos de índice de búsqueda y, a continuación, se agrega la capacidad de enumerar índices por nombre. Normalmente, la enumeración de los índices en un servicio Foundry IQ se considera un derecho administrativo.

  1. Inicie sesión en el portal de Azure y vaya al servicio Foundry IQ.

  2. En el panel izquierdo, seleccione Access control (IAM).

  3. En la pestaña Roles , busque Lector de datos de índice de búsqueda u otro rol, seleccione los puntos suspensivos (...)y, a continuación, seleccione Clonar.

  4. En la pestaña Basics, escriba un nombre para el rol personalizado, como "Search Index Data Explorer" y seleccione Next.

  5. En la pestaña Permisos , seleccione Agregar permisos.

  6. En el panel Agregar permisos, seleccione el icono Búsqueda de Microsoft.

  7. Con Acciones seleccionadas en la parte superior, establezca los permisos siguientes:

    • En Microsoft.Search/operations, seleccione Read : Enumerar todas las operaciones disponibles.
    • En Microsoft.Search/searchServices/indexes, seleccione Read : Read Index.
  8. Cambie a Data Actions en la parte superior y, en Microsoft.Search/searchServices/indexes/documents, seleccione Read : Read Documents.

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

    {
        "properties": {
            "roleName": "Search Index Data Explorer",
            "description": "List all indexes on the service and query them.",
            "assignableScopes": [
                "/subscriptions/<subscription>/resourceGroups/<resource-group>"
            ],
            "permissions": [
                {
                    "actions": [
                        "Microsoft.Search/operations/read",
                        "Microsoft.Search/searchServices/indexes/read"
                    ],
                    "notActions": [],
                    "dataActions": [
                        "Microsoft.Search/searchServices/indexes/documents/read"
                    ],
                    "notDataActions": []
                }
            ]
        }
    }
    
  9. Seleccione Agregar para cerrar el panel.

  10. Seleccione Revisar y crear para crear el rol.

    Ahora puede asignar usuarios y grupos al rol. Para obtener más información sobre estos pasos, consulte Crear o actualizar Azure roles personalizados mediante el portal de Azure.

Creación de una directiva de acceso condicional

Si necesita aplicar directivas organizativas, como la autenticación multifactor, use Acceso condicional de Microsoft Entra.

Para crear una directiva de acceso condicional para Foundry IQ:

  1. Inicie sesión en el portal Azure.

  2. Busque Acceso condicional de Microsoft Entra.

  3. En la página Información general , seleccione Crear nueva directiva.

  4. En Aplicaciones o acciones en la nube, agregue Foundry IQ como una aplicación en la nube, en función de cómo quiera configurar la directiva.

  5. Actualice los parámetros restantes de su política. Por ejemplo, especifique a qué usuarios y grupos se aplica la directiva.

  6. Guarde la directiva.

Importante

Si el servicio Foundry IQ tiene asignada una identidad administrada, el servicio Foundry IQ específico aparece como una aplicación en la nube. Sin embargo, al seleccionar ese servicio Foundry IQ específico no se aplica la directiva. En su lugar, seleccione la aplicación en la nube de Foundry IQ general para aplicar directivas de acceso condicional al servicio Foundry IQ.

Solución de problemas

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

  • La configuración predeterminada de un servicio Foundry IQ es la autenticación basada en claves. Si no cambia esta configuración a Ambos o Control de acceso basado en rol, todas las solicitudes que usan la autenticación basada en rol se deniegan automáticamente, independientemente de los permisos subyacentes.

  • Si la solicitud incluye una clave de API junto con las credenciales basadas en roles, el servicio se autentica mediante la clave . Quite la clave de API de los encabezados de solicitud para usar la autenticación basada en roles.

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

  • Si las consultas con permisos de nivel de documento no devuelven resultados esperados, use Colaborador de datos de índice de búsqueda o cree un rol personalizado con permisos elevados para investigar.

Paso siguiente

En este artículo se explica cómo asignar roles para las operaciones del plano de control y del plano de datos en Foundry IQ. Para obtener instrucciones completas sobre cómo agregar acceso basado en roles al código de la aplicación: