Integrasi SharePoint

LibreChat menyediakan integrasi tingkat perusahaan dengan SharePoint Online dan OneDrive for Business, yang memungkinkan pengguna untuk menelusuri, memilih, dan melampirkan file dari lingkungan Microsoft 365 mereka secara langsung di dalam percakapan dengan lancar.

Ikhtisar

Integrasi SharePoint memungkinkan pengguna untuk:

• Telusuri pustaka dokumen SharePoint dan file OneDrive
• Pilih beberapa file sekaligus (hingga 10 file secara default)
• Lihat progres unduhan secara real-time
• Lampirkan file dari SharePoint ke percakapan
• Jaga keamanan perusahaan dengan kontrol akses yang tepat

Prasyarat

Sebelum mengonfigurasi integrasi SharePoint, pastikan Anda telah memiliki:

1. Azure Entra ID Authentication dikonfigurasi dan berfungsi
2. Token Reuse diaktifkan (OPENID_REUSE_TOKENS=true)
3. Cakupan API yang terekspos untuk LibreChat, seperti api://<client-id>/access_as_user
4. Akses admin ke tenant Azure Anda untuk izin aplikasi
5. HTTPS diaktifkan (diperlukan untuk lingkungan produksi)

Penyiapan Pendaftaran Aplikasi Azure

Langkah 1: Konfigurasi Izin API

1. Buka pendaftaran aplikasi Anda di Azure Portal
2. Buka API permissions di menu sebelah kiri
3. Klik Add a permission

Langkah 2: Ekspos dan Berikan Scope API LibreChat

Alur on-behalf-of memerlukan token akses OpenID awal untuk menargetkan API aplikasi LibreChat Anda, bukan Microsoft Graph. Ekspos cakupan API agar Azure dapat menerbitkan token dengan LibreChat sebagai audiensnya.

1. Buka Expose an API di menu sebelah kiri
2. Atur Application ID URI ke api://<client-id> jika belum dikonfigurasi
3. Klik Add a scope
4. Beri nama scope tersebut access_as_user
5. Simpan scope tersebut, lalu salin nilai scope lengkapnya:

api://<client-id>/access_as_user

Kemudian berikan cakupan (scope) tersebut ke pendaftaran aplikasi:

1. Kembali ke API permissions
2. Klik Add a permission
3. Pilih APIs my organization uses
4. Cari dan pilih pendaftaran aplikasi LibreChat Anda
5. Pilih Delegated permissions
6. Pilih access_as_user
7. Klik Add permissions

Gunakan nilai scope api://<client-id>/access_as_user secara lengkap di dalam OPENID_SCOPE pada bagian selanjutnya di panduan ini.

Langkah 3: Tambahkan Izin SharePoint

Untuk antarmuka pemilih file:

1. Pilih SharePoint dari daftar API
2. Pilih Delegated permissions
3. Cari dan pilih:
   • AllSites.Read - Membaca item di semua koleksi situs
4. Klik Add permissions

Langkah 4: Tambahkan Izin Microsoft Graph

Untuk unduhan file:

1. Klik Add a permission lagi
2. Pilih Microsoft Graph
3. Pilih Delegated permissions
4. Cari dan pilih:
   • Files.Read.All - Membaca semua file yang dapat diakses oleh pengguna
5. Klik Add permissions

Langkah 5: Berikan Persetujuan Admin

1. Setelah menambahkan izin tersebut, Anda akan melihatnya tercantum
2. Klik Grant admin consent for [Your Organization]
3. Konfirmasi persetujuan di popup

Izin Anda seharusnya terlihat seperti ini:

Konfigurasi Lingkungan

Tambahkan variabel lingkungan berikut ke file .env Anda:

# 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

Cara Kerja

Alur Autentikasi

1. Pengguna melakukan autentikasi melalui Azure Entra ID
2. Saat mengakses pemilih SharePoint, LibreChat menukarkan token pengguna untuk akses SharePoint
3. Token di-cache untuk performa optimal (biasanya 50 menit)
4. Cakupan terpisah memastikan prinsip hak istimewa paling rendah (principle of least privilege)

Proses Pemilihan File

1. Pengguna mengeklik "From SharePoint" di menu lampiran
2. Pemilih file SharePoint Online terbuka di dalam iframe yang disematkan
3. Pengguna menelusuri dan memilih file menggunakan antarmuka SharePoint yang familier
4. File yang dipilih telah dimasukkan ke dalam antrean untuk diunduh

Proses Unduh

1. File diunduh dalam batch (hingga 3 unduhan bersamaan)
2. Indikator progres menampilkan file saat ini dan persentase penyelesaian
3. File yang diunduh dilampirkan ke percakapan
4. Unduhan yang gagal akan dicoba ulang secara otomatis

Pengalaman Pengguna

Mengakses File SharePoint

Setelah dikonfigurasi dengan benar, pengguna akan melihat opsi baru di menu lampiran file:

1. Klik ikon lampiran di kolom input pesan
2. Pilih "From SharePoint" dari menu
3. Pemilih file SharePoint akan terbuka
4. Telusuri dan pilih file sesuai kebutuhan
5. Klik "Select" untuk mulai mengunduh

Fitur yang Tersedia

• Pemilihan banyak file: Pilih hingga 10 file sekaligus
• Antarmuka yang familier: Menggunakan pemilih file SharePoint asli
• Pelacakan progres: Lihat progres unduhan secara real-time
• Penanganan error: Pesan yang jelas untuk setiap masalah
• Lokalisasi: Mendukung berbagai bahasa

Pertimbangan Keamanan

Kontrol Akses

• Hanya file yang memiliki izin akses oleh pengguna di SharePoint yang tersedia
• Menghormati semua izin dan kebijakan SharePoint
• Tidak ada akses yang ditingkatkan atau pengabaian kontrol keamanan

Keamanan Token

• Menggunakan alur on-behalf-of yang aman untuk pertukaran token
• Token bersifat jangka pendek dan diperbarui secara otomatis
• Tidak ada penyimpanan jangka panjang untuk kredensial SharePoint

Isolasi Cakupan

• Cakupan SharePoint dibatasi hanya untuk operasi baca saja
• Cakupan Graph API dibatasi pada akses baca file
• Tidak dapat mengubah atau menghapus file melalui LibreChat

Pemecahan Masalah

Masalah Umum

Opsi "From SharePoint" tidak muncul

Penyebab: Fitur tidak diaktifkan dengan benar atau terdapat masalah autentikasi

Solusi:

1. Verifikasi ENABLE_SHAREPOINT_FILEPICKER=true di dalam .env
2. Pastikan OPENID_REUSE_TOKENS=true telah diatur
3. Periksa apakah pengguna telah diautentikasi melalui Azure Entra ID
4. Mulai ulang LibreChat setelah perubahan konfigurasi

Pemilih file gagal dibuka

Penyebab: Izin hilang atau tidak tepat

Solusi:

1. Verifikasi bahwa izin SharePoint telah diberikan di Azure
2. Pastikan persetujuan admin telah diberikan
3. Pastikan SHAREPOINT_BASE_URL sama persis dengan tenant Anda
4. Pastikan SHAREPOINT_PICKER_SHAREPOINT_SCOPE menggunakan URL tenant lengkap, seperti https://contoso.sharepoint.com/AllSites.Read
5. Pastikan HTTPS diaktifkan di lingkungan produksi

Pemilih file terbuka ke halaman putih kosong

Penyebab: Azure mungkin menolak pertukaran on-behalf-of karena token akses OpenID memiliki audience yang salah, atau karena pertukaran token userinfo tidak diaktifkan.

Solusi:

1. Pastikan pendaftaran aplikasi Azure Anda memiliki scope API yang diekspos, seperti api://<client-id>/access_as_user
2. Tambahkan cakupan penuh tersebut ke OPENID_SCOPE
3. Atur OPENID_ON_BEHALF_FLOW_FOR_USERINFO_REQUIRED=true
4. Mulai ulang LibreChat dan masuk kembali agar Azure menerbitkan token OpenID yang baru

Unduhan gagal atau timeout

Penyebab: Izin Graph API atau masalah jaringan

Solusi:

1. Verifikasi izin Files.Read.All telah diberikan
2. Periksa konektivitas jaringan ke SharePoint
3. Pastikan token belum kedaluwarsa (lakukan autentikasi ulang jika diperlukan)
4. Periksa konsol peramban untuk pesan kesalahan spesifik

Mode Debug

Untuk pemecahan masalah, aktifkan pencatatan debug:

DEBUG_LOGGING=true
DEBUG_CONSOLE=true

Ini akan memberikan log terperinci mengenai:

• Proses pertukaran token
• Panggilan API ke SharePoint dan Graph
• Kemajuan unduhan dan kesalahan
• Alur autentikasi

Optimalisasi Performa

Token Caching

• Token di-cache untuk mengurangi overhead autentikasi
• Durasi cache sesuai dengan masa berlaku token (biasanya 50 menit)
• Penyegaran otomatis sebelum kedaluwarsa

Unduhan Bersamaan

• Hingga 3 file diunduh secara bersamaan
• Mencegah kelebihan beban pada browser atau server
• Mengoptimalkan untuk kecepatan dan stabilitas

Pertimbangan Ukuran File

• File berukuran besar mungkin memerlukan waktu untuk diunduh
• Indikator progres membantu mengelola ekspektasi pengguna
• Pertimbangkan batas unggah file Anda dalam konfigurasi LibreChat

Praktik Terbaik

Untuk Administrator

1. Audit Izin Berkala: Tinjau izin aplikasi secara berkala
2. Monitor Penggunaan: Lacak penggunaan integrasi SharePoint di dalam log
3. Update Documentation: Selalu perbarui dokumentasi internal dengan spesifikasi tenant Anda
4. Uji Secara Menyeluruh: Verifikasi fungsionalitas setelah adanya perubahan pada Azure AD

Untuk Pengguna Akhir

1. Pengorganisasian File: Pustaka SharePoint yang terorganisir dengan baik meningkatkan pengalaman pengguna
2. Ukuran File: Perhatikan file berukuran besar yang dapat memperlambat percakapan
3. Izin: Pastikan Anda memiliki akses ke file sebelum membagikannya
4. Unduhan Pasien: Berikan waktu untuk banyak file atau file berukuran besar

Konfigurasi Lanjutan

Custom Scopes

Untuk organisasi dengan kebutuhan khusus, Anda dapat menyesuaikan 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

Integrasi dengan Information Barriers

Jika organisasi Anda menggunakan Information Barriers:

• Integrasi SharePoint menghormati semua kebijakan penghalang (barrier policies)
• Pengguna hanya melihat konten yang diizinkan untuk mereka akses
• Tidak diperlukan konfigurasi tambahan

Dokumentasi Terkait

• Autentikasi Azure Entra
• Penggunaan Ulang Token OpenID
• Integrasi Microsoft Graph API
• Konfigurasi Unggah Berkas