Granular Access Control

LibreChat, kimlik doğrulamanın üzerinde tam bir yetkilendirme sistemiyle birlikte gelir. Erişim "ya hep ya hiç" şeklinde değildir: uygulamadaki her paylaşılabilir varlığın (ajanlar, istemler, MCP sunucuları, uzak ajanlar, dosyalar, konuşmalar) kendi Erişim Denetim Listesi (ACL) bulunur ve her özellik kullanıcı, grup, rol bazında veya herkese açık olarak bağımsız bir şekilde etkinleştirilebilir veya kısıtlanabilir.

Bu sayfa, herkesin özgürce paylaşım yaptığı küçük bir ekipten, senkronize edilmiş Entra ID grupları, özel roller ve yetkilendirilmiş yöneticilere sahip kurumsal bir dağıtıma kadar, organizasyonunuza uygun izinleri modelleyebilmeniz için parçaların nasıl bir araya geldiğini açıklamaktadır.

Erişim Modeline Bir Bakış

LibreChat'in yetkilendirme sistemi, birlikte çalışan üç bağımsız katmandan oluşur:

Üçü de aynı dört temel tür için değerlendirilir:

• User: bireysel bir LibreChat hesabı
• Grup: kullanıcıların bir koleksiyonu (yerel veya Entra ID üzerinden senkronize edilmiş)
• Role: adlandırılmış bir izin profili (örneğin USER, ADMIN veya herhangi bir özel rol)
• Public: örnek üzerindeki her kimliği doğrulanmış kullanıcı

Katman 1: Özellik İzinleri (Rol Tabanlı)

Özellik düzeyi izinleri, belirli bir rol için uygulamanın tüm yeteneklerini denetler. Bu izinler, "Bu roldeki kullanıcılar hiç ajan oluşturabilir mi?", "İstemleri herkese açık olarak paylaşmalarına izin veriliyor mu?", "Kod yorumlayıcıyı çalıştırabilirler mi?" gibi sorulara yanıt verir.

Yerleşik Sistem Rolleri

LibreChat, her zaman mevcut olan ve silinemeyen iki sistem rolüyle birlikte gelir:

• ADMIN: örnekte (instance) kayıtlı ilk hesaba atanır. Yöneticiler her kaynağı görebilir, herhangi bir ayarı değiştirebilir, yönetici paneline erişebilir ve platform genelindeki davranışları yapılandırabilir.
• USER: her yeni hesaba atanan varsayılan rol.

Yöneticiler, MongoDB'deki kullanıcı belgesi güncellenerek manuel olarak yükseltilebilir, bkz. Administrator Controls.

İzin Türleri

Her rol bir izin türleri × eylemler matrisi tutar:

SHARE ve SHARE_PUBLIC arasındaki ayrım önemlidir: Bir role, temsilcileri herkese görünür kılmalarına izin vermeden (SHARE_PUBLIC), belirli kullanıcılara veya gruplara (SHARE) temsilci paylaşma yetkisi verebilirsiniz.

Özellik İzinlerini Yapılandırma

Özellik izinlerini yönetmenin önerilen yolu, her rol (oluşturduğunuz özel roller dahil) üzerindeki izin matrisini doğrudan düzenleyen LibreChat Admin Panel kullanmaktır. Değişiklikler, LibreChat'i yeniden dağıtmaya gerek kalmadan geçerli olur ve genel USER varsayılanı yerine, değiştirmek istediğiniz tam role özel olarak uygulanır.

Özel Roller

USER ve ADMIN rollerinin ötesinde, yöneticiler kendi özellik-izin matrislerine sahip özel roller oluşturabilirler (v0.8.5 ile tanıtılmıştır; bkz. #12528). Bir kullanıcı birden fazla role sahip olabilir ve kullanıcının geçerli izinleri, sahip olduğu tüm rollerin birleşimidir. Özel roller, yönetici panelinden yönetilir.

Rol ve Grup Kapsamlı Yapılandırma Geçersiz Kılmaları

Özellik bayraklarına ek olarak, v0.8.5 sürümü veritabanı destekli bir yapılandırma geçersiz kılma (override) sistemi getirdi (#12354). Bu sistem, belirli gruplara veya rollere farklı bir librechat.yaml tarzı yapılandırma atamanıza olanak tanır. Örneğin, bir "Araştırma" grubu, varsayılan yapılandırmadan farklı olarak ek endpoint'lere, daha yüksek bir özyineleme sınırına ve farklı ajan yeteneklerine erişebilir. Geçersiz kılmalar giriş sırasında çözümlenir ve temel yapılandırmanın üzerine eklenerek oluşturulur.

Katman 2: Kaynak ACL'leri (Varlık Bazlı Paylaşım)

LibreChat içindeki her paylaşılabilir kaynağın, rol tabanlı izinlerden bağımsız olarak kendi Erişim Kontrol Listesi (Access Control List) bulunur. SHARE iznine sahip bir kullanıcının, kendi temsilcisine (agent), istemine (prompt) veya MCP sunucusuna kimin erişebileceğini seçme yöntemi budur.

Kaynak Türleri

Kaynak ACL'leri şu anda şunlar için geçerlidir:

• Ajanlar (agent)
• İstemler / İstem Grupları (promptGroup)
• MCP Sunucuları (mcpServer)
• Uzak Temsilciler (remoteAgent), Agents API için
• Dosyalar (file), genellikle onları kullanan kaynaktan miras alınır
• Projeler (project), kaynakların bir projeyle paylaşıldığında otomatik olarak ACL'leri devralmasını sağlayan kalıtımı destekler

Erişim Rolleri (İzin Ön Ayarları)

Son kullanıcılara ham izin bitlerini göstermek yerine, paylaşım özelliği her kaynak türü için üç adlandırılmış rol kullanır:

Arka planda izinler, her (kaynak, sorumlu) çifti için bir bit maskesi (permBits) olarak saklanır; üst kümeler otomatik olarak işlenir, bu nedenle Düzenleyici (Editor) yetkisi vermek, Görüntüleyici (Viewer) yetkisini de beraberinde getirir.

Arayüzden Erişim Verme

1. Kaynağı açın (agent builder, prompt form, MCP server settings, vb.)
2. Paylaş düğmesine tıklayın (sohbetin sahibi olduğunuzda, yönetici olduğunuzda veya size SHARE yetkisi verildiğinde görünür)
3. Paylaşım iletişim kutusunda:
   • Kullanıcıları, grupları veya rolleri eklemek üzere aramak için kişi seçiciyi kullanın
   • Her bir asıl (principal) için bir erişim rolü (Viewer / Editor / Owner) seçin
   • İsteğe bağlı olarak, kaynağı örnekteki (instance) herkes için görünür kılmak üzere Public access (Herkese açık erişim) seçeneğini açıp kapatabilirsiniz (SHARE_PUBLIC özellik izni gerektirir)
4. Kaydet. Kullanıcılar sayfayı bir sonraki yenilediklerinde kaynağı görürler.

Kullanıcıların Gördükleri

• Görüntüleyiciler, kaynağı ilgili seçicide (örneğin ajan açılır menüsü) kullanıma hazır bir öğe olarak görürler. Oluşturucuyu açamaz, ham talimatları göremez veya ayarları değiştiremezler.
• Editors (Düzenleyiciler), kaynağın yapılandırmasını açabilir ve değiştirebilir, ancak onu silemez veya yeniden paylaşamazlar.
• Owners, orijinal yazarla aynı kullanıcı arayüzüne sahiptir ve diledikleri gibi silme ve yeniden paylaşma işlemi yapabilirler.
• Orijinal yazar, ACL durumundan bağımsız olarak her zaman tam kontrole sahiptir ve yöneticiler örnek üzerindeki herhangi bir kaynağı yönetebilir.

Proje Devralma

İzinler bir üst project (proje) öğesinden devralınabilir. Bir ACL girişi devralındığında, inheritedFrom bağlantısı kaynağı işaret eder. LibreChat içindeki "Global" projesine güç veren mekanizma budur; global projeye eklenen bir kaynak, her bir kullanıcı (principal) için ayrı bir giriş gerektirmeden tüm kullanıcılar tarafından erişilebilir hale gelir.

Katman 3: Sistem İzinleri (Yönetici Yetenekleri)

Sistem izinleri (system grants), yönetici düzeyi yetenekler için kullanılan ayrı bir izin tablosudur ve "Bu kullanıcı yönetici paneline erişebilir mi?" veya "Bu grup MCP sunucularını küresel olarak yönetebilir mi?" gibi soruları yanıtlar. Bunlar her zaman bir özneye (kullanıcı, grup veya rol) ve bir yetenek dizisine (capability string) göre kapsamlandırılır.

Kanonik yetenekler şunları içerir:

Yönetme (manage) yetenekleri, ilgili okuma (read) yeteneklerini de kapsar (örneğin, manage:users yetkisine sahip olmak otomatik olarak read:users yetkisini de verir). Bir SystemRoles.ADMIN kullanıcısı tüm yeteneklere örtük olarak sahiptir; yetkilendirmeler (grants), yönetici olmayan kişilere tam yönetici yapmadan yönetici yetkilerinin bir alt kümesini devretmenize olanak tanır.

Sistem izinleri, yönetici paneli aracılığıyla verilir ve geri alınır.

İlkelerin Derinlemesine İncelenmesi

Kullanıcılar

Standart LibreChat hesapları. Kullanıcılar yerel (e-posta/parola) veya federe (OAuth2, OIDC, SAML, LDAP) olabilir. Federe kullanıcılar harici bir kimlikle (idOnTheSource) eşleştirilebilir; Entra ID için bu, grup senkronizasyonunu sağlayan OID'dir.

Gruplar

Bir grup, adlandırılmış bir kullanıcı koleksiyonudur. LibreChat iki kaynağı destekler:

• Yerel gruplar: yönetici panelinden veya doğrudan veritabanından oluşturulur ve yönetilir. Üyeler LibreChat kullanıcı kimlikleridir (user ID).
• Entra ID (Azure AD) grupları: token reuse etkinleştirilmiş şekilde bir kullanıcı Azure OIDC aracılığıyla giriş yaptığında Microsoft Graph'ten senkronize edilir. Senkronize edilen her grup, Entra Nesne Kimliğini idOnTheSource olarak saklar; bu da LibreChat'in kiracı üyeliğiyle uyumlu kalmasını sağlar.

Gruplar herhangi bir ACL'de, peoplePicker aramasında ve yapılandırma geçersiz kılmaları veya sistem izinleri için birincil hedef olarak görünebilir. 500 kişilik bir grupla paylaşılan tek bir kaynak, 500 değil, tek bir ACL girdisidir ve Entra'daki üyelik değişiklikleri bir sonraki girişte otomatik olarak yansıtılır.

Roller

Herhangi bir sistem veya özel rol, yetkili (principal) olarak kullanılabilir. Bir ajanı bir rolle (örneğin SupportEngineers) paylaşmak, bireyleri tek tek listelemeye gerek kalmadan, şu anda o role sahip olan her kullanıcıya erişim sağlar. Rol tabanlı paylaşımın yalnızca yöneticiye özel olduğu ortamlar için roller, interface.peoplePicker.roles aracılığıyla kişi seçiciden gizlenebilir.

Genel

Her kimlik doğrulanmış kullanıcıyla eşleşen özel bir yönetici (principal). Genel izinler (public grants), yalnızca izni veren kullanıcı ilgili kaynak türü için SHARE_PUBLIC özellik iznine sahip olduğunda verilebilir.

Kişi Seçici Görünürlüğü

Kişi seçici (paylaşım iletişim kutularındaki arama kutusu), dağıtımınız için uygun olmayan asıl türleri gizlemek üzere örnek düzeyinde sınırlandırılabilir:

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

Bu durum yalnızca arama arayüzünü etkiler; gizli asıl türleri (principal types) için mevcut ACL girişleri çalışmaya devam eder ve normal şekilde uygulanır.

ACL Öncesi Sürümlerden Geçişler

v0.8.0-rc3 öncesi sürümler daha basit bir sahiplik modeli kullanıyordu. Yükseltme işlemi, mevcut ajanların ve istemlerin erişilebilir kalması için ACL geçişinin çalıştırılmasını gerektirir:

Dry run (değişiklikleri önizle):

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

Yürüt:

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

Docker varyantları ve batch-size seçenekleri için agents migration guide bölümüne bakın.

İlgili Dokümantasyon

• Ajanlar: Paylaşım ve İzinler
• Arayüz Yapılandırması (özellik izinleri)
• Kimlik Doğrulama
• OpenID Connect Token Reuse (Entra ID grup senkronizasyonu için gereklidir)
• Azure / Entra ID OAuth2
• SharePoint Entegrasyonu
• Agents API (Remote Agents)
• LibreChat Yönetim Paneli