Introducción a la seguridad de documentos de chat para Python

Al compilar una aplicación de chat de mediante el patrón de generación aumentada de recuperación (RAG) con sus propios datos, asegúrese de que cada usuario recibe una respuesta basada en sus permisos. Siga el proceso de este artículo para agregar el control de acceso de documentos a la aplicación de chat.

• usuario autorizado: esta persona debe tener acceso a las respuestas contenidas en los documentos de la aplicación de chat.

  

• usuario no autorizado: esta persona no debe tener acceso a respuestas de documentos protegidos que no tienen autorización para ver.

  

Nota

En este artículo se utilizan una o varias plantillas de aplicación de IA de como base para los ejemplos y la orientación del artículo. Las plantillas de aplicación de IA proporcionan implementaciones de referencia bien mantenidas que son fáciles de implementar. Ayudan a garantizar un punto de partida de alta calidad para las aplicaciones de inteligencia artificial.

Introducción a la arquitectura

Sin una característica de seguridad de documentos, la aplicación de chat empresarial tiene una arquitectura sencilla mediante Azure AI Search y Azure OpenAI. Una respuesta se determina a partir de consultas a Azure AI Search donde se almacenan los documentos, en combinación con una respuesta de un modelo GPT de Azure OpenAI. No se usa ninguna autenticación de usuario en este flujo sencillo.

Para agregar seguridad a los documentos, debe actualizar la aplicación de chat empresarial:

• Agregue la autenticación de cliente a la aplicación de chat con Microsoft Entra.
• Agregue lógica del lado servidor para rellenar un índice de búsqueda con acceso de usuario y grupo.

Búsqueda de Azure AI no proporciona permisos nativos a nivel de documento y no puede variar los resultados de búsqueda desde dentro de un índice por permisos de usuario. En su lugar, la aplicación puede usar filtros de búsqueda para asegurarse de que un documento sea accesible para un usuario específico o un grupo específico. Dentro del índice de búsqueda, cada documento debe tener un campo filtrable que almacene información de identidad de usuario o grupo.

Dado que la autorización no está contenida de forma nativa en Azure AI Search, debe agregar un campo para contener información de usuario o grupo y, a continuación, filtrar los documentos que no coincidan. Para implementar esta técnica, debe:

• Cree un campo de control de acceso a documentos en el índice dedicado a almacenar los detalles de los usuarios o grupos con acceso a documentos.
• Rellene el campo de control de acceso del documento con los detalles de usuario o grupo pertinentes.
• Actualice este campo de control de acceso siempre que haya cambios en los permisos de acceso de usuario o grupo.

Si las actualizaciones de índice se programan con un indexador, los cambios se aplican en la siguiente ejecución del indexador. Si no usa un indexador, debe volver a indexar manualmente.

En este artículo, el proceso de protección de documentos en Azure AI Search se hace posible con los scripts de ejemplo y, que usted, en su calidad de administrador de búsqueda, ejecutaría. Los scripts asocian un único documento a una sola identidad de usuario. Puede tomar estos scripts y aplicar sus propios requisitos de seguridad y producción para escalar según sus necesidades.

Determinación de la configuración de seguridad

La solución proporciona variables de entorno booleanas para activar las características necesarias para la seguridad del documento en este ejemplo.

Parámetro	Propósito
AZURE_USE_AUTHENTICATION	Cuando se establece en true, habilita el inicio de sesión de usuario en la aplicación de chat y la autenticación de Azure App Service. Habilita Use oid security filter en la aplicación de chat Configuración del desarrollador.
AZURE_ENFORCE_ACCESS_CONTROL	Cuando se establece en true, requiere autenticación para cualquier acceso a documentos. La configuración de Developer para el identificador de objeto (OID) y la seguridad de grupo están activadas y deshabilitadas para que no se puedan deshabilitar desde la interfaz de usuario.
AZURE_ENABLE_GLOBAL_DOCUMENTS_ACCESS	Cuando se establece en true, esta opción permite a los usuarios autenticados buscar en documentos que no tienen asignados controles de acceso, incluso cuando se requiere control de acceso. Este parámetro solo se debe usar cuando AZURE_ENFORCE_ACCESS_CONTROL está habilitado.
AZURE_ENABLE_UNAUTHENTICATED_ACCESS	Cuando se establece en true, esta configuración permite a los usuarios no autenticados usar la aplicación, incluso cuando se aplica el control de acceso. Este parámetro solo se debe usar cuando AZURE_ENFORCE_ACCESS_CONTROL está habilitado.

Use las secciones siguientes para comprender los perfiles de seguridad admitidos en este ejemplo. Este artículo configura el perfil Enterprise.

Empresa: cuenta requerida + filtro de documento

Cada usuario del sitio debe iniciar sesión. El sitio contiene contenido público para todos los usuarios. El filtro de seguridad de nivel de documento se aplica a todas las solicitudes.

Variables de entorno:

• AZURE_USE_AUTHENTICATION=true
• AZURE_ENABLE_GLOBAL_DOCUMENTS_ACCESS=true
• AZURE_ENFORCE_ACCESS_CONTROL=true

Uso mixto: cuenta opcional + filtro de documento

Cada usuario del sitio puede iniciar sesión. El sitio contiene contenido público para todos los usuarios. El filtro de seguridad de nivel de documento se aplica a todas las solicitudes.

Variables de entorno:

• AZURE_USE_AUTHENTICATION=true
• AZURE_ENABLE_GLOBAL_DOCUMENTS_ACCESS=true
• AZURE_ENFORCE_ACCESS_CONTROL=true
• AZURE_ENABLE_UNAUTHENTICATED_ACCESS=true

Prerrequisitos

Hay disponible un entorno contenedor de desarrollo con todas las dependencias necesarias para completar este artículo. Puede ejecutar el contenedor de desarrollo en GitHub Codespaces (en un explorador) o localmente mediante Visual Studio Code.

Para usar este artículo, necesita los siguientes requisitos previos:

• Una suscripción de Azure. Crear uno gratis.
• Permisos de cuenta de Azure: la cuenta de Azure debe tener:
  • Permiso para administrar aplicaciones en Microsoft Entra ID.
  • Permisos Microsoft.Authorization/roleAssignments/write, como Administrador de acceso de usuarios o Propietario.

Necesita más requisitos previos en función de su entorno de desarrollo preferido.

GitHub Codespaces (recomendado)

• GitHub

Visual Studio Code

• Azure Developer CLI.
• Docker Desktop. Inicie Docker Desktop si aún no se está ejecutando.
• Visual Studio Code.
• Extensión de contenedores de desarrollo

Apertura de un entorno de desarrollo

Use las instrucciones siguientes para implementar un entorno de desarrollo preconfigurado que contenga todas las dependencias necesarias para completar este artículo.

GitHub Codespaces (recomendado)

GitHub Codespaces ejecuta un contenedor de desarrollo administrado por GitHub con Visual Studio Code para web como interfaz de usuario. Para el entorno de desarrollo más sencillo, use GitHub Codespaces para que tenga las herramientas de desarrollo y las dependencias correctas preinstaladas para completar este artículo.

Importante

Todas las cuentas de GitHub pueden usar GitHub Codespaces durante hasta 60 horas gratuitas cada mes con dos instancias principales. Para obtener más información, consulte Almacenamiento y horas de núcleo incluidas mensualmente en GitHub Codespaces.

1. Inicie el proceso para crear un nuevo espacio de código de GitHub en la rama main del repositorio Azure-Samples/azure-search-openai-demo GitHub.

2. Haga clic con el botón derecho en el siguiente botón y seleccione Abrir el enlace en nuevas ventanas para tener el entorno de desarrollo y la documentación disponibles al mismo tiempo.

   

3. En la página Crear codespace, revise las opciones de configuración de codespace y, después, seleccione Crear nuevo codespace.

   

4. Espere a que se inicie Codespace. Este proceso de inicio puede tardar unos minutos.

5. En el terminal de la parte inferior de la pantalla, inicie sesión en Azure con la CLI para desarrolladores de Azure.

   azd auth login
   

6. Complete el proceso de autenticación.

7. Las tareas restantes de este artículo tienen lugar en el contexto de este contenedor de desarrollo.

Visual Studio Code

La extensión Dev Containers para Visual Studio Code requiere que Docker se instale en el equipo local. La extensión hospeda el contenedor de desarrollo localmente mediante el host de Docker con las herramientas de desarrollo y las dependencias correctas preinstaladas para completar este artículo.

1. Cree un nuevo directorio local en su computadora para el proyecto.

   mkdir my-intelligent-app && cd my-intelligent-app
   

2. Abra Visual Studio Code en ese directorio.

   code .
   

3. Abra un nuevo terminal en Visual Studio Code.

4. Ejecute el siguiente comando AZD para llevar el repositorio de GitHub al equipo local.

   azd init -t azure-search-openai-demo
   

5. Abra la paleta de Comandos y busque y seleccione Dev Containers: Abrir carpeta en contenedor para abrir el proyecto en un contenedor de desarrollo. Espere hasta que se abra el contenedor de desarrollo antes de continuar.

6. Inicie sesión en Azure con la CLI para desarrolladores de Azure.

   azd auth login
   

   Copie el código del terminal y péguelo en un explorador. Siga las instrucciones para autenticarse con su cuenta de Azure.

7. Los ejercicios restantes de este proyecto tienen lugar en el contexto de este contenedor de desarrollo.

Obtención de información necesaria con la CLI de Azure

Obtenga el identificador de suscripción y el identificador de inquilino con el siguiente comando de la CLI de Azure. Copie el valor para usarlo como tu valor AZURE_TENANT_ID.

az account list --query "[].{subscription_id:id, name:name, tenantId:tenantId}" -o table

Si recibe un error sobre la política de acceso condicional de su tenant, necesita un segundo tenant sin política de acceso condicional.

• Su primer tenant, asociado a su cuenta de usuario, se utiliza para la variable de entorno AZURE_TENANT_ID.
• Su segundo tenant, sin acceso condicional, se utiliza para la variable de entorno AZURE_AUTH_TENANT_ID para acceder a Microsoft Graph. Para arrendatarios con una directiva de acceso condicional, busque el ID de un segundo arrendatario sin una directiva de acceso condicional o cree un nuevo arrendatario.

Establecimiento de variables de entorno

1. Ejecute los siguientes comandos para configurar la aplicación para el perfil de Enterprise.

   azd env set AZURE_USE_AUTHENTICATION true
   azd env set AZURE_ENABLE_GLOBAL_DOCUMENTS_ACCESS true
   azd env set AZURE_ENFORCE_ACCESS_CONTROL true
   

2. Ejecute el siguiente comando para establecer el cliente, lo que autoriza el inicio de sesión del usuario en el entorno de aplicación hospedado. Reemplace <YOUR_TENANT_ID> por el identificador de inquilino.

   azd env set AZURE_TENANT_ID <YOUR_TENANT_ID>
   

Nota

Si tiene una política de acceso condicional en su tenant de usuario, necesita especificar un tenant de autenticación.

Implementación de la aplicación de chat en Azure

La implementación consta de los pasos siguientes:

• Cree los recursos de Azure.
• Cargue los documentos.
• Cree las aplicaciones de identidad de Microsoft Entra (cliente y servidor).
• Active la identidad del recurso de hospedaje.

1. Ejecute el siguiente comando de la CLI para desarrolladores de Azure para aprovisionar los recursos de Azure e implementar el código fuente.

   azd up
   

2. Utilice la siguiente tabla para responder a las solicitudes de implementación AZD.

   Pronto	Respuesta
   Nombre del entorno	Use un nombre corto con información de identificación como el alias y la aplicación. Y el ejemplo es tjones-secure-chat.
   Suscripción	Seleccione una suscripción en la que se van a crear los recursos.
   Ubicación de los recursos de Azure	Seleccione una ubicación cerca de usted.
   Ubicación de documentIntelligentResourceGroupLocation	Seleccione una ubicación cerca de usted.
   Ubicación de openAIResourceGroupLocation	Seleccione una ubicación cerca de usted.

   Espere 5 o 10 minutos después de que la aplicación se implemente para permitir que la aplicación se inicie.

3. Una vez que la aplicación se implemente correctamente, aparece una dirección URL en el terminal.

4. Seleccione la dirección URL etiquetada (✓) Done: Deploying service webapp para abrir la aplicación de chat en un explorador.

   

5. Por favor, acepte la ventana emergente de autenticación de la aplicación.

6. Cuando aparezca la aplicación de chat, observe en la esquina superior derecha que el usuario ha iniciado sesión.

7. Abra ajustes del desarrollador y observe que ambas de las siguientes opciones están seleccionadas e inhabilitadas para modificación:

   • Usar filtro de seguridad oid
   • Uso del filtro de seguridad de grupos

8. Seleccione la tarjeta con ¿Qué hace un administrador de productos?.

9. Recibe una respuesta como: Los orígenes proporcionados no contienen información específica sobre el rol de administrador de productos en Contoso Electronics.

   

Abrir el acceso a un documento para un usuario

Active sus permisos para el documento exacto para que pueda obtener la respuesta. Necesitas varias piezas de información:

• Azure Storage
  • Nombre de cuenta
  • Nombre del contenedor
  • Blob/documento URL para role_library.pdf
• Identificador del usuario en Microsoft Entra ID

Cuando se conozca esta información, actualice el campo oids del índice de búsqueda de Azure AI en el documento role_library.pdf.

Obtención de la dirección URL de un documento en el almacenamiento

1. En la carpeta .azure en la raíz del proyecto, busque el directorio del entorno y abra el archivo .env con ese directorio.

2. Busque la entrada AZURE_STORAGE_ACCOUNT y copie su valor.

3. Use los siguientes comandos de la CLI de Azure para obtener la dirección URL del blob role_library.pdf en el contenedor de content.

   az storage blob url \
       --account-name <REPLACE_WITH_AZURE_STORAGE_ACCOUNT \
       --container-name 'content' \
       --name 'role_library.pdf' 
   

   Parámetro	Propósito
   --nombre-de-cuenta	Nombre de la cuenta de Azure Storage.
   --container-name	El nombre del contenedor de este ejemplo es content.
   --nombre	El nombre del blob de este paso es role_library.pdf.

4. Copie la dirección URL del blob para usarla más adelante.

Obtención del identificador de usuario

1. En la aplicación de chat, seleccione Configuración del desarrollador.
2. En la sección Notificaciones de token de ID, copie su parámetro objectidentifier. Este parámetro se conoce en la sección siguiente como USER_OBJECT_ID.

Proporcionar acceso de usuario a un documento en Azure Search

1. Use el siguiente script para cambiar el campo oids de Azure AI Search para role_library.pdf para que tenga acceso a él.

   ./scripts/manageacl.sh \
       -v \
       --acl-type oids \
       --acl-action add \
       --acl <REPLACE_WITH_YOUR_USER_OBJECT_ID> \
       --url <REPLACE_WITH_YOUR_DOCUMENT_URL>
   

   Parámetro	Propósito
   -v	Salida detallada.
   --acl-type	OID de grupo o usuario: oids.
   --acl-action	Agregar a un campo índice de búsqueda. Otras opciones incluyen remove, remove_ally list.
   --acl	Usuario o grupo USER_OBJECT_ID.
   --url	Ubicación del archivo en Azure Storage, como https://MYSTORAGENAME.blob.core.windows.net/content/role_library.pdf. No rodear la dirección URL con comillas en el comando de la CLI.

2. La salida de la consola de este comando es similar a la siguiente:

   Loading azd .env file from current environment...
   Creating Python virtual environment "app/backend/.venv"...
   Installing dependencies from "requirements.txt" into virtual environment (in quiet mode)...
   Running manageacl.py. Arguments to script: -v --acl-type oids --acl-action add --acl 00000000-0000-0000-0000-000000000000 --url https://mystorage.blob.core.windows.net/content/role_library.pdf
   Found 58 search documents with storageUrl https://mystorage.blob.core.windows.net/content/role_library.pdf
   Adding acl 00000000-0000-0000-0000-000000000000 to 58 search documents
   

3. Opcionalmente, use el siguiente comando para comprobar que el permiso aparece para el archivo en Azure AI Search.

   ./scripts/manageacl.sh \
       -v \
       --acl-type oids \
       --acl-action list \
       --acl <REPLACE_WITH_YOUR_USER_OBJECT_ID> \
       --url <REPLACE_WITH_YOUR_DOCUMENT_URL>
   

   Parámetro	Propósito
   -v	Salida detallada.
   --acl-type	OID de grupo o usuario: oids.
   --acl-action	Enumerar un campo de índice de búsqueda oids. Otras opciones incluyen remove, remove_ally list.
   --acl	Parámetro USER_OBJECT_ID de grupo o usuario.
   --url	La ubicación del archivo en que se muestra, como https://MYSTORAGENAME.blob.core.windows.net/content/role_library.pdf. No rodear la dirección URL con comillas en el comando de la CLI.

4. La salida de la consola de este comando es similar a la siguiente:

   Loading azd .env file from current environment...
   Creating Python virtual environment "app/backend/.venv"...
   Installing dependencies from "requirements.txt" into virtual environment (in quiet mode)...
   Running manageacl.py. Arguments to script: -v --acl-type oids --acl-action view --acl 00000000-0000-0000-0000-000000000000 --url https://mystorage.blob.core.windows.net/content/role_library.pdf
   Found 58 search documents with storageUrl https://mystorage.blob.core.windows.net/content/role_library.pdf
   [00000000-0000-0000-0000-000000000000]
   

   La matriz al final de la salida incluye el parámetro USER_OBJECT_ID y se usa para determinar si el documento se usa en la respuesta con Azure OpenAI.

Compruebe que Azure AI Search contiene su USER_OBJECT_ID

1. Abra el Azure Portal y busque AI Search.

2. Seleccione el recurso de búsqueda en la lista.

3. Seleccione Administración de búsqueda>Índices.

4. Seleccione gptkbindex.

5. Seleccione Ver>vista JSON.

6. Reemplace el código JSON por el siguiente json:

   {
     "search": "*",
     "select": "sourcefile, oids",
     "filter": "oids/any()"
   }
   

   Este JSON busca en todos los documentos donde el campo oids tiene cualquier valor y devuelve los campos sourcefile y oids.

7. Si el role_library.pdf no tiene tu OID, vuelve a la sección Proporcionar acceso de usuario a un documento en Azure Search y completa los pasos.

Comprobación del acceso de usuario al documento

Si completó los pasos pero no vio la respuesta correcta, compruebe que el parámetro USER_OBJECT_ID se ha establecido correctamente en Azure AI Search para role_library.pdf.

1. Vuelva a la aplicación de chat. Es posible que tenga que volver a iniciar sesión.

2. Escriba la misma consulta para que el contenido de role_library se use en la respuesta de Azure OpenAI: What does a product manager do?.

3. Visualice el resultado, que ahora incluye la respuesta adecuada del documento de la biblioteca de roles.

   

Limpieza de recursos

Los pasos siguientes le guiarán por el proceso de limpieza de los recursos que usó.

Limpieza de recursos de Azure

Los recursos de Azure creados en este artículo se facturan a su suscripción de Azure. Si no espera necesitar estos recursos en el futuro, elimínelos para evitar incurrir en más cargos.

Ejecute el siguiente comando de la CLI para desarrolladores de Azure para eliminar los recursos de Azure y quitar el código fuente.

azd down --purge

Limpieza de GitHub Codespaces y Visual Studio Code

Los pasos siguientes le guiarán por el proceso de limpieza de los recursos que usó.

GitHub Codespaces

La eliminación del entorno de GitHub Codespaces garantiza que pueda maximizar la cantidad de derechos de horas gratuitas por núcleo que obtiene para su cuenta.

Importante

Para obtener más información sobre los derechos de la cuenta de GitHub, consulte Almacenamiento y horas de núcleo incluidas mensualmente en GitHub Codespaces.

1. Inicie sesión en el panel de GitHub Codespaces.

2. Busque los codespaces que se ejecutan actualmente a partir del repositorio de GitHub Azure-Samples/azure-search-openai-demo.

   

3. Abra el menú contextual del espacio de código y seleccione Eliminar.

   

Visual Studio Code

No es necesariamente necesario limpiar el entorno local, pero puede detener el contenedor de desarrollo en ejecución y volver a ejecutar Visual Studio Code en el contexto de un área de trabajo local.

1. Abra la paleta Comando y busque los comandos de Contenedores de desarrollo.

2. Seleccione Contenedores de desarrollo: Reabrir carpeta localmente.

   

Sugerencia

Visual Studio Code detiene el contenedor de desarrollo en ejecución, pero el contenedor todavía existe en Docker en un estado detenido. Siempre tiene la opción de eliminar la instancia de contenedor, la imagen de contenedor y los volúmenes de Docker para liberar más espacio en el equipo local.

Obtener ayuda

Este repositorio de muestras ofrece información para la resolución de problemas.

Solución de problemas

En esta sección se ofrece solución de problemas específicos de este artículo.

Proporcione el tenant de autenticación

Cuando su autenticación se encuentra en un tenant separado de la aplicación de hospedaje, debe configurar ese tenant de autenticación con el siguiente proceso.

1. Ejecute el siguiente comando para configurar la muestra para utilizar una segunda entidad como la entidad de autenticación.

   azd env set AZURE_AUTH_TENANT_ID <REPLACE-WITH-YOUR-TENANT-ID>
   

   Parámetro	Propósito
   AZURE_AUTH_TENANT_ID	Si se establece AZURE_AUTH_TENANT_ID, es el arrendatario encargado de hospedar la aplicación.

2. Vuelva a implementar la solución con el siguiente comando:

   azd up
   

Contenido relacionado

• Cree una aplicación de chat con Azure OpenAI utilizando la arquitectura de solución de mejores prácticas.
• Aprenda sobre el control de acceso en aplicaciones de inteligencia artificial generativa con Azure AI Search.
• Cree una solución de Azure OpenAI preparada para la empresa con Azure API Management.
• Consulte Búsqueda de Azure AI: Superar el vector de búsqueda con capacidades híbridas de recuperación y clasificación.