Integrazione SharePoint

LibreChat fornisce un'integrazione di livello enterprise con SharePoint Online e OneDrive for Business, consentendo agli utenti di sfogliare, selezionare e allegare file dal proprio ambiente Microsoft 365 direttamente all'interno delle conversazioni in modo fluido.

Panoramica

L'integrazione SharePoint consente agli utenti di:

• Sfoglia le raccolte documenti di SharePoint e i file di OneDrive
• Seleziona più file contemporaneamente (fino a 10 per impostazione predefinita)
• Visualizza l'avanzamento del download in tempo reale
• Allega file da SharePoint alle conversazioni
• Mantieni la sicurezza aziendale con controlli di accesso adeguati

Prerequisiti

Prima di configurare l'integrazione con SharePoint, assicurati di avere:

1. Azure Entra ID Authentication configurata e funzionante
2. Token Reuse abilitato (OPENID_REUSE_TOKENS=true)
3. Un ambito API esposto per LibreChat, come api://<client-id>/access_as_user
4. Accesso amministratore al tuo tenant Azure per le autorizzazioni dell'app
5. HTTPS abilitato (richiesto per ambienti di produzione)

Configurazione della registrazione dell'app Azure

Passaggio 1: Configurare le autorizzazioni API

1. Vai alla registrazione della tua app nel Azure Portal
2. Vai su API permissions nel menu a sinistra
3. Fai clic su Add a permission

Passaggio 2: Esporre e concedere uno scope dell'API di LibreChat

Il flusso on-behalf-of richiede il token di accesso OpenID iniziale per puntare alla API della tua app LibreChat, non a Microsoft Graph. Esponi uno scope API in modo che Azure possa emettere un token con LibreChat come audience.

1. Vai su Expose an API nel menu a sinistra
2. Imposta l'Application ID URI su api://<client-id> se non è già configurato
3. Fai clic su Add a scope
4. Assegna al nome dell'ambito access_as_user
5. Salva l'ambito (scope), quindi copia il valore completo dell'ambito:

api://<client-id>/access_as_user

Quindi concedi tale ambito alla registrazione dell'app:

1. Torna a API permissions
2. Fai clic su Add a permission
3. Seleziona APIs my organization uses
4. Cerca e seleziona la tua registrazione dell'app LibreChat
5. Scegli Delegated permissions
6. Seleziona access_as_user
7. Fai clic su Add permissions

Utilizza il valore completo dello scope api://<client-id>/access_as_user in OPENID_SCOPE più avanti in questa guida.

Passaggio 3: Aggiungere le autorizzazioni SharePoint

Per l'interfaccia di selezione file:

1. Seleziona SharePoint dall'elenco API
2. Scegli Delegated permissions
3. Cerca e seleziona:
   • AllSites.Read - Leggi elementi in tutte le raccolte siti
4. Fai clic su Add permissions

Passaggio 4: Aggiungere le autorizzazioni di Microsoft Graph

Per i download di file:

1. Fai di nuovo clic su Add a permission
2. Seleziona Microsoft Graph
3. Scegli Delegated permissions
4. Cerca e seleziona:
   • Files.Read.All - Leggi tutti i file a cui l'utente può accedere
5. Fai clic su Add permissions

Passaggio 5: Concedere il consenso dell'amministratore

1. Dopo aver aggiunto le autorizzazioni, le vedrai elencate
2. Fai clic su Grant admin consent for [Your Organization]
3. Conferma il consenso nel popup

Le tue autorizzazioni dovrebbero apparire così:

Configurazione dell'ambiente

Aggiungi le seguenti variabili d'ambiente al tuo file .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

Come funziona

Flusso di autenticazione

1. L'utente si autentica tramite Azure Entra ID
2. Quando si accede al selettore SharePoint, LibreChat scambia il token dell'utente per l'accesso a SharePoint
3. I token vengono memorizzati nella cache per prestazioni ottimali (solitamente 50 minuti)
4. Ambiti separati garantiscono il principio del privilegio minimo

Processo di selezione dei file

1. L'utente clicca su "From SharePoint" nel menu degli allegati
2. Il file picker di SharePoint Online si apre in un iframe incorporato
3. L'utente naviga e seleziona i file utilizzando la familiare interfaccia di SharePoint
4. I file selezionati sono in coda per il download

Processo di download

1. I file vengono scaricati in batch (fino a 3 download simultanei)
2. L'indicatore di avanzamento mostra il file corrente e la percentuale di completamento
3. I file scaricati sono allegati alla conversazione
4. I download falliti vengono riprovati automaticamente

Esperienza utente

Accesso ai file SharePoint

Se configurato correttamente, gli utenti vedranno una nuova opzione nel menu degli allegati:

1. Fai clic sull'icona dell'allegato nell'input del messaggio
2. Seleziona "From SharePoint" dal menu
3. Si aprirà il selettore di file di SharePoint
4. Sfoglia e seleziona i file come necessario
5. Fai clic su "Select" per avviare il download

Funzionalità Disponibili

• Selezione multipla di file: Seleziona fino a 10 file contemporaneamente
• Interfaccia familiare: utilizza il selettore di file nativo di SharePoint
• Monitoraggio del progresso: Visualizza il progresso del download in tempo reale
• Gestione degli errori: Messaggi chiari per qualsiasi problema
• Localizzazione: Supporta diverse lingue

Considerazioni sulla sicurezza

Controllo Accessi

• Sono disponibili solo i file a cui l'utente ha il permesso di accedere in SharePoint
• Rispetta tutte le autorizzazioni e le policy di SharePoint
• Nessun accesso privilegiato o elusione dei controlli di sicurezza

Sicurezza dei Token

• Utilizza il flusso sicuro on-behalf-of per lo scambio di token
• I token sono a breve termine e vengono aggiornati automaticamente
• Nessuna memorizzazione a lungo termine delle credenziali SharePoint

Isolamento dello Scope

• Ambito di SharePoint limitato alle sole operazioni di lettura
• Ambito della Graph API limitato all'accesso in lettura dei file
• Impossibile modificare o eliminare file tramite LibreChat

Risoluzione dei problemi

Problemi comuni

L'opzione "From SharePoint" non viene visualizzata

Causa: Funzionalità non abilitata correttamente o problemi di autenticazione

Soluzioni:

1. Verifica ENABLE_SHAREPOINT_FILEPICKER=true in .env
2. Conferma che OPENID_REUSE_TOKENS=true sia impostato
3. Verifica che l'utente sia autenticato tramite Azure Entra ID
4. Riavvia LibreChat dopo le modifiche alla configurazione

Il selettore di file non si apre

Causa: Permessi mancanti o errati

Soluzioni:

1. Verifica che le autorizzazioni di SharePoint siano concesse in Azure
2. Assicurati che sia stato fornito il consenso dell'amministratore
3. Verifica che SHAREPOINT_BASE_URL corrisponda esattamente al tuo tenant
4. Conferma che SHAREPOINT_PICKER_SHAREPOINT_SCOPE utilizzi l'URL completo del tenant, come https://contoso.sharepoint.com/AllSites.Read
5. Conferma che HTTPS sia abilitato in produzione

Il selettore di file si apre su una pagina bianca vuota

Causa: Azure potrebbe rifiutare lo scambio on-behalf-of perché il token di accesso OpenID ha l'audience errata, o perché lo scambio del token userinfo non è abilitato.

Soluzioni:

1. Conferma che la registrazione della tua app Azure abbia un ambito API esposto, come api://<client-id>/access_as_user
2. Aggiungi quell'intero ambito a OPENID_SCOPE
3. Imposta OPENID_ON_BEHALF_FLOW_FOR_USERINFO_REQUIRED=true
4. Riavvia LibreChat ed effettua nuovamente l'accesso affinché Azure rilasci nuovi token OpenID

I download falliscono o vanno in timeout

Causa: Autorizzazioni Graph API o problemi di rete

Soluzioni:

1. Verifica che l'autorizzazione Files.Read.All sia concessa
2. Controlla la connettività di rete a SharePoint
3. Assicurati che i token non siano scaduti (riautenticati se necessario)
4. Controlla la console del browser per messaggi di errore specifici

Modalità di debug

Per la risoluzione dei problemi, abilita la registrazione di debug:

DEBUG_LOGGING=true
DEBUG_CONSOLE=true

Questo fornirà log dettagliati su:

• Processi di scambio di token
• Chiamate API a SharePoint e Graph
• Avanzamento del download ed errori
• Flussi di autenticazione

Ottimizzazione delle prestazioni

Token Caching

• I token vengono memorizzati nella cache per ridurre il sovraccarico di autenticazione
• La durata della cache corrisponde alla durata del token (solitamente 50 minuti)
• Aggiornamento automatico prima della scadenza

Download simultanei

• Fino a 3 file scaricati simultaneamente
• Impedisce di sovraccaricare il browser o il server
• Ottimizzato sia per la velocità che per la stabilità

Considerazioni sulle dimensioni dei file

• I file di grandi dimensioni potrebbero richiedere del tempo per essere scaricati
• L'indicatore di progresso aiuta a gestire le aspettative dell'utente
• Considera i tuoi limiti di caricamento file nella configurazione di LibreChat

Best Practices

Per gli amministratori

1. Audit periodici delle autorizzazioni: Rivedi periodicamente le autorizzazioni dell'app
2. Monitoraggio dell'utilizzo: Traccia l'utilizzo dell'integrazione SharePoint nei log
3. Aggiornamento della documentazione: Mantieni aggiornata la documentazione interna con le specifiche del tuo tenant
4. Test Thoroughly: Verifica la funzionalità dopo qualsiasi modifica ad Azure AD

Per gli utenti finali

1. Organizzazione dei file: Le librerie SharePoint ben organizzate migliorano l'esperienza utente
2. Dimensioni dei file: Fai attenzione ai file di grandi dimensioni che potrebbero rallentare le conversazioni
3. Autorizzazioni: Assicurati di avere accesso ai file prima di condividerli
4. Download paziente: Consenti tempo per file multipli o di grandi dimensioni

Configurazione avanzata

Ambiti personalizzati

Per le organizzazioni con requisiti specifici, è possibile personalizzare gli scope:

# 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

Integrazione con Information Barriers

Se la tua organizzazione utilizza Information Barriers:

• L'integrazione con SharePoint rispetta tutte le policy di barriera
• Gli utenti vedono solo i contenuti a cui sono autorizzati ad accedere
• Nessuna configurazione aggiuntiva richiesta

Documentazione correlata

• Autenticazione Azure Entra
• Riutilizzo del token OpenID
• Integrazione Microsoft Graph API
• Configurazione del caricamento file