Authentik: self-hosted SSO для ваших застосунків

Один вхід для всіх розміщених вами застосунків

Authentik — це self-hosted сервер SSO (єдиного входу): користувачі входять один раз, після чого всі застосунки за ним приймають цю сесію, а не запитують власний пароль. Встановлення виконується за допомогою офіційного Docker Compose-файлу та двох згенерованих секретів. Найбільше уваги потребує подальше налаштування: спрямувати на нього reverse proxy і розмістити один наявний застосунок за forward auth.

Authentik постачається як три сервіси в цьому Compose-файлі: база даних PostgreSQL, процес server і процес worker. Контейнер сервера також запускає вбудований outpost — компонент, який для кожного захищеного застосунку визначає, чи автентифіковано запит. Версія 2026.5 є поточним релізом станом на July 2026, а проєкт рекомендує хост щонайменше з 2 CPU cores і 2 GB RAM. Вважайте це мінімальною конфігурацією. PostgreSQL і worker використовують пам’ять після того, як сервер працює протягом доби.

Що потрібно підготувати

Потрібен Docker Engine із плагіном Compose v2. Перевірити це можна командою docker compose version. Якщо замість версії команда виводить помилку, спочатку встановіть плагін. Основні відомості наведено в матеріалі запуск застосунків за допомогою Docker Compose на VPS. Також потрібен DNS-запис A, що вказує на сервер. У наведених нижче прикладах це auth.example.com. Authentik формує URL-адреси перенаправлення на основі імені хоста, яке використав браузер.

Запускайте стек від імені звичайного користувача з групи docker, а не від імені root. Членство в цій групі фактично надає права root на хості, тому додайте до неї лише один обліковий запис для розгортання і не додавайте інших користувачів. Дотримуйтеся підходу, описаного в матеріалі облікові записи з мінімальними привілеями на VPS.

Встановлення з офіційним файлом Compose

sudo install -d -o "$USER" -g "$USER" /opt/authentik
cd /opt/authentik
wget https://docs.goauthentik.io/compose.yml
echo "PG_PASS=$(openssl rand -base64 36 | tr -d '\n')" >> .env
echo "AUTHENTIK_SECRET_KEY=$(openssl rand -base64 60 | tr -d '\n')" >> .env
docker compose pull
docker compose up -d

docker compose ps має показати три контейнери. postgresql має повідомляти healthy і server, а worker — running. Під час першого запуску виконуються міграції бази даних, тому зачекайте хвилину, перш ніж вебінтерфейс почне відповідати.

Обидва згенеровані значення важливі, але з різних причин. PG_PASS — це пароль PostgreSQL, максимальна довжина якого становить 99 символів. AUTHENTIK_SECRET_KEY використовується для підписування сеансів і токенів. Якщо змінити це значення пізніше, усі користувачі вийдуть із системи, а всі видані вами API-токени стануть недійсними. Для .env встановіть режим 600 і зберігайте копію в безпечному місці. База даних, відновлена без відповідного секретного ключа, буде недоступна для входу.

Файл Compose читає обидва значення у формі ${PG_PASS:?database password required}. Тому Compose відмовляється запускатися, якщо файл відсутній. Запуск docker compose up -d з неправильного каталогу виводить required variable AUTHENTIK_SECRET_KEY is missing a value: secret key required і завершується. Це проблема шляху, а не конфігурації.

Значення середовища, які мають значення

Усе інше додається до того самого файлу .env. Authentik перетворює подвійне підкреслення на вкладений ключ конфігурації, тому AUTHENTIK_EMAIL__HOST задає email.host. Одинарне підкреслення ігнорується без попередження. Це найпоширеніша причина, через яку параметр не працює.

• AUTHENTIK_BOOTSTRAP_PASSWORD задає пароль вбудованого користувача akadmin під час першого запуску. Тому пароль не потрібно вводити у відкриту вебформу. AUTHENTIK_BOOTSTRAP_EMAIL і AUTHENTIK_BOOTSTRAP_TOKEN так само задають адресу цього користувача й API-токен.
• COMPOSE_PORT_HTTP і COMPOSE_PORT_HTTPS переносять опубліковані порти зі стандартних значень 9000 і 9443.
• AUTHENTIK_EMAIL__HOST, AUTHENTIK_EMAIL__PORT, AUTHENTIK_EMAIL__USERNAME, AUTHENTIK_EMAIL__PASSWORD, AUTHENTIK_EMAIL__USE_TLS і AUTHENTIK_EMAIL__FROM налаштовують вихідну пошту. Без них Authentik намагається використовувати localhost через порт 25, тому листи для скидання пароля завершуються помилкою підключення в журналі worker.
• AUTHENTIK_LOG_LEVEL=debug вмикає докладні повідомлення, потрібні під час помилкової роботи login flow. Після цього поверніть значення info.
• За замовчуванням AUTHENTIK_ERROR_REPORTING__ENABLED має значення false. Встановлюйте true, лише якщо ви погоджуєтеся надсилати звіти про аварійне завершення upstream.

Це секрети у звичайному файлі, тому захищайте цей каталог так само, як будь-яке інше сховище облікових даних. Менеджер паролів, наприклад self-hosted екземпляр Vaultwarden, є безпечнішим місцем для резервної копії, ніж нотатка на ноутбуці.

Перший вхід і обліковий запис адміністратора

Відкрийте http://SERVER_IP:9000 у браузері. Authentik покаже початковий процес налаштування та попросить задати пароль для стандартного користувача akadmin. Якщо ви вже налаштували AUTHENTIK_BOOTSTRAP_PASSWORD, цей крок виконано, і ви одразу перейдете на сторінку входу.

Створіть для себе звичайний обліковий запис адміністратора в розділі Directory, потім Users, додайте його до групи authentik Admins і увійдіть під цим обліковим записом. Залиште akadmin як аварійний обліковий запис із довгим паролем, збереженим офлайн. Щоденна робота під спільним вбудованим обліковим записом руйнує журнал аудиту, оскільки в кожній події зазначено akadmin, але не вказано, хто саме виконав дію. Це також стосується систем, які працюють за Authentik: наприклад, self-hosted OneCLI harness, який надає кожному користувачеві власного агента, залишає зрозумілий слід лише тоді, коли ідентичність, що надходить до нього, належить одній конкретній людині, а не обліковому запису, спільному для всієї команди.

Розмістіть Authentik за reverse proxy

Публікація порту 9000 в інтернет працює, але вам потрібен TLS (захист транспортного рівня) і справжнє доменне ім’я. Якщо ви вже використовуєте конфігурацію з Traefik як reverse proxy для кількох Compose-застосунків, підключіть Authentik до тієї самої зовнішньої мережі proxy за допомогою override-файлу. Створіть docker-compose.override.yml поруч із compose.yml:

services:
  server:
    networks:
      - default
      - proxy
    labels:
      traefik.enable: "true"
      traefik.docker.network: proxy
      traefik.http.routers.authentik.rule: Host(`auth.example.com`)
      traefik.http.routers.authentik.entrypoints: websecure
      traefik.http.routers.authentik.tls.certresolver: le
      traefik.http.services.authentik.loadbalancer.server.port: "9000"

networks:
  proxy:
    external: true

Застосуйте зміни за допомогою docker compose up -d. Compose автоматично об’єднає override-файл, тому сервіс server збереже всі параметри з офіційного файлу та отримає ці labels. Перевірте результат за допомогою curl -I https://auth.example.com/if/user/. Команда має повернути HTTP/2 200. Помилка 404 page not found від Traefik означає, що контейнер не підключений до мережі proxy, і Traefik не може маршрутизувати запит до контейнера, якого не бачить.

Коли доменне ім’я запрацює, прив’яжіть опубліковані порти до 127.0.0.1 в override-файлі, щоб єдиним шляхом доступу залишався proxy.

Захистіть один застосунок за допомогою forward auth

У Authentik proxy provider має три режими, і неправильний вибір може коштувати години роботи. Proxy означає, що сам outpost пересилає трафік до upstream-застосунку. Forward auth (single application) означає, що ваш reverse proxy і далі передає трафік, а Authentik лише перевіряє, чи автентифіковано запит. Forward auth (domain level) захищає всі застосунки в одному батьківському домені за допомогою одного provider, але без окремих правил авторизації для кожного застосунку. Якщо перед Authentik використовується Traefik, вибирайте forward auth (single application). Для практики можна взяти конкретний застосунок, наприклад self-hosted робочий простір AFFiNE. Це типовий внутрішній інструмент, який має бути доступним із ваших пристроїв і більше нізвідки. Для командного інструмента перевага ще очевидніша: розмістіть self-hosted службу підтримки Chatwoot за тим самим provider, і кожен, хто відповідає на звернення, входить один раз на день замість того, щоб передавати один одному ще один пароль.

У вебінтерфейсі відкрийте Applications, потім Providers, створіть Proxy Provider, виберіть режим forward auth single application і вкажіть зовнішній хост https://app.example.com. Створіть Application, який посилається на цей provider. Потім відкрийте Outposts, відредагуйте authentik Embedded Outpost і додайте новий застосунок до списку вибраних застосунків. Outpost відповідає лише за ті застосунки, які йому призначено. Тому пропуск останнього кроку призводить до того, що правильно налаштований provider не повертає відповіді.

Визначте middleware один раз для контейнера Authentik і посилайтеся на нього з кожного захищеного застосунку:

      traefik.http.middlewares.authentik.forwardauth.address: http://server:9000/outpost.goauthentik.io/auth/traefik
      traefik.http.middlewares.authentik.forwardauth.trustForwardHeader: "true"
      traefik.http.middlewares.authentik.forwardauth.authResponseHeaders: X-authentik-username,X-authentik-groups,X-authentik-email,X-authentik-name,X-authentik-uid,X-authentik-jwt,X-authentik-meta-jwks,X-authentik-meta-outpost,X-authentik-meta-provider,X-authentik-meta-app,X-authentik-meta-version

authResponseHeaders — це список заголовків, які Traefik копіює з відповіді Authentik у запит до upstream-застосунку. Якщо не вказати цей список, застосунок усе одно буде захищено, але він не дізнається, хто саме виконав вхід. Тому все, що читає X-authentik-username для автоматичного входу, залишатиметься неавторизованим.

Для самого захищеного застосунку потрібні два routers, а не один:

    labels:
      traefik.enable: "true"
      traefik.http.routers.myapp.rule: Host(`app.example.com`)
      traefik.http.routers.myapp.entrypoints: websecure
      traefik.http.routers.myapp.tls.certresolver: le
      traefik.http.routers.myapp.middlewares: authentik@docker
      traefik.http.routers.myapp-auth.rule: Host(`app.example.com`) && PathPrefix(`/outpost.goauthentik.io/`)
      traefik.http.routers.myapp-auth.entrypoints: websecure
      traefik.http.routers.myapp-auth.tls.certresolver: le
      traefik.http.routers.myapp-auth.priority: "15"
      traefik.http.routers.myapp-auth.service: authentik

Другий router часто пропускають. Після входу Authentik повертає браузер на шлях під /outpost.goauthentik.io/ на hostname застосунку, а не на auth.example.com. Якщо немає router, який передає цей префікс шляху до сервісу Authentik, запит потрапляє до вашого застосунку. Він повертає 404, і вхід не завершується. Вищий priority забезпечує пріоритет конкретного правила для цього шляху над звичайним правилом Host() для того самого домену.

Перевірте конфігурацію у приватному вікні браузера. Вас має перенаправити на auth.example.com. Виконайте вхід і поверніться до застосунку. docker compose logs -f server на стороні Authentik виводить подію авторизації для кожної спроби. Це дає змогу визначити, чи досяг запит Authentik взагалі.

Фактичні помилки, з якими ви зіткнетеся

Нескінченний цикл перенаправлення між застосунком і сторінкою входу. Зовнішній хост у провайдера не відповідає хосту, який використовує браузер: зазвичай http:// у провайдера та https:// в адресному рядку. Тоді session cookie встановлюється для іншого origin, тому кожне повернення виглядає як новий анонімний запит. Виправте зовнішній хост і видаліть cookie для обох доменів перед повторною перевіркою.

404 на /outpost.goauthentik.io/start. Відсутній router outpost або його пріоритет нижчий за catch-all router для цього хоста.

Застосунок завантажується, але не запитує дані для входу. Мітка middlewares вказує на middleware, якого не існує. Traefik не повідомляє про це, тому помилка в authentik@docker просто означає, що middleware не запускається. Відкрийте панель Traefik і переконайтеся, що router містить цей middleware.

403 від Authentik після успішного входу. Користувач пройшов автентифікацію, але не має авторизації: для застосунку налаштовано прив’язку policy або вимогу щодо групи, якій цей користувач не відповідає. У журналі Events в адміністративному інтерфейсі вказано policy, яка відхилила запит.

Коли Keycloak є кращим вибором

Keycloak — старіший проєкт, який підтримує Red Hat. Це надійніший вибір для класичних корпоративних завдань керування ідентифікацією: інтенсивного використання SAML federation, брокеризації входу через кількох зовнішніх identity provider одночасно, а також експорту й імпорту realm як задокументованого шляху міграції. Для деяких організацій важливе й комерційне support, яке стоїть за цим проєктом. Компроміс полягає в тому, що Keycloak не має власного proxy. Тому для захисту застосунку, який не підтримує OIDC (OpenID Connect), потрібно запускати поруч із ним щось на зразок oauth2-proxy. Вбудований proxy provider в Authentik виконує цю функцію та вже інтегрований у систему. Саме тому більшість self-hosters із різнорідним набором застосунків обирають Authentik.

Резервне копіювання та оновлення

Для відновлення потрібні три компоненти: база даних PostgreSQL, каталог ./data і .env.

cd /opt/authentik
docker compose exec -T postgresql pg_dump -U authentik authentik | gzip > authentik-$(date +%F).sql.gz

Зберігайте цей дамп разом із .env. Самого дампу недостатньо, оскільки секретний ключ, який захищає дані сеансів і токенів, зберігається в .env.

Оновлення полягає у зміні тегу. Установіть AUTHENTIK_TAG у .env на потрібний вам реліз, а потім виконайте docker compose pull і docker compose up -d. Спочатку прочитайте примітки до релізу, оскільки Authentik використовує версії на основі дат, а деякі релізи містять міграції, які передбачають оновлення з попередньої версії. Створіть дамп бази даних до виконання pull, а не після нього.

FAQ

Чи можна безкоштовно розгорнути Authentik на власній інфраструктурі?

Версія з відкритим вихідним кодом безкоштовна й охоплює все описане вище: proxy provider, forward auth, OIDC (OpenID Connect), SAML і flows engine. Платний enterprise tier додає підтримку та деякі enterprise-функції, але для описаної конфігурації ліцензія не потрібна.

Чи потрібен Traefik для використання Authentik?

Ні. Forward auth працює з nginx через auth_request і з Caddy через forward_auth. У всіх випадках використовується однакова схема: reverse proxy надсилає Authentik запит щодо кожного запиту, а префікс шляху /outpost.goauthentik.io/ на захищеному хості має спрямовуватися до Authentik, а не до застосунку.

Чому захищений застосунок постійно перемикається між сторінкою входу та помилкою?

Зовнішній хост, налаштований у proxy provider, не відповідає URL, який використовує браузер, найчастіше http замість https. Сеансовий cookie створюється для одного origin, а читається з іншого, тому Authentik щоразу отримує анонімний запит. Виправте зовнішній хост, а потім видаліть cookies для обох імен хостів перед повторною перевіркою.

Скільки RAM потрібно Authentik?

Станом на July 2026 документований мінімум становить 2 CPU cores і 2 GB RAM для PostgreSQL, сервера та worker разом. На сервері з 2 GB RAM worker стає першим процесом, який kernel завершує під час нестачі пам’яті. У результаті фонові завдання та вихідна електронна пошта припиняють працювати, хоча сторінка входу залишається доступною. Виділіть 4 GB RAM, якщо на тому самому сервері також працюють застосунки, які ви захищаєте.