Granular Access Control

LibreChat jest dostarczany z pełnym systemem autoryzacji działającym w oparciu o uwierzytelnianie. Dostęp nie działa na zasadzie „wszystko albo nic”: każdy współdzielony element w aplikacji (agenci, prompty, serwery MCP, zdalni agenci, pliki, konwersacje) posiada własną listę kontroli dostępu (ACL), a każda funkcja może być niezależnie włączona lub ograniczona dla użytkownika, grupy, roli lub publicznie.

Ta strona wyjaśnia, jak poszczególne elementy do siebie pasują, dzięki czemu możesz modelować uprawnienia tak, aby odpowiadały Twojej organizacji – od małego zespołu, w którym wszyscy dzielą się zasobami, po wdrożenie korporacyjne z zsynchronizowanymi grupami Entra ID, niestandardowymi rolami i delegowanymi administratorami.

Model dostępu w skrócie

Autoryzacja w LibreChat składa się z trzech niezależnych warstw, które współpracują ze sobą:

Wszystkie trzy są oceniane pod kątem tych samych czterech głównych typów:

• Użytkownik: indywidualne konto LibreChat
• Grupa: zbiór użytkowników (lokalnych lub zsynchronizowanych z Entra ID)
• Rola: nazwany profil uprawnień (np. USER, ADMIN lub dowolna rola niestandardowa)
• Public: każdy uwierzytelniony użytkownik w instancji

Warstwa 1: Uprawnienia funkcji (oparte na rolach)

Uprawnienia na poziomie funkcji ograniczają dostęp do całych możliwości aplikacji dla danej roli. Odpowiadają one na pytania takie jak: "Czy użytkownicy w tej roli mogą w ogóle tworzyć agentów?", "Czy mogą publicznie udostępniać prompty?", "Czy mogą korzystać z interpretera kodu?".

Wbudowane role systemowe

LibreChat jest dostarczany z dwiema rolami systemowymi, które są zawsze obecne i nie można ich usunąć:

• ADMIN: przypisana do pierwszego konta zarejestrowanego w instancji. Administratorzy mogą przeglądać wszystkie zasoby, modyfikować dowolne ustawienia, uzyskiwać dostęp do panelu administratora oraz konfigurować zachowanie całej platformy.
• USER: domyślna rola przypisywana każdemu nowemu kontu.

Administratorzy mogą zostać awansowani ręcznie poprzez aktualizację dokumentu użytkownika w MongoDB, zobacz Administrator Controls.

Typy uprawnień

Każda rola posiada macierz typów uprawnień × akcji:

Rozróżnienie między SHARE a SHARE_PUBLIC jest istotne: możesz zezwolić roli na udostępnianie agentów określonym użytkownikom lub grupom (SHARE) bez pozwalania im na udostępnianie agentów w sposób widoczny dla wszystkich w instancji (SHARE_PUBLIC).

Konfigurowanie uprawnień funkcji

Zalecanym sposobem zarządzania uprawnieniami funkcji jest Panel Administratora LibreChat, który edytuje macierz uprawnień bezpośrednio dla każdej roli (w tym wszelkich utworzonych ról niestandardowych). Zmiany wchodzą w życie bez konieczności ponownego wdrażania LibreChat i dotyczą dokładnie tej roli, którą chcesz zmodyfikować, zamiast globalnego ustawienia domyślnego USER.

Niestandardowe role

Poza USER i ADMIN, administratorzy mogą tworzyć role niestandardowe z własną macierzą uprawnień do funkcji (wprowadzone w wersji v0.8.5; zobacz #12528). Użytkownik może posiadać wiele ról, a jego efektywne uprawnienia stanowią sumę uprawnień wszystkich posiadanych ról. Role niestandardowe są zarządzane z poziomu panelu administratora.

Zastępowanie konfiguracji w zakresie ról i grup

Oprócz flag funkcji, wersja v0.8.5 wprowadziła system nadpisywania konfiguracji wspierany przez bazę danych (#12354). Pozwala on na przypisanie innej konfiguracji w stylu librechat.yaml do określonych grup lub ról. Na przykład grupa "Research" może mieć dostęp do dodatkowych endpoint, wyższego limitu rekurencji oraz innych możliwości agenta niż w konfiguracji domyślnej. Nadpisania są rozstrzygane podczas logowania i nakładane na konfigurację bazową.

Warstwa 2: ACL zasobów (udostępnianie dla poszczególnych jednostek)

Każdy współdzielony zasób w LibreChat posiada własną listę kontroli dostępu (Access Control List), niezależną od uprawnień opartych na rolach. W ten sposób indywidualny użytkownik z uprawnieniem SHARE decyduje, kto uzyskuje dostęp do jego agenta, promptu lub serwera MCP.

Typy zasobów

Obecnie listy kontroli dostępu (ACL) zasobów mają zastosowanie do:

• Agenci (agent)
• Prompty / Grupy promptów (promptGroup)
• Serwery MCP (mcpServer)
• Zdalni agenci (remoteAgent), dla Agents API
• Pliki (file), zazwyczaj dziedziczone z zasobu, który z nich korzysta
• Projekty (project), obsługują dziedziczenie, dzięki czemu zasoby udostępnione w projekcie automatycznie dziedziczą listy ACL (ACLs)

Role dostępowe (Presety uprawnień)

Zamiast udostępniać użytkownikom końcowym surowe bity uprawnień, udostępnianie wykorzystuje trzy nazwane role dla każdego typu zasobu:

Pod maską uprawnienia są przechowywane jako maska bitowa (permBits) dla każdej pary (zasób, podmiot); nadzbiory są obsługiwane automatycznie, więc przyznanie uprawnień Editor oznacza również przyznanie uprawnień Viewer.

Przyznawanie dostępu z poziomu interfejsu użytkownika

1. Otwórz zasób (kreator agentów, formularz promptu, ustawienia serwera MCP itp.)
2. Kliknij przycisk Share (widoczny, gdy jesteś właścicielem, administratorem lub otrzymałeś uprawnienie SHARE)
3. W oknie dialogowym udostępniania:
   • Użyj selektora osób, aby wyszukać użytkowników, grupy lub role, które chcesz dodać
   • Wybierz rolę dostępu (Viewer / Editor / Owner) dla każdego podmiotu (principal)
   • Opcjonalnie przełącz Dostęp publiczny, aby udostępnić zasób wszystkim użytkownikom instancji (wymaga uprawnienia funkcji SHARE_PUBLIC)
4. Zapisz. Użytkownicy zobaczą zasób przy następnym odświeżeniu strony.

Co widzą beneficjenci

• Widzowie widzą zasób jako gotowy do użycia element w odpowiednim selektorze (np. na liście rozwijanej agentów). Nie mogą oni otwierać kreatora, przeglądać surowych instrukcji ani modyfikować ustawień.
• Edytorzy mogą otwierać konfigurację zasobu i ją modyfikować, ale nie mogą jej usuwać ani ponownie udostępniać.
• Właściciele mają taki sam interfejs jak oryginalny autor i mogą swobodnie usuwać oraz ponownie udostępniać elementy.
• Oryginalny autor zawsze zachowuje pełną kontrolę niezależnie od stanu ACL, a administratorzy mogą zarządzać każdym zasobem w instancji.

Dziedziczenie projektu

Uprawnienia mogą być dziedziczone z projektu nadrzędnego. Gdy wpis ACL jest dziedziczony, link inheritedFrom wskazuje na źródło. To właśnie napędza projekt "Global" w LibreChat, gdzie zasób dodany do projektu globalnego staje się dostępny dla wszystkich użytkowników bez konieczności tworzenia wpisu dla każdego podmiotu (principal).

Warstwa 3: Uprawnienia systemowe (możliwości administratora)

Uprawnienia systemowe to oddzielna tabela uprawnień używana do funkcji na poziomie administratora, odpowiadająca na pytania takie jak "Czy ten użytkownik ma dostęp do panelu administratora?" lub "Czy ta grupa może globalnie zarządzać serwerami MCP?". Są one zawsze przypisane do podmiotu (użytkownika, grupy lub roli) oraz ciągu znaków określającego uprawnienie.

Kanoniczne możliwości obejmują:

Uprawnienia typu manage implikują odpowiadające im uprawnienia typu read (np. posiadanie manage:users automatycznie przyznaje read:users). Użytkownik z SystemRoles.ADMIN posiada domyślnie wszystkie uprawnienia; nadania pozwalają delegować podzbiór uprawnień administracyjnych podmiotom niebędącym administratorami, bez nadawania im pełnych uprawnień administratora.

Uprawnienia systemowe są przyznawane i odbierane za pośrednictwem panelu administratora.

Szczegółowe informacje o zasadach (Principals)

Użytkownicy

Standardowe konta LibreChat. Użytkownicy mogą być lokalni (email/hasło) lub sfederowani (OAuth2, OIDC, SAML, LDAP). Użytkownicy sfederowani mogą być dopasowani do zewnętrznej tożsamości (idOnTheSource); w przypadku Entra ID jest to OID, co umożliwia synchronizację grup.

Grupy

Grupa to nazwana kolekcja użytkowników. LibreChat obsługuje dwa źródła:

• Grupy lokalne: tworzone i zarządzane z poziomu panelu administratora lub bezpośrednio w bazie danych. Członkami są identyfikatory użytkowników LibreChat.
• Grupy Entra ID (Azure AD): synchronizowane z Microsoft Graph podczas logowania użytkownika przez Azure OIDC z włączoną funkcją token reuse. Każda zsynchronizowana grupa przechowuje swój identyfikator Entra Object ID jako idOnTheSource, co pozwala LibreChat na utrzymanie pełnej zgodności z członkostwem w dzierżawie (tenant).

Grupy mogą pojawiać się w dowolnej liście ACL, w wyszukiwarce peoplePicker oraz jako główny cel dla nadpisań konfiguracji lub uprawnień systemowych. Pojedynczy zasób udostępniony grupie 500-osobowej stanowi jeden wpis ACL (a nie 500), a zmiany w członkostwie w Entra są automatycznie propagowane przy następnym logowaniu.

Role

Każda rola systemowa lub niestandardowa może być użyta jako podmiot (principal). Udostępnienie agenta roli (np. SupportEngineers) zapewnia dostęp każdemu użytkownikowi posiadającemu obecnie tę rolę, bez konieczności wymieniania poszczególnych osób. Role mogą być ukryte w selektorze osób za pomocą interface.peoplePicker.roles w środowiskach, w których udostępnianie oparte na rolach jest kwestią zastrzeżoną wyłącznie dla administratorów.

Public

Specjalny podmiot (principal), który pasuje do każdego uwierzytelnionego użytkownika. Publiczne uprawnienia są dozwolone tylko wtedy, gdy użytkownik udzielający dostępu posiada uprawnienie funkcji SHARE_PUBLIC dla danego typu zasobu.

Widoczność wyboru osób (People Picker)

Wybierak osób (pole wyszukiwania w oknach dialogowych udostępniania) może być ograniczony na poziomie instancji, aby ukryć typy podmiotów, które nie są istotne dla Twojego wdrożenia:

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

Wpływa to tylko na interfejs wyszukiwania; istniejące wpisy ACL dla ukrytych typów podmiotów (principal types) nadal działają i są egzekwowane w normalny sposób.

Migracje z wersji sprzed ACL

Wersje wcześniejsze niż v0.8.0-rc3 korzystały z prostszego modelu własności. Aktualizacja wymaga przeprowadzenia migracji ACL, aby istniejące agenty i prompty pozostały dostępne:

Dry run (podgląd zmian):

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

Wykonaj:

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

Zobacz przewodnik migracji agentów dla wariantów Docker oraz opcji batch-size.

Powiązana dokumentacja

• Agenci: Udostępnianie i uprawnienia
• Konfiguracja interfejsu (uprawnienia funkcji)
• Uwierzytelnianie
• Ponowne użycie tokena OpenID Connect (wymagane do synchronizacji grup Entra ID)
• Azure / Entra ID OAuth2
• Integracja z SharePoint
• Agents API (Zdalni agenci)
• Panel administratora LibreChat