Перейти до основного вмісту

Автентифікація та безпека

Libre WebUI використовує локальні облікові записи із сеансами JWT. Нове встановлення завжди дозволяє створити одного локального адміністратора. Публічна реєстрація всіх наступних локальних або OAuth-облікових записів типово закрита.

Перше налаштування​

Коли в базі немає користувачів:

  1. Libre WebUI показує початковий процес.
  2. Користувач створює перший локальний обліковий запис.
  3. Він отримує роль admin.
  4. Наступні публічні реєстрації залишаються закритими до явного ввімкнення.

Наявні бази зберігають користувачів і ролі.

Локальні облікові записи​

Реєстрація потребує:

  • Ім’я користувача
  • Пароль від 12 символів до 72 байтів UTF-8 з великими й малими літерами та цифрою
  • Необов’язкову електронну пошту

Паролі хешуються bcrypt до зберігання. Маршрути входу й реєстрації мають обмеження частоти.

Схвалення реєстрації​

Публічна реєстрація сама не надає доступ. Кожен обліковий запис із публічної форми або OAuth починає у стані pending і потребує схвалення адміністратора.

Виняток — перший справжній обліковий запис у порожній базі: він атомарно створюється active з роллю admin, щоб нове встановлення мало робочого адміністратора. Усі наступні чекають перевірки.

Користувач у стані очікування бачить:

  • Реєстрація успішна, але без токена сеансу. API повертає 202 з approvalRequired: true, а інтерфейс пояснює потребу схвалення.
  • Вхід із правильним паролем відхиляється 403 із кодом ACCOUNT_PENDING ("Your account is waiting for administrator approval"). OAuth повертає на сторінку входу з ?approval=pending.
  • Стан облікового запису читається з бази за кожним автентифікованим запитом, тому сеанс не переживе втрату стану active.

Адміністратор бачить:

  • Картку Очікують схвалення зі списком, дією Активувати обліковий запис і відхиленням. Відхилення означає видалення; окремого призупиненого стану немає.
  • Під час входу — позначку в розділі Користувачі й спливне повідомлення про нову реєстрацію. Зведення опитується приблизно щохвилини (GET /api/users/pending-approvals, лише адміністратори).
  • Схвалення (PATCH /api/users/:id/approve) записує адміністратора й час, але не змінює роль: обліковий запис лишається user до підвищення. Воно діє під час наступної спроби входу.

Оновлення не впливає на наявні облікові записи: очікують лише створені публічно після появи функції. Створені адміністратором активні відразу.

Навмисне ввімкнення публічної реєстрації​

Типово реєстрацію вимкнено. Задавайте змінну лише на час приймання нових локальних або OAuth-користувачів:

ENABLE_SIGNUP=true

Після запланованого вікна поверніть false. Наявні користувачі все одно можуть входити, а адміністратори — створювати облікові записи.

Порожня база завжди дозволяє одного локального адміністратора навіть при ENABLE_SIGNUP=false; OAuth не може зайняти це місце. Для приватного віддаленого розгортання спочатку захистіть хост списком ідентичностей, наприклад Cloudflare Access, а тоді створіть адміністратора через захищений маршрут.

Ролі​

РольПризначення
adminКерування інстанцією, користувачами, системними параметрами та довірене керування середовищем Work
userЗвичайні чати, моделі, персони, документи й налаштування

Установлення, видалення, копіювання, надсилання та вивантаження моделей доступні лише адміністраторам, бо змінюють ресурси хоста.

Доступ Work​

Work типово обмежено адміністраторами, оскільки модель виконує довільні команди в керованому контейнері. Адміністратор може відкрити Work усім активним користувачам на вкладці Керування користувачами в Налаштуваннях; налаштування зберігається, діє одразу й охоплює відкриті термінали. Робочі області в папках хоста завжди лишаються лише адміністративними, бо підключають шляхи сервера. Усіх користувачів Work вважайте довіреними операторами середовища.

Авторизація адміністратора перевіряє поточну роль у базі, а не лише JWT. Пониження одразу відкликає Work, після чого сервер намагається перервати запуски та зупинити контейнери й перегляди, зберігаючи записи й томи. Якщо очищення Docker не вдалося, доступ не повертається, зміна ролі повідомляє помилку, а оператор має відновити Docker і повторити очищення.

Видалення користувача знищує його дані Work. Libre спочатку зупиняє контейнери й видаляє томи, потім обліковий запис і записи бази. Якщо Docker не підтвердив очищення, видалення не виконується, щоб адміністратор міг виправити проблему й повторити.

Групи й дозволи ресурсів​

Адміністратори створюють групи й керують членством. Групи є суб’єктами дозволів: власник чату, нотатки, документа, колекції, папки, персони, промпту, навички або календаря може надати read, write чи admin користувачеві або групі через спільний діалог (див. Спільний доступ); так само обмежуються сервери інструментів. Ресурси типово приватні — глобальна роль admin не відкриває чужий вміст. Членство перевіряється під час запиту, тому видалення учасника негайно відкликає доступ. Перегляд ефективного доступу на вкладці Керування користувачами в Налаштуваннях пояснює його через роль, групи, функції й усі дозволи.

Журнал аудиту безпеки​

Входи й помилки, виходи, відкликання сеансів і токенів, зміни користувачів, груп, дозволів і токенів записуються в окремий журнал лише для додавання. Перед зберіганням подробиці редагуються: секретоподібні ключі відкидаються, розміри обмежуються, тому паролі, токени й промпти не потрапляють до журналу. Зміни груп і дозволів записують подію в тій самій транзакції. Адміністратори переглядають журнал на вкладці Керування користувачами в Налаштуваннях; типовий строк — 180 днів (AUDIT_RETENTION_DAYS).

Сеанси​

Сервер підписує JWT через JWT_SECRET. Для промислового середовища задайте стабільний секрет:

JWT_SECRET=replace-with-a-long-random-secret

Зміна JWT_SECRET скасовує наявні сеанси. Локальні й OAuth-токени використовують JWT_EXPIRES_IN, типово 7d; зміна впливає на нові сеанси. WebSocket обмінює постійний токен на короткий одноразовий квиток і закривається після завершення базового сеансу.

Кожен вхід створює серверний запис сеансу, прив’язаний до JWT. Налаштування → Сеанси показує пристрої, спосіб входу, першу й останню активність та строк. Відкликання або «Вийти з інших сеансів» негайно скасовує токен на всіх репліках і закриває WebSocket; вихід так само скасовує поточний. Старі токени без ID діють до завершення, але новий вхід із виходом з інших сеансів також ставить граничний час для їх відхилення.

Двофакторна автентифікація та ключі доступу​

Налаштування → Сеанси керує другим фактором і входом без пароля:

  • Застосунок автентифікації (TOTP). Реєстрація показує base32-секрет і посилання otpauth://; перший 6-значний код активує й відкриває десять одноразових кодів відновлення. Потім пароль повертає короткий виклик, а POST /api/auth/mfa/verify завершує вхід кодом TOTP або відновлення. Використаний часовий крок записується проти повтору; коди відновлення зберігаються лише як односторонні токени й працюють один раз. Вимкнення або нові коди потребують повторного підтвердження фактора.
  • Ключі доступу (WebAuthn). «Увійти з ключем доступу» використовує видимі облікові дані без пароля з обов’язковою перевіркою користувача — блокуванням екрана, біометрією або PIN. Attestation приймається як none, підтримуються ES256 і EdDSA, матеріал шифрується, а ID зберігається як токен пошуку. Виклики одноразові й спливають за п’ять хвилин; ненульовий лічильник підпису, що не зростає, вважається ознакою клону. Потрібне безпечне HTTPS-походження або localhost; задайте WEBAUTHN_RP_ID для кількох імен хоста.

Токен виклику MFA після правильного пароля підписано секретом, похідним, але відмінним від JWT_SECRET: він не автентифікує API, прив’язаний до одного облікового запису й призначення та споживається після успіху.

Адміністратор може вимагати другий фактор для всіх через картку політики або MFA_REQUIRED_MODE=required. Користувач без фактора проходить реєстрацію під час наступного входу до видачі сеансу. Адміністратор може скинути TOTP для відновлення; ключі доступу лишаються під керуванням користувача. Усі реєстрації, активації, помилки, вимкнення, політики, ключі й адміністративні скидання записуються в аудит.

MFA застосовується до паролів. OAuth та OIDC покладаються на другий фактор провайдера й не запитуються повторно. Токени API не залежать від сеансів.

Токени API​

Налаштування → Ключі API створює особисті токени з префіксом lwk_. Секрет показується раз і зберігається лише як хеш. Токен має явні області (chat, models, documents, notes, personas, media, work, admin); кожна родина маршрутів потребує свою, тому токен нотаток не відкриє чати чи адміністрацію, а керування сеансами недоступне. Токени можуть мати строк, відстежують останнє використання, відкликаються й обмежуються за частотою на всіх репліках. Область admin створює лише адміністратор і під час використання все одно потребує цієї ролі. Область chat також є ключем публічного API /v1.

Cloudflare Turnstile​

Turnstile захищає вхід і реєстрацію, коли задано обидва ключі:

TURNSTILE_SITE_KEY=...
TURNSTILE_SECRET_KEY=...
TURNSTILE_EXPECTED_HOSTNAME=chat.example.com

Фронтенд задає окремі дії login і signup. Сервер перевіряє токен у Cloudflare та відхиляє невідповідне ім’я хоста або дію. BASE_URL задає очікуване ім’я, якщо TURNSTILE_EXPECTED_HOSTNAME не встановлено. Без одного з ключів Turnstile вимкнено.

GitHub OAuth​

GITHUB_CLIENT_ID=...
GITHUB_CLIENT_SECRET=...
GITHUB_CALLBACK_URL=https://your-domain.example/api/auth/oauth/github/callback

Потік створює локальних користувачів із префіксом gh_ і типовою роллю user.

Hugging Face OAuth​

HUGGINGFACE_CLIENT_ID=...
HUGGINGFACE_CLIENT_SECRET=...
HUGGINGFACE_CALLBACK_URL=https://your-domain.example/api/auth/oauth/huggingface/callback

Потік створює користувачів із префіксом hf_ і типовою роллю user.

Обидва провайдери використовують криптографічно випадковий state, прив’язаний до короткого HttpOnly SameSite cookie. Зворотний виклик відхиляє відсутній або невідповідний стан. Після успіху JWT повертається фронтенду в 60-секундному HttpOnly cookie, одразу обмінюється й очищається; bearer-токени не потрапляють до URL, історії або referrer.

Перенаправлення та CORS​

Задайте BASE_URL для типових зворотних викликів і CORS_ORIGIN для доступу браузера:

BASE_URL=https://your-domain.example
CORS_ORIGIN=https://your-domain.example

Для локальної розробки додайте походження Vite:

CORS_ORIGIN=http://localhost:5173,http://127.0.0.1:5173

Демонстраційний режим​

Це режим попереднього перегляду фронтенду з вимкненими демонстраційними обліковими даними та імітованими відповідями API. Він не призначений для промислової автентифікації.

Контрольний список безпеки​

  • Задайте надійний JWT_SECRET.
  • Зберігайте DATA_DIR у постійному сховищі з контролем доступу.
  • Копіюйте ENCRYPTION_KEY разом із базою.
  • Налаштуйте Turnstile для публічної реєстрації.
  • Використовуйте HTTPS у публічних розгортаннях.
  • Обмежуйте ключі провайдерів мінімальною областю.
  • Точно задавайте URL зворотних викликів OAuth.
  • Надавайте Work лише людям, яким довіряєте керування контейнерним середовищем сервера.

Пов’язана документація​