Authentik: self-hosted SSO через Docker Compose

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

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

Authentik постачається як три сервіси в цьому Compose-файлі: база даних PostgreSQL, процес server і процес worker. Контейнер сервера також запускає вбудований outpost — компонент, який для кожного захищеного застосунку відповідає на запит «чи автентифікований цей запит?». Версія 2026.8.5 є поточним релізом станом на 25 October 2026. Її опубліковано 21 October 2026 як останній patch-реліз серії 2026.8, що почалася з 2026.8.0 18 August. Вона замінює 2026.8.4 від 14 October як стандартний тег образу в офіційному Compose-файлі. Проєкт вимагає хост щонайменше з 2 CPU cores і 2 GB RAM. Вважайте це мінімальними вимогами. PostgreSQL і worker споживають пам’ять після того, як сервер працює протягом доби.

Що потрібно підготувати перед початком

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

Запускайте stack від імені звичайного користувача, доданого до групи docker, а не від імені root. Членство в цій групі фактично надає права root на хості, тому додайте до неї один deploy-акаунт і не додавайте інших користувачів, як описано в матеріалі облікові записи користувачів із мінімальними привілеями на 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 після успішної перевірки. Під час першого запуску виконуються міграції бази даних, тому зачекайте хвилину, перш ніж вебінтерфейс почне відповідати.

Обидва згенеровані значення важливі, але з різних причин. PG_PASS — це пароль PostgreSQL. В інструкції з встановлення Authentik зазначено, що паролі довші за 99 символів не підтримуються, тому самостійно вибраний пароль має бути коротшим; згенерований пароль значно коротший. AUTHENTIK_SECRET_KEY — це ключ, який Authentik використовує для підпису cookie. У документації з конфігурації зазначено, що його зміна робить активні сесії недійсними, тому новий ключ виведе з облікових записів усіх користувачів. Встановіть для .env права доступу mode 600 і збережіть копію в безпечному місці разом із резервними копіями, щоб після відновлення використовувався той самий ключ.

Compose-файл позначає обидва значення як обов’язкові за допомогою форми ${VAR:?message}: ${PG_PASS:?database password required} для сервісу PostgreSQL і ${AUTHENTIK_SECRET_KEY:?secret key required} для server та worker. Це означає, що 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, лише якщо погоджуєтеся надсилати звіти про збої розробникам.

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

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

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

Створіть для себе звичайного адміністратора в розділі Directory, потім Users, додайте його до групи authentik Admins і ввійдіть під цим обліковим записом. Залиште akadmin як аварійний обліковий запис із довгим паролем, збереженим офлайн. Якщо помилковий flow або stage заблокує вам доступ, docker compose run --rm server create_recovery_key 10 akadmin, запущений із /opt/authentik, виведе посилання для безпосереднього входу як akadmin. Будь-хто, хто має це посилання, отримає такий самий доступ, тому поводьтеся з ним як із паролем. Щоденна робота під спільним вбудованим обліковим записом руйнує audit log, оскільки кожна подія містить 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 означає, що жоден router не зіставив запит. Перевірте, чи передалися labels контейнеру, чи правило Host() точно відповідає імені хоста та чи надійшов запит на HTTPS entry point, на якому прослуховується router.

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

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

Proxy provider в Authentik має три режими, і неправильний вибір може коштувати години роботи. Proxy означає, що сам outpost пересилає трафік до upstream-застосунку. Forward auth (single application) означає, що ваш reverse proxy і далі передає трафік, а лише запитує Authentik, чи виконано вхід для запиту. Forward auth (domain level) захищає всі застосунки в одному батьківському домені за допомогою одного provider, але без окремих правил авторизації для кожного застосунку. Якщо перед ним працює 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 і додайте новий застосунок до його selected applications. 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-entitlements,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 для автоматичного входу, залишатиметься без авторизації. Це особливо помітно перед застосунком із власною системою входу, наприклад self-hosted трекером тренувань openGym і його входом за passkey: заголовки визначають, чи побачить користувач один запит замість двох на тій самій сторінці.

Для самого захищеного застосунку потрібні два 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/ на хості застосунку, а не на auth.example.com. Якщо немає router, який передає цей префікс шляху сервісу Authentik, запит потрапляє до вашого застосунку. Той повертає 404, і вхід не завершується. Більше значення priority забезпечує перевагу конкретного правила для шляху над звичайним правилом Host() у тому самому домені.

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

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

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

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

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

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

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

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

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

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

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

Зберігайте цей dump і .env разом. Dump не містить копії AUTHENTIK_SECRET_KEY, а відновлення з іншим ключем зробить усі активні сесії недійсними. Тому збереження оригінального ключа дає змогу відновленому серверу продовжити роботу без змін.

Оновлення виконуються зміною тега. Встановіть AUTHENTIK_TAG у .env на потрібний реліз, потім виконайте docker compose pull, а після цього docker compose up -d. Якщо AUTHENTIK_TAG не встановлено, версія береться зі стандартного значення, записаного безпосередньо в compose.yml. Тому завантаження новішої копії цього файлу є оновленням — саме цей спосіб описано в офіційній документації з оновлення. Спочатку прочитайте release notes. Authentik використовує версії на основі дат. Станом на October 2026 у документації зазначено, що оновлення мають виконуватися послідовно між major releases: спочатку перейти на останній patch-реліз поточної серії, а потім послідовно пройти кожну наступну серію без пропусків. Authentik не підтримує downgrading, тому створіть dump бази даних перед pull, а не після нього.

FAQ

Чи безкоштовний Authentik для self-hosting?

Версія з відкритим кодом безкоштовна та охоплює все описане вище: 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?

Станом на October 2026 задокументований мінімум становить 2 CPU cores і 2 GB RAM для PostgreSQL, server і worker разом. На сервері з 2 GB дефіцит пам’яті може активувати kernel's OOM killer. Він завершує процес із найвищим badness score: приблизно за часткою дозволеної пам’яті, яку процес використовує, плюс його oom_score_adj. Якщо таким процесом виявляється worker, фонові завдання та вихідна електронна пошта припиняються, але сторінка входу продовжує працювати. Виділіть 4 GB, якщо на тому самому сервері також працюють застосунки, які ви захищаєте.