Kontrol Akses Granular

LibreChat hadir dengan sistem otorisasi lengkap di atas autentikasi. Akses tidak bersifat "semua atau tidak sama sekali": setiap entitas yang dapat dibagikan di dalam aplikasi (agen, prompt, server MCP, agen jarak jauh, file, percakapan) memiliki Access Control List (ACL) sendiri, dan setiap fitur dapat diaktifkan atau dibatasi secara independen per pengguna, grup, peran, atau publik.

Halaman ini menjelaskan bagaimana bagian-bagian tersebut disatukan sehingga Anda dapat memodelkan izin agar sesuai dengan organisasi Anda, mulai dari tim kecil di mana setiap orang berbagi secara bebas, hingga penyebaran perusahaan dengan grup Entra ID yang disinkronkan, peran kustom, dan admin yang didelegasikan.

Sekilas tentang Model Akses

Otorisasi LibreChat memiliki tiga lapisan independen yang tersusun bersama:

Ketiganya dievaluasi untuk empat tipe utama yang sama:

• User: akun LibreChat individu
• Grup: kumpulan pengguna (lokal atau disinkronkan dari Entra ID)
• Role: profil izin bernama (contoh: USER, ADMIN, atau peran kustom apa pun)
• Public: setiap pengguna yang terautentikasi pada instance tersebut

Layer 1: Izin Fitur (Berbasis Peran)

Izin tingkat fitur membatasi seluruh kapabilitas aplikasi untuk peran tertentu. Izin ini menjawab pertanyaan seperti "Apakah pengguna dalam peran ini dapat membuat agen?", "Apakah mereka diizinkan untuk membagikan prompt secara publik?", "Apakah mereka dapat menjalankan interpreter kode?".

Peran Sistem Bawaan

LibreChat hadir dengan dua peran sistem yang selalu ada dan tidak dapat dihapus:

• ADMIN: ditetapkan ke akun pertama yang terdaftar di instans tersebut. Admin dapat melihat setiap sumber daya, mengubah pengaturan apa pun, mengakses panel admin, dan mengonfigurasi perilaku di seluruh platform.
• USER: peran default yang ditetapkan untuk setiap akun baru.

Admin dapat dipromosikan secara manual dengan memperbarui dokumen pengguna di MongoDB, lihat Administrator Controls.

Tipe Izin

Setiap peran memiliki matriks tipe izin × tindakan:

Perbedaan antara SHARE dan SHARE_PUBLIC sangat penting: Anda dapat mengizinkan suatu peran untuk membagikan agen kepada pengguna atau grup tertentu (SHARE) tanpa membiarkan mereka membuat agen tersebut terlihat oleh semua orang di instans tersebut (SHARE_PUBLIC).

Mengonfigurasi Izin Fitur

Cara yang direkomendasikan untuk mengelola izin fitur adalah LibreChat Admin Panel, yang mengedit matriks izin secara langsung pada setiap peran (termasuk peran kustom apa pun yang Anda buat). Perubahan akan langsung berlaku tanpa perlu melakukan redeploy LibreChat dan dicakup pada peran spesifik yang ingin Anda modifikasi, alih-alih menggunakan default USER global.

Peran Kustom

Selain USER dan ADMIN, administrator dapat membuat peran kustom dengan matriks fitur-izin mereka sendiri (diperkenalkan pada v0.8.5; lihat #12528). Seorang pengguna dapat memiliki beberapa peran, dan izin efektif mereka adalah gabungan dari semua peran yang dimiliki. Peran kustom dikelola dari panel admin.

Penggantian Konfigurasi Berbasis Peran dan Grup

Selain fitur flags, v0.8.5 memperkenalkan sistem penggantian konfigurasi berbasis DB (#12354). Sistem ini memungkinkan Anda menetapkan konfigurasi bergaya librechat.yaml yang berbeda ke grup atau peran tertentu. Sebagai contoh, grup "Research" mungkin memiliki akses ke endpoint tambahan, batas rekursi yang lebih tinggi, dan kemampuan agen yang berbeda dibandingkan dengan konfigurasi default. Penggantian diselesaikan saat login dan disusun di atas konfigurasi dasar.

Layer 2: Resource ACLs (Per-Entity Sharing)

Setiap sumber daya yang dapat dibagikan di LibreChat memiliki Access Control List (Daftar Kontrol Akses) sendiri, yang terpisah dari izin berbasis peran. Inilah cara pengguna individu dengan izin SHARE memilih siapa yang mendapatkan akses ke agen, prompt, atau server MCP milik mereka.

Tipe Sumber Daya

ACL Sumber Daya saat ini berlaku untuk:

• Agen (agent)
• Prompt / Grup Prompt (promptGroup)
• Server MCP (mcpServer)
• Remote Agents (remoteAgent), untuk Agents API
• Files (file), biasanya diwarisi dari sumber daya yang menggunakannya
• Projects (project), mendukung pewarisan sehingga sumber daya yang dibagikan ke sebuah project secara otomatis mewarisi ACL

Peran Akses (Preset Izin)

Daripada mengekspos bit izin mentah kepada pengguna akhir, berbagi menggunakan tiga peran bernama per jenis sumber daya:

Di balik layar, izin disimpan sebagai bitmask (permBits) untuk setiap pasangan (resource, principal); superset ditangani secara otomatis, sehingga memberikan akses Editor secara implisit juga memberikan akses Viewer.

Memberikan Akses dari UI

1. Buka sumber daya (pembuat agen, formulir prompt, pengaturan server MCP, dll.)
2. Klik tombol Share (terlihat saat Anda adalah pemilik, admin, atau telah diberikan akses SHARE)
3. Di dalam dialog bagikan:
   • Gunakan pemilih orang untuk mencari users, groups, atau roles untuk ditambahkan
   • Pilih peran akses (Viewer / Editor / Owner) per prinsipal
   • Secara opsional, aktifkan Public access untuk membuat sumber daya tersebut terlihat oleh semua orang di instance (memerlukan izin fitur SHARE_PUBLIC)
4. Simpan. Penerima hibah akan melihat sumber daya tersebut saat mereka menyegarkan halaman di lain waktu.

Apa yang Dilihat Penerima Hibah

• Viewers melihat sumber daya tersebut sebagai item yang siap digunakan di pemilih yang relevan (misalnya, menu tarik-turun agen). Mereka tidak dapat membuka pembuat, melihat instruksi mentah, atau mengubah pengaturan.
• Editors dapat membuka konfigurasi sumber daya dan mengubahnya, tetapi tidak dapat menghapusnya atau membagikannya kembali.
• Pemilik (Owners) memiliki UI yang sama dengan penulis asli, serta dapat menghapus dan membagikan ulang secara bebas.
• Penulis asli selalu memegang kendali penuh terlepas dari status ACL, dan admin dapat mengelola sumber daya apa pun pada instance tersebut.

Pewarisan Proyek

Izin dapat diwariskan dari project induk. Saat entri ACL diwariskan, tautan inheritedFrom akan mengarah kembali ke sumbernya. Inilah yang menggerakkan project "Global" di LibreChat, di mana sumber daya yang ditambahkan ke project global menjadi tersedia bagi semua pengguna tanpa memerlukan entri per prinsipal.

Layer 3: System Grants (Kemampuan Admin)

System grants adalah tabel hibah terpisah yang digunakan untuk kapabilitas tingkat admin, yang menjawab pertanyaan seperti "Bisakah pengguna ini mengakses panel admin?" atau "Bisakah grup ini mengelola server MCP secara global?". Hibah ini selalu dicakupkan ke principal (pengguna, grup, atau peran) dan string kapabilitas.

Kemampuan kanonik meliputi:

Kemampuan kelola (manage) menyiratkan kemampuan baca (read) yang sesuai (misalnya, memiliki manage:users secara otomatis memberikan read:users). Pengguna dengan SystemRoles.ADMIN secara implisit memegang semua kemampuan; pemberian hak akses memungkinkan Anda untuk mendelegasikan sebagian kekuatan admin kepada prinsipal non-admin tanpa menjadikan mereka admin penuh.

Hak akses sistem diberikan dan dicabut melalui panel admin.

Prinsip-prinsip secara Mendalam

Pengguna

Akun LibreChat standar. Pengguna bisa berupa lokal (email/kata sandi) atau terfederasi (OAuth2, OIDC, SAML, LDAP). Pengguna terfederasi dapat dicocokkan dengan identitas eksternal (idOnTheSource); untuk Entra ID, ini adalah OID, yang merupakan hal yang memungkinkan sinkronisasi grup.

Grup

Grup adalah kumpulan pengguna yang diberi nama. LibreChat mendukung dua sumber:

• Grup lokal: dibuat dan dikelola dari panel admin atau langsung di dalam basis data. Anggotanya adalah ID pengguna LibreChat.
• Grup Entra ID (Azure AD): disinkronkan dari Microsoft Graph saat pengguna masuk melalui Azure OIDC dengan token reuse diaktifkan. Setiap grup yang disinkronkan menyimpan Entra Object ID-nya sebagai idOnTheSource, yang menjaga LibreChat tetap selaras dengan keanggotaan penyewa (tenant).

Grup dapat muncul di ACL mana pun, dalam pencarian peoplePicker, dan sebagai target utama untuk penggantian konfigurasi atau pemberian akses sistem. Satu sumber daya yang dibagikan kepada grup berisi 500 orang dihitung sebagai satu entri ACL (bukan 500), dan perubahan keanggotaan di Entra akan disebarkan secara otomatis pada login berikutnya.

Peran

Sistem atau peran kustom apa pun dapat digunakan sebagai prinsipal. Berbagi agen dengan peran (misalnya SupportEngineers) memberikan akses kepada setiap pengguna yang saat ini memegang peran tersebut, tanpa perlu menyebutkan individu satu per satu. Peran dapat disembunyikan dari pemilih orang (people picker) melalui interface.peoplePicker.roles untuk lingkungan di mana berbagi berbasis peran hanya menjadi urusan admin.

Publik

Prinsipal khusus yang mencocokkan setiap pengguna yang terautentikasi. Pemberian akses publik hanya diizinkan jika pengguna yang memberikan akses memiliki izin fitur SHARE_PUBLIC untuk jenis sumber daya tersebut.

Visibilitas Pemilih Orang

Pemilih orang (kotak pencarian dalam dialog berbagi) dapat dibatasi di tingkat instans untuk menyembunyikan jenis prinsipal yang tidak relevan bagi penyebaran Anda:

interface:
  peoplePicker:
    users: true
    groups: true
    roles: false

Ini hanya memengaruhi search UI; entri ACL yang ada untuk tipe principal yang disembunyikan akan terus berfungsi dan ditegakkan secara normal.

Migrasi dari Versi Pra-ACL

Versi sebelum v0.8.0-rc3 menggunakan model kepemilikan yang lebih sederhana. Peningkatan versi mengharuskan Anda menjalankan migrasi ACL agar agen dan prompt yang sudah ada tetap dapat diakses:

Dry run (pratinjau perubahan):

npm run migrate:agent-permissions:dry-run
npm run migrate:prompt-permissions:dry-run

Eksekusi:

npm run migrate:agent-permissions
npm run migrate:prompt-permissions

Lihat panduan migrasi agents untuk varian Docker dan opsi batch-size.

Dokumentasi Terkait

• Agen: Berbagi dan Izin
• Konfigurasi Antarmuka (izin fitur)
• Autentikasi
• Penggunaan Kembali Token OpenID Connect (diperlukan untuk sinkronisasi grup Entra ID)
• Azure / Entra ID OAuth2
• Integrasi SharePoint
• Agents API (Remote Agents)
• Panel Admin LibreChat