Від Matt Connor 2026-07-31 · Оновлено 2026-08-01

Authentik: SSO для застосунків у Docker Compose

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

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

Розгорніть Authentik у Docker Compose: потрібні env-змінні, запуск akadmin і forward auth через Traefik для єдиного входу до всіх застосунків.

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

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

Authentik складається з трьох сервісів у цьому файлі Compose: бази даних PostgreSQL, процесу server і процесу worker. Контейнер сервера також запускає вбудований outpost. Це компонент, який для кожного захищеного застосунку визначає, чи виконано вхід для цього запиту. Версія 2026.5 є поточним випуском станом на липень 2026 року. Проєкт рекомендує хост щонайменше з 2 ядрами CPU і 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 вмикає потрібний рівень деталізації, коли потік входу працює неправильно. Після цього поверніть значення info.
За замовчуванням AUTHENTIK_ERROR_REPORTING__ENABLED має значення false. Встановлюйте true, лише якщо ви погоджуєтеся надсилати звіти про аварійне завершення роботи розробникам.

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

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

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

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

Розмістіть Authentik за зворотним проксі

Публікація порту 9000 в інтернет працює, але потрібні TLS (захист транспортного рівня) і справжнє ім’я хоста. Якщо ви вже використовуєте конфігурацію з Traefik як зворотний проксі для кількох застосунків Compose, підключіть Authentik до тієї самої зовнішньої мережі proxy за допомогою файла перевизначення. Створіть 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 автоматично об’єднає конфігурації, тому сервіс server збереже всі параметри з офіційного файла й отримає ці мітки. Перевірте за допомогою curl -I https://auth.example.com/if/user/. У відповідь має бути HTTP/2 200. Відповідь 404 page not found від Traefik означає, що контейнер не підключений до мережі proxy. Traefik не може маршрутизувати трафік до контейнера, якого не може досягти.

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

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

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

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

Визначте 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 для автоматичного входу, залишатиметься неавторизованим.

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

    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

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

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

Збої, з якими ви фактично зіткнетеся

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

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

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

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

Коли Keycloak краще підходить

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

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

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

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

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

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

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

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

#authentik#sso#authentication#self-hosting #docker-compose #traefik