Intégration SharePoint

LibreChat offre une intégration de niveau entreprise avec SharePoint Online et OneDrive for Business, permettant aux utilisateurs de parcourir, sélectionner et joindre facilement des fichiers depuis leur environnement Microsoft 365 directement au sein des conversations.

Vue d'ensemble

L'intégration SharePoint permet aux utilisateurs de :

• Parcourir les bibliothèques de documents SharePoint et les fichiers OneDrive
• Sélectionnez plusieurs fichiers à la fois (jusqu'à 10 par défaut)
• Voir la progression du téléchargement en temps réel
• Joindre des fichiers depuis SharePoint aux conversations
• Maintenez la sécurité de l'entreprise avec des contrôles d'accès appropriés

Prérequis

Avant de configurer l'intégration SharePoint, assurez-vous de disposer des éléments suivants :

1. Authentification Azure Entra ID configurée et fonctionnelle
2. Réutilisation de jetons activée (OPENID_REUSE_TOKENS=true)
3. Une portée d'API exposée pour LibreChat, telle que api://<client-id>/access_as_user
4. Accès administrateur à votre tenant Azure pour les autorisations d'application
5. HTTPS activé (requis pour les environnements de production)

Configuration de l'enregistrement d'application Azure

Étape 1 : Configurer les autorisations API

1. Accédez à l'enregistrement de votre application dans le Azure Portal
2. Allez dans API permissions dans le menu de gauche
3. Cliquez sur Add a permission

Étape 2 : Exposer et accorder une portée d'API LibreChat

Le flux « on-behalf-of » nécessite le jeton d'accès OpenID initial pour cibler votre API LibreChat, et non Microsoft Graph. Exposez une étendue (scope) d'API afin qu'Azure puisse émettre un jeton avec LibreChat comme audience.

1. Allez dans Expose an API dans le menu de gauche
2. Définissez l'Application ID URI sur api://<client-id> si elle n'est pas déjà configurée
3. Cliquez sur Add a scope
4. Nommez la portée access_as_user
5. Enregistrez la portée (scope), puis copiez la valeur complète de la portée :

api://<client-id>/access_as_user

Ensuite, accordez cette portée à l'enregistrement de l'application :

1. Retourner aux API permissions
2. Cliquez sur Add a permission
3. Sélectionnez APIs my organization uses
4. Recherchez et sélectionnez votre enregistrement d'application LibreChat
5. Choisissez Delegated permissions
6. Sélectionnez access_as_user
7. Cliquez sur Add permissions

Utilisez la valeur de portée api://<client-id>/access_as_user complète dans OPENID_SCOPE plus loin dans ce guide.

Étape 3 : Ajouter les autorisations SharePoint

Pour l'interface du sélecteur de fichiers :

1. Sélectionnez SharePoint dans la liste des API
2. Choisissez Delegated permissions
3. Rechercher et sélectionner :
   • AllSites.Read - Lire les éléments dans toutes les collections de sites
4. Cliquez sur Add permissions

Étape 4 : Ajouter les autorisations Microsoft Graph

Pour les téléchargements de fichiers :

1. Cliquez à nouveau sur Add a permission
2. Sélectionnez Microsoft Graph
3. Choisissez Delegated permissions
4. Rechercher et sélectionner :
   • Files.Read.All - Lire tous les fichiers auxquels l'utilisateur peut accéder
5. Cliquez sur Add permissions

Étape 5 : Accorder le consentement de l'administrateur

1. Après avoir ajouté les permissions, vous les verrez listées
2. Cliquez sur Grant admin consent for [Your Organization]
3. Confirmez le consentement dans la fenêtre contextuelle

Vos permissions devraient ressembler à ceci :

Configuration de l'environnement

Ajoutez les variables d'environnement suivantes à votre fichier .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

Comment ça fonctionne

Flux d'authentification

1. L'utilisateur s'authentifie via Azure Entra ID
2. Lors de l'accès au sélecteur SharePoint, LibreChat échange le jeton de l'utilisateur pour un accès à SharePoint.
3. Les jetons sont mis en cache pour une performance optimale (généralement 50 minutes)
4. Des portées distinctes garantissent le principe du moindre privilège

Processus de sélection de fichiers

1. L'utilisateur clique sur « From SharePoint » dans le menu des pièces jointes
2. Le sélecteur de fichiers SharePoint Online s'ouvre dans une iframe intégrée
3. L'utilisateur parcourt et sélectionne des fichiers en utilisant l'interface SharePoint familière
4. Les fichiers sélectionnés sont mis en file d'attente pour le téléchargement

Processus de téléchargement

1. Les fichiers sont téléchargés par lots (jusqu'à 3 téléchargements simultanés)
2. L'indicateur de progression affiche le fichier actuel et le pourcentage terminé
3. Les fichiers téléchargés sont joints à la conversation
4. Les téléchargements ayant échoué sont relancés automatiquement

Expérience utilisateur

Accéder aux fichiers SharePoint

Une fois correctement configuré, les utilisateurs verront une nouvelle option dans le menu des pièces jointes :

1. Cliquez sur l'icône de pièce jointe dans la zone de saisie du message
2. Sélectionnez "From SharePoint" dans le menu
3. Le sélecteur de fichiers SharePoint s'ouvrira
4. Parcourez et sélectionnez les fichiers selon vos besoins
5. Cliquez sur « Select » pour commencer le téléchargement

Fonctionnalités disponibles

• Sélection de fichiers multiples : Sélectionnez jusqu'à 10 fichiers à la fois
• Interface familière : Utilise le sélecteur de fichiers natif de SharePoint
• Suivi de la progression : Visualisez la progression du téléchargement en temps réel
• Gestion des erreurs : Messages clairs pour tout problème
• Localisation : Prend en charge plusieurs langues

Considérations de sécurité

Contrôle d'accès

• Seuls les fichiers auxquels l'utilisateur a l'autorisation d'accéder dans SharePoint sont disponibles
• Respecte toutes les autorisations et politiques SharePoint
• Aucun accès privilégié ni contournement des contrôles de sécurité

Sécurité des jetons

• Utilise un flux sécurisé « on-behalf-of » pour l'échange de jetons
• Les jetons sont de courte durée et sont automatiquement actualisés
• Aucun stockage à long terme des identifiants SharePoint

Isolation de la portée

• Portée SharePoint limitée aux opérations de lecture uniquement
• Portée de l'API Graph restreinte à l'accès en lecture de fichiers
• Impossible de modifier ou de supprimer des fichiers via LibreChat

Dépannage

Problèmes courants

L'option "From SharePoint" n'apparaît pas

Cause : Fonctionnalité non correctement activée ou problèmes d'authentification

Solutions :

1. Vérifiez ENABLE_SHAREPOINT_FILEPICKER=true dans .env
2. Confirmez que OPENID_REUSE_TOKENS=true est défini
3. Vérifier que l'utilisateur est authentifié via Azure Entra ID
4. Redémarrez LibreChat après avoir modifié la configuration

Le sélecteur de fichiers ne s'ouvre pas

Cause : Permissions manquantes ou incorrectes

Solutions :

1. Vérifiez que les autorisations SharePoint sont accordées dans Azure
2. Assurez-vous que le consentement de l'administrateur a été fourni
3. Vérifiez que SHAREPOINT_BASE_URL correspond exactement à votre tenant
4. Confirmez que SHAREPOINT_PICKER_SHAREPOINT_SCOPE utilise l'URL complète du tenant, telle que https://contoso.sharepoint.com/AllSites.Read
5. Confirmer que HTTPS est activé en production

Le sélecteur de fichiers s'ouvre sur une page blanche

Cause : Azure peut rejeter l'échange « on-behalf-of » parce que le jeton d'accès OpenID a une audience incorrecte, ou parce que l'échange de jeton userinfo n'est pas activé.

Solutions :

1. Confirmez que votre inscription d'application Azure dispose d'une étendue d'API exposée, telle que api://<client-id>/access_as_user
2. Ajoutez cette portée complète à OPENID_SCOPE
3. Définissez OPENID_ON_BEHALF_FLOW_FOR_USERINFO_REQUIRED=true
4. Redémarrez LibreChat et reconnectez-vous afin qu'Azure émette de nouveaux jetons OpenID

Les téléchargements échouent ou expirent

Cause : Autorisations de l'API Graph ou problèmes réseau

Solutions :

1. Vérifiez que l'autorisation Files.Read.All est accordée
2. Vérifier la connectivité réseau vers SharePoint
3. Assurez-vous que les jetons n'ont pas expiré (ré-authentifiez-vous si nécessaire)
4. Vérifiez la console du navigateur pour des messages d'erreur spécifiques

Mode débogage

Pour le dépannage, activez la journalisation de débogage :

DEBUG_LOGGING=true
DEBUG_CONSOLE=true

Cela fournira des journaux détaillés concernant :

• Processus d'échange de jetons
• Appels API vers SharePoint et Graph
• Progression du téléchargement et erreurs
• Flux d'authentification

Optimisation des performances

Mise en cache des jetons

• Les jetons sont mis en cache pour réduire la surcharge liée à l'authentification.
• La durée du cache correspond à la durée de vie du jeton (généralement 50 minutes)
• Actualisation automatique avant expiration

Téléchargements simultanés

• Jusqu'à 3 fichiers téléchargés simultanément
• Empêche de surcharger le navigateur ou le serveur
• Optimise à la fois pour la vitesse et la stabilité

Considérations sur la taille des fichiers

• Les fichiers volumineux peuvent prendre du temps à être téléchargés
• L'indicateur de progression aide à gérer les attentes des utilisateurs
• Tenez compte de vos limites de téléchargement de fichiers dans la configuration de LibreChat

Meilleures pratiques

Pour les administrateurs

1. Audits de permissions réguliers : Examinez périodiquement les permissions de l'application
2. Surveiller l'utilisation : Suivre l'utilisation de l'intégration SharePoint dans les journaux
3. Mise à jour de la documentation : Maintenez la documentation interne à jour avec les spécificités de votre tenant
4. Test Thoroughly : Vérifiez la fonctionnalité après toute modification apportée à Azure AD

Pour les utilisateurs finaux

1. Organisation des fichiers : Des bibliothèques SharePoint bien organisées améliorent l'expérience utilisateur
2. Tailles de fichiers : Soyez attentif aux fichiers volumineux qui peuvent ralentir les conversations
3. Permissions : Assurez-vous d'avoir accès aux fichiers avant de les partager
4. Téléchargements patients : Prévoyez du temps pour les fichiers multiples ou volumineux

Configuration avancée

Scopes personnalisés

Pour les organisations ayant des exigences spécifiques, vous pouvez personnaliser les 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

Intégration avec les barrières d'information

Si votre organisation utilise des barrières d'information (Information Barriers) :

• L'intégration SharePoint respecte toutes les politiques de barrière
• Les utilisateurs ne voient que le contenu auquel ils sont autorisés à accéder
• Aucune configuration supplémentaire n'est requise

Documentation associée

• Authentification Azure Entra
• Réutilisation de jeton OpenID
• Intégration de l'API Microsoft Graph
• Configuration du téléchargement de fichiers