Integracja z SharePoint

LibreChat zapewnia integrację klasy korporacyjnej z SharePoint Online oraz OneDrive for Business, umożliwiając użytkownikom płynne przeglądanie, wybieranie i załączanie plików ze środowiska Microsoft 365 bezpośrednio wewnątrz konwersacji.

Przegląd

Integracja z SharePoint umożliwia użytkownikom:

• Przeglądaj biblioteki dokumentów SharePoint i pliki OneDrive
• Wybierz wiele plików jednocześnie (domyślnie do 10)
• Zobacz postęp pobierania w czasie rzeczywistym
• Dołączaj pliki z SharePoint do konwersacji
• Utrzymuj bezpieczeństwo klasy korporacyjnej dzięki odpowiednim kontrolom dostępu

Wymagania wstępne

Przed skonfigurowaniem integracji z SharePoint upewnij się, że posiadasz:

1. Azure Entra ID Authentication skonfigurowane i działające
2. Token Reuse włączone (OPENID_REUSE_TOKENS=true)
3. Udostępniony zakres API dla LibreChat, taki jak api://<client-id>/access_as_user
4. Dostęp administratora do Twojego tenanta Azure w celu nadania uprawnień aplikacji
5. HTTPS włączone (wymagane w środowiskach produkcyjnych)

Konfiguracja rejestracji aplikacji Azure

Krok 1: Skonfiguruj uprawnienia API

1. Przejdź do rejestracji swojej aplikacji w Azure Portal
2. Przejdź do API permissions w menu po lewej stronie
3. Kliknij Add a permission

Krok 2: Uwidocznij i przyznaj zakres API LibreChat

Przepływ on-behalf-of wymaga początkowego tokenu dostępu OpenID, aby kierować zapytania do API Twojej aplikacji LibreChat, a nie do Microsoft Graph. Uwidocznij zakres (scope) API, aby Azure mógł wydać token z LibreChat jako odbiorcą (audience).

1. Przejdź do Expose an API w menu po lewej stronie
2. Ustaw Application ID URI na api://<client-id>, jeśli nie jest jeszcze skonfigurowany
3. Kliknij Add a scope
4. Nazwij zakres access_as_user
5. Zapisz zakres (scope), a następnie skopiuj pełną wartość zakresu:

api://<client-id>/access_as_user

Następnie przyznaj ten zakres rejestracji aplikacji:

1. Wróć do API permissions
2. Kliknij Add a permission
3. Wybierz APIs my organization uses
4. Wyszukaj i wybierz swoją rejestrację aplikacji LibreChat
5. Wybierz Delegated permissions
6. Wybierz access_as_user
7. Kliknij Add permissions

Użyj pełnej wartości zakresu api://<client-id>/access_as_user w OPENID_SCOPE w dalszej części tego przewodnika.

Krok 3: Dodaj uprawnienia SharePoint

Dla interfejsu wyboru plików:

1. Wybierz SharePoint z listy API
2. Wybierz Delegated permissions
3. Wyszukaj i wybierz:
   • AllSites.Read - Odczyt elementów we wszystkich kolekcjach witryn
4. Kliknij Add permissions

Krok 4: Dodaj uprawnienia Microsoft Graph

Dla pobierania plików:

1. Kliknij ponownie Add a permission
2. Wybierz Microsoft Graph
3. Wybierz Delegated permissions
4. Wyszukaj i wybierz:
   • Files.Read.All - Odczyt wszystkich plików, do których użytkownik ma dostęp
5. Kliknij Add permissions

Krok 5: Udziel zgody administratora

1. Po dodaniu uprawnień zobaczysz je na liście
2. Kliknij Udziel zgody administratora dla [Twoja Organizacja]
3. Potwierdź zgodę w wyskakującym okienku

Twoje uprawnienia powinny wyglądać następująco:

Konfiguracja środowiska

Dodaj następujące zmienne środowiskowe do swojego pliku .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

Jak to działa

Przepływ uwierzytelniania

1. Użytkownik uwierzytelnia się za pomocą Azure Entra ID
2. Podczas uzyskiwania dostępu do selektora SharePoint, LibreChat wymienia token użytkownika na dostęp do SharePoint.
3. Tokeny są buforowane w celu uzyskania optymalnej wydajności (zazwyczaj przez 50 minut)
4. Oddzielne zakresy zapewniają zasadę najmniejszych uprawnień

Proces wyboru plików

1. Użytkownik klika „From SharePoint” w menu załączników
2. Selektor plików SharePoint Online otwiera się w osadzonym elemencie iframe
3. Użytkownik przegląda i wybiera pliki przy użyciu znanego interfejsu SharePoint
4. Wybrane pliki zostały dodane do kolejki pobierania

Proces pobierania

1. Pliki są pobierane w partiach (do 3 jednoczesnych pobrań)
2. Wskaźnik postępu pokazuje bieżący plik i procent ukończenia
3. Pobrane pliki są dołączone do konwersacji
4. Nieudane pobieranie jest ponawiane automatycznie

Doświadczenie użytkownika

Dostęp do plików SharePoint

Po prawidłowej konfiguracji użytkownicy zobaczą nową opcję w menu załączników plików:

1. Kliknij ikonę załącznika w polu wprowadzania wiadomości
2. Wybierz "From SharePoint" z menu
3. Otworzy się selektor plików SharePoint
4. Przeglądaj i wybieraj pliki w razie potrzeby
5. Kliknij "Select", aby rozpocząć pobieranie

Dostępne funkcje

• Wybór wielu plików: Wybierz do 10 plików jednocześnie
• Znajomy interfejs: Wykorzystuje natywny selektor plików SharePoint
• Śledzenie postępu: Zobacz postęp pobierania w czasie rzeczywistym
• Obsługa błędów: Jasne komunikaty dotyczące wszelkich problemów
• Localization: Obsługuje wiele języków

Kwestie bezpieczeństwa

Kontrola dostępu

• Dostępne są tylko pliki, do których użytkownik ma uprawnienia w SharePoint
• Respektuje wszystkie uprawnienia i zasady SharePoint
• Brak podwyższonego dostępu lub omijania zabezpieczeń

Bezpieczeństwo tokenów

• Wykorzystuje bezpieczny przepływ on-behalf-of do wymiany tokenów
• Tokeny są krótkotrwałe i automatycznie odświeżane
• Brak długoterminowego przechowywania poświadczeń SharePoint

Izolacja zakresu

• Zakres SharePoint ograniczony wyłącznie do operacji odczytu
• Zakres Graph API ograniczony do dostępu do odczytu plików
• Nie można modyfikować ani usuwać plików za pośrednictwem LibreChat

Rozwiązywanie problemów

Typowe problemy

Opcja "From SharePoint" nie pojawia się

Przyczyna: Funkcja nie została poprawnie włączona lub wystąpiły problemy z uwierzytelnianiem

Rozwiązania:

1. Zweryfikuj ENABLE_SHAREPOINT_FILEPICKER=true w pliku .env
2. Upewnij się, że ustawiono OPENID_REUSE_TOKENS=true
3. Sprawdź, czy użytkownik jest uwierzytelniony przez Azure Entra ID
4. Zrestartuj LibreChat po wprowadzeniu zmian w konfiguracji

Wybór plików nie działa

Przyczyna: Brakujące lub nieprawidłowe uprawnienia

Rozwiązania:

1. Zweryfikuj, czy uprawnienia SharePoint zostały przyznane w Azure
2. Upewnij się, że uzyskano zgodę administratora
3. Sprawdź, czy SHAREPOINT_BASE_URL dokładnie odpowiada Twojemu tenantowi
4. Upewnij się, że SHAREPOINT_PICKER_SHAREPOINT_SCOPE używa pełnego adresu URL dzierżawy, na przykład https://contoso.sharepoint.com/AllSites.Read
5. Potwierdź, że HTTPS jest włączone w środowisku produkcyjnym

Selektor plików otwiera się na pustej białej stronie

Przyczyna: Azure może odrzucać wymianę on-behalf-of, ponieważ token dostępu OpenID ma nieprawidłową grupę odbiorców (audience) lub ponieważ wymiana tokena userinfo nie jest włączona.

Rozwiązania:

1. Upewnij się, że Twoja rejestracja aplikacji Azure posiada udostępniony zakres API, taki jak api://<client-id>/access_as_user
2. Dodaj ten pełny zakres do OPENID_SCOPE
3. Ustaw OPENID_ON_BEHALF_FLOW_FOR_USERINFO_REQUIRED=true
4. Zrestartuj LibreChat i zaloguj się ponownie, aby Azure wygenerował nowe tokeny OpenID

Pobieranie kończy się niepowodzeniem lub przekracza limit czasu

Przyczyna: Uprawnienia Graph API lub problemy z siecią

Rozwiązania:

1. Zweryfikuj, czy przyznano uprawnienie Files.Read.All
2. Sprawdź łączność sieciową z SharePoint
3. Upewnij się, że tokeny nie wygasły (w razie potrzeby przeprowadź ponowną autoryzację)
4. Sprawdź konsolę przeglądarki pod kątem konkretnych komunikatów o błędach

Tryb debugowania

W celu rozwiązywania problemów włącz logowanie debugowania:

DEBUG_LOGGING=true
DEBUG_CONSOLE=true

To zapewni szczegółowe logi dotyczące:

• Procesy wymiany tokenów
• Wywołania API do SharePoint i Graph
• Postęp pobierania i błędy
• Przepływy uwierzytelniania

Optymalizacja wydajności

Buforowanie tokenów

• Tokeny są buforowane w celu zmniejszenia narzutu uwierzytelniania
• Czas trwania pamięci podręcznej odpowiada okresowi ważności tokena (zazwyczaj 50 minut)
• Automatyczne odświeżanie przed wygaśnięciem

Równoległe pobieranie

• Do 3 plików pobieranych jednocześnie
• Zapobiega przeciążeniu przeglądarki lub serwera
• Optymalizuje zarówno pod kątem szybkości, jak i stabilności

Uwagi dotyczące rozmiaru plików

• Pobieranie dużych plików może chwilę potrwać
• Wskaźnik postępu pomaga zarządzać oczekiwaniami użytkownika
• Rozważ limity przesyłania plików w konfiguracji LibreChat

Najlepsze praktyki

Dla administratorów

1. Regularne audyty uprawnień: Okresowo sprawdzaj uprawnienia aplikacji
2. Monitorowanie użycia: Śledź użycie integracji z SharePoint w logach
3. Aktualizacja dokumentacji: Utrzymuj wewnętrzną dokumentację w stanie aktualnym, uwzględniając specyfikę Twojego tenanta
4. Test Thoroughly: Zweryfikuj funkcjonalność po każdej zmianie w Azure AD

Dla użytkowników końcowych

1. Organizacja plików: Dobrze zorganizowane biblioteki SharePoint poprawiają komfort użytkowania
2. Rozmiary plików: Pamiętaj, że duże pliki mogą spowalniać konwersacje
3. Uprawnienia: Upewnij się, że masz dostęp do plików przed ich udostępnieniem
4. Pobieranie przez pacjenta: Zapewnij czas na pobranie wielu lub dużych plików

Zaawansowana konfiguracja

Niestandardowe zakresy (Custom Scopes)

W przypadku organizacji o określonych wymaganiach, możesz dostosować zakresy (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

Integracja z Information Barriers

Jeśli Twoja organizacja korzysta z Information Barriers:

• Integracja z SharePoint respektuje wszystkie zasady barier (barrier policies)
• Użytkownicy widzą tylko te treści, do których mają uprawnienia dostępu
• Nie jest wymagana żadna dodatkowa konfiguracja

Powiązana dokumentacja

• Uwierzytelnianie Azure Entra
• Ponowne użycie tokena OpenID
• Integracja z Microsoft Graph API
• Konfiguracja przesyłania plików