Integración con SharePoint

LibreChat proporciona una integración de nivel empresarial con SharePoint Online y OneDrive for Business, lo que permite a los usuarios explorar, seleccionar y adjuntar archivos de su entorno de Microsoft 365 directamente dentro de las conversaciones de forma fluida.

Descripción general

La integración con SharePoint permite a los usuarios:

• Explorar bibliotecas de documentos de SharePoint y archivos de OneDrive
• Seleccionar varios archivos a la vez (hasta 10 por defecto)
• Ver el progreso de descarga en tiempo real
• Adjuntar archivos de SharePoint a las conversaciones
• Mantenga la seguridad empresarial con controles de acceso adecuados

Requisitos previos

Antes de configurar la integración con SharePoint, asegúrese de tener:

1. Autenticación de Azure Entra ID configurada y funcionando
2. Reutilización de tokens habilitada (OPENID_REUSE_TOKENS=true)
3. Un ámbito de API expuesto para LibreChat, como api://<client-id>/access_as_user
4. Acceso de administrador a su inquilino de Azure para los permisos de la aplicación
5. HTTPS habilitado (requerido para entornos de producción)

Configuración del Registro de Aplicaciones de Azure

Paso 1: Configurar los permisos de la API

1. Navegue hasta el registro de su aplicación en el Azure Portal
2. Ve a API permissions en el menú de la izquierda
3. Haz clic en Add a permission

Paso 2: Exponer y otorgar un ámbito (scope) de la API de LibreChat

El flujo on-behalf-of necesita el token de acceso inicial de OpenID para dirigirse a la API de su aplicación LibreChat, no a Microsoft Graph. Exponga un scope de API para que Azure pueda emitir un token con LibreChat como audiencia.

1. Ve a Expose an API en el menú de la izquierda
2. Establezca el Application ID URI en api://<client-id> si aún no está configurado
3. Haz clic en Add a scope
4. Asigne al ámbito el nombre access_as_user
5. Guarda el scope, luego copia el valor completo del scope:

api://<client-id>/access_as_user

Luego, otorga ese scope al registro de la aplicación:

1. Volver a API permissions
2. Haz clic en Add a permission
3. Seleccione APIs my organization uses
4. Busque y seleccione su registro de aplicación de LibreChat
5. Elija Delegated permissions
6. Seleccione access_as_user
7. Haz clic en Add permissions

Utilice el valor de alcance completo api://<client-id>/access_as_user en OPENID_SCOPE más adelante en esta guía.

Paso 3: Agregar permisos de SharePoint

Para la interfaz del selector de archivos:

1. Seleccione SharePoint de la lista de API
2. Elija Delegated permissions
3. Buscar y seleccionar:
   • AllSites.Read - Leer elementos en todas las colecciones de sitios
4. Haz clic en Add permissions

Paso 4: Agregar permisos de Microsoft Graph

Para descargas de archivos:

1. Haz clic en Add a permission de nuevo
2. Seleccione Microsoft Graph
3. Elija Delegated permissions
4. Buscar y seleccionar:
   • Files.Read.All - Leer todos los archivos a los que el usuario puede acceder
5. Haz clic en Add permissions

Paso 5: Otorgar consentimiento de administrador

1. Después de agregar los permisos, los verás listados
2. Haz clic en Grant admin consent for [Your Organization]
3. Confirma el consentimiento en la ventana emergente

Tus permisos deberían verse así:

Configuración del entorno

Agregue las siguientes variables de entorno a su archivo .env:

# OpenID token reuse and OBO-compatible audience
OPENID_REUSE_TOKENS=true
OPENID_SCOPE=openid profile email offline_access api://<client-id>/access_as_user
OPENID_ON_BEHALF_FLOW_FOR_USERINFO_REQUIRED=true

# Enable SharePoint file picker
ENABLE_SHAREPOINT_FILEPICKER=true

# Your SharePoint tenant base URL
# Format: https://[your-tenant-name].sharepoint.com
SHAREPOINT_BASE_URL=https://contoso.sharepoint.com

# SharePoint scope for the file picker
# Replace 'contoso' with your actual tenant name
SHAREPOINT_PICKER_SHAREPOINT_SCOPE=https://contoso.sharepoint.com/AllSites.Read

# Microsoft Graph scope for file downloads
SHAREPOINT_PICKER_GRAPH_SCOPE=Files.Read.All

Cómo funciona

Flujo de autenticación

1. El usuario se autentica a través de Azure Entra ID
2. Al acceder al selector de SharePoint, LibreChat intercambia el token del usuario por acceso a SharePoint
3. Los tokens se almacenan en caché para un rendimiento óptimo (típicamente 50 minutos)
4. Los ámbitos separados garantizan el principio de menor privilegio

Proceso de selección de archivos

1. El usuario hace clic en "From SharePoint" en el menú de archivos adjuntos
2. El selector de archivos de SharePoint Online se abre en un iframe incrustado
3. El usuario explora y selecciona archivos utilizando la interfaz familiar de SharePoint
4. Los archivos seleccionados están en cola para su descarga

Proceso de descarga

1. Los archivos se descargan en lotes (hasta 3 descargas simultáneas)
2. El indicador de progreso muestra el archivo actual y el porcentaje completado
3. Los archivos descargados se adjuntan a la conversación
4. Las descargas fallidas se reintentan automáticamente

Experiencia del usuario

Acceso a archivos de SharePoint

Cuando se configura correctamente, los usuarios verán una nueva opción en el menú de adjuntos de archivos:

1. Haz clic en el icono de adjuntar en la entrada de mensaje
2. Selecciona "From SharePoint" en el menú
3. Se abrirá el selector de archivos de SharePoint
4. Explora y selecciona archivos según sea necesario
5. Haz clic en "Select" para comenzar la descarga

Características disponibles

• Selección múltiple de archivos: Seleccione hasta 10 archivos a la vez
• Interfaz familiar: Utiliza el selector de archivos nativo de SharePoint
• Seguimiento del progreso: Vea el progreso de la descarga en tiempo real
• Gestión de errores: Mensajes claros para cualquier problema
• Localización: Soporta múltiples idiomas

Consideraciones de seguridad

Control de acceso

• Solo los archivos a los que el usuario tiene permiso de acceso en SharePoint están disponibles
• Respeta todos los permisos y políticas de SharePoint
• Sin acceso elevado ni omisión de controles de seguridad

Seguridad de tokens

• Utiliza un flujo seguro "on-behalf-of" para el intercambio de tokens
• Los tokens son de corta duración y se actualizan automáticamente
• Sin almacenamiento a largo plazo de credenciales de SharePoint

Aislamiento de alcance

• El alcance de SharePoint está limitado solo a operaciones de lectura
• Ámbito de la Graph API restringido al acceso de lectura de archivos
• No se pueden modificar ni eliminar archivos a través de LibreChat

Solución de problemas

Problemas comunes

La opción "From SharePoint" no aparece

Causa: Función no habilitada correctamente o problemas de autenticación

Soluciones:

1. Verifique ENABLE_SHAREPOINT_FILEPICKER=true en .env
2. Confirma que OPENID_REUSE_TOKENS=true esté configurado
3. Comprobar que el usuario está autenticado mediante Azure Entra ID
4. Reiniciar LibreChat después de realizar cambios en la configuración

El selector de archivos no se abre

Causa: Permisos faltantes o incorrectos

Soluciones:

1. Verifique que los permisos de SharePoint estén concedidos en Azure
2. Asegúrese de que se haya proporcionado el consentimiento del administrador
3. Comprueba que SHAREPOINT_BASE_URL coincida exactamente con tu tenant
4. Confirme que SHAREPOINT_PICKER_SHAREPOINT_SCOPE utiliza la URL completa del inquilino, como https://contoso.sharepoint.com/AllSites.Read
5. Confirmar que HTTPS esté habilitado en producción

El selector de archivos se abre en una página blanca en blanco

Causa: Azure podría estar rechazando el intercambio on-behalf-of porque el token de acceso OpenID tiene la audiencia incorrecta, o porque el intercambio de token userinfo no está habilitado.

Soluciones:

1. Confirme que el registro de su aplicación Azure tiene un ámbito de API expuesto, como api://<client-id>/access_as_user
2. Añada ese alcance completo a OPENID_SCOPE
3. Establezca OPENID_ON_BEHALF_FLOW_FOR_USERINFO_REQUIRED=true
4. Reinicia LibreChat e inicia sesión de nuevo para que Azure emita nuevos tokens OpenID

Las descargas fallan o se agotan el tiempo de espera

Causa: Permisos de Graph API o problemas de red

Soluciones:

1. Verifique que el permiso Files.Read.All esté concedido
2. Comprobar la conectividad de red a SharePoint
3. Asegúrese de que los tokens no hayan caducado (vuelva a autenticarse si es necesario)
4. Revisa la consola del navegador para ver mensajes de error específicos

Modo de depuración

Para la resolución de problemas, habilite el registro de depuración (debug logging):

DEBUG_LOGGING=true
DEBUG_CONSOLE=true

Esto proporcionará registros detallados sobre:

• Procesos de intercambio de tokens
• Llamadas a la API de SharePoint y Graph
• Progreso de descarga y errores
• Flujos de autenticación

Optimización del rendimiento

Token Caching

• Los tokens se almacenan en caché para reducir la sobrecarga de autenticación
• La duración de la caché coincide con el tiempo de vida del token (típicamente 50 minutos)
• Actualización automática antes de la expiración

Descargas simultáneas

• Hasta 3 archivos se descargan simultáneamente
• Evita sobrecargar el navegador o el servidor
• Optimiza tanto para velocidad como para estabilidad

Consideraciones sobre el tamaño de archivo

• Los archivos grandes pueden tardar tiempo en descargarse
• El indicador de progreso ayuda a gestionar las expectativas del usuario
• Considere sus límites de carga de archivos en la configuración de LibreChat

Mejores prácticas

Para administradores

1. Auditorías de permisos periódicas: Revise los permisos de la aplicación periódicamente
2. Monitorizar el uso: Realice un seguimiento del uso de la integración de SharePoint en los registros
3. Actualización de la documentación: Mantenga la documentación interna actualizada con los detalles específicos de su tenant
4. Probar exhaustivamente: Verifique la funcionalidad después de cualquier cambio en Azure AD

Para usuarios finales

1. Organización de archivos: Las bibliotecas de SharePoint bien organizadas mejoran la experiencia del usuario
2. Tamaños de archivo: Tenga cuidado con los archivos grandes que pueden ralentizar las conversaciones
3. Permisos: Asegúrese de tener acceso a los archivos antes de compartirlos
4. Descargas del paciente: Permita tiempo para archivos múltiples o de gran tamaño

Configuración avanzada

Alcances personalizados

Para organizaciones con requisitos específicos, puede personalizar los scopes:

# Example: Limiting to specific site collections
SHAREPOINT_PICKER_SHAREPOINT_SCOPE=https://contoso.sharepoint.com/sites/Engineering/AllSites.Read

# Example: Using more restrictive Graph permissions
SHAREPOINT_PICKER_GRAPH_SCOPE=Files.Read

Integración con Information Barriers

Si su organización utiliza Information Barriers:

• La integración con SharePoint respeta todas las políticas de barrera
• Los usuarios solo ven el contenido al que tienen permiso de acceder
• No se requiere configuración adicional

Documentación relacionada

• Autenticación de Azure Entra
• Reutilización de tokens OpenID
• Integración con Microsoft Graph API
• Configuración de carga de archivos