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

Nota:

Búsqueda de Azure AI está disponible a través del portal de Azure, las API REST y los SDK de Azure. También respalda Foundry IQ, la capa de conocimiento administrada que transforma el contenido empresarial en bases de conocimiento reutilizables y compatibles con permisos para agentes en el portal de Microsoft Foundry.

Búsqueda de Azure AI admite el control de acceso basado en roles 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

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 de búsqueda, 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 relacionadas con el punto de conexión del servicio Search. 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 Búsqueda de Azure AI. 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 de búsqueda. 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
Propietario 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 Search 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 de í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 de búsqueda. 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 de Búsqueda de Azure AI ✅ ❌ ✅ ❌ ❌
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 ❌ ❌ ❌ ✅ ✅
Eludir los filtros de permisos con lectura con privilegios elevados (versión preliminar) ❌ ❌ ❌ ✅ ❌

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. Del mismo modo, los indexadores pueden escribir en cualquier índice del servicio de búsqueda, independientemente de las asignaciones de roles por índice. En ambos casos, el servicio de búsqueda (no el usuario) realiza las acciones del plano de datos mediante sus permisos de Microsoft.Search/searchServices/indexes/documents/*.

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 de búsqueda. Estos roles son jerárquicos, por lo que debe seleccionar uno en función del nivel de acceso que necesite.

Rol identificación
Propietario 8e3af657-a8ff-443c-a75c-2fe8c4bcb635
Colaborador b24988ac-6180-42a0-ab88-20f7382dd24c
Lector acdd72a7-3385-48ef-bd42-f606fba81ae7

  1. Vaya al servicio de búsqueda en el portal 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
Colaborador del servicio Search 7ca78c08-252a-4471-8644-bb5ff32d4ba0
Colaborador de datos de í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 de búsqueda en el portal 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 de búsqueda en el portal 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 puede eliminar ni denegar roles heredados que tienen como ámbito el nivel de suscripción o de grupo de recursos a nivel de recurso (servicio de búsqueda).

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

  1. Vaya al servicio de búsqueda en el portal 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 indexadores que escriban en cualquier índice del servicio de búsqueda, incluso índices en los que ese usuario no tenga ninguna asignación de roles por índice.

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

  • Use servicios de búsqueda 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, enumerar los índices de un servicio de búsqueda se considera un derecho administrativo.

  1. Inicie sesión en el portal Azure y vaya al servicio de búsqueda.

  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 Búsqueda de Azure AI:

  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 Búsqueda de Azure AI como una aplicación en la nube, según cómo quiera configurar su política.

  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 de búsqueda tiene asignada una identidad administrada, el servicio de búsqueda específico aparece como una aplicación en la nube. Sin embargo, al seleccionar ese servicio de búsqueda específico no se aplica la directiva. En su lugar, seleccione la aplicación en la nube general Búsqueda de Azure AI para aplicar directivas de acceso condicional al servicio de búsqueda.

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 de búsqueda 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 (versión preliminar) para investigar.

Paso siguiente

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

Conecte la aplicación para Búsqueda de Azure AI mediante identidades

  • Last updated on