Authelia на Ubuntu 24.04: пошаговая установка

MAATRIX

Если за одним VPS у вас крутится несколько self-hosted сервисов без встроенной 2FA — панель мониторинга, внутренний дашборд, админка CI — рано или поздно встаёт вопрос, как закрыть их все одним слоем входа, не переписывая каждый сервис отдельно. Authelia решает это как forward-auth: лёгкий Go-бинарник, который встаёт перед Nginx или Traefik и проверяет логин с TOTP до того, как запрос долетит до реального приложения. Ниже — пошаговая установка на чистом Ubuntu 24.04: от Docker-контейнера до рабочей связки с reverse proxy.

Что такое forward-auth и зачем здесь Authelia

Схема forward-auth простая: реверс-прокси перед тем, как отдать запрос сервису, сначала стучится в отдельный внутренний эндпоинт — спрашивает «этот пользователь прошёл аутентификацию?». У Nginx это директива auth_request, у Traefik — middleware forwardAuth. Authelia отвечает на этот вопрос: держит сессию пользователя, проверяет пароль и второй фактор, а прокси лишь пропускает или блокирует запрос по её вердикту. Сам сервис за прокси вообще не знает про существование Authelia — ему просто не долетает трафик от тех, кто не прошёл проверку.

Ключевое отличие от Keycloak в том, что Authelia не строит SSO-протоколы OIDC/SAML для каждого приложения — она защищает сам вход на уровне прокси. Это узкая, но частая задача: закрыть паролем и TOTP группу внутренних сервисов, у которых нет собственной авторизации. Если вам нужна полноценная федерация identity-провайдеров или тонкие ролевые модели для десятков приложений — присмотритесь к Keycloak на Ubuntu 24.04, это другой класс задачи. Authelia же весит в разы меньше: контейнеру хватает 50-100 МБ RAM в простое, тогда как Java-процесс Keycloak просит от полугигабайта уже на старте.

Шаг 1. Подготовка сервера и Docker

Возьмите чистый VPS с Ubuntu 24.04 и root-доступом. Ресурсы под саму Authelia минимальны — 1 vCPU и 1 ГБ RAM с запасом хватит и на неё, и на проксируемые сервисы среднего размера. Обновите систему и поставьте Docker официальным скриптом:

apt update && apt upgrade -y
curl -fsSL https://get.docker.com | sh
systemctl enable --now docker
docker compose version

Откройте нужные порты в фаерволе. Наружу смотрит только reverse proxy — сама Authelia работает внутри Docker-сети и наружу не публикуется:

ufw allow 22/tcp
ufw allow 80/tcp
ufw allow 443/tcp
ufw enable

Заранее заведите поддомен для самой Authelia (например, auth.example.com) и убедитесь, что его A-запись указывает на IP вашего сервера — на этот адрес будет уходить редирект при логине. Локацию сервера выбирайте по тому, где физически сидят пользователи защищённых сервисов: RU для доступа из России с минимальной задержкой, US или UK — если аудитория за рубежом. У MAATRIX доступны все три локации с оплатой из России картой, СБП или криптовалютой.

Шаг 2. Каталоги, конфиг и секреты

Создайте рабочий каталог и структуру, которую ждёт Authelia:

mkdir -p /opt/authelia/config
cd /opt/authelia

Секреты — обязательная часть настройки: Authelia отказывается стартовать без корректных ключей для JWT и шифрования сессий. Сгенерируйте их случайными строками и сохраните в отдельный файл окружения, а не в самом конфиге:

cat > .env <<'EOF'
AUTHELIA_JWT_SECRET=$(openssl rand -hex 32)
AUTHELIA_SESSION_SECRET=$(openssl rand -hex 32)
AUTHELIA_STORAGE_ENCRYPTION_KEY=$(openssl rand -hex 32)
EOF

Обратите внимание: команда выше подставит буквальный текст $(openssl rand -hex 32), а не результат вычисления, если запускать её как есть через cat с heredoc в кавычках 'EOF' — уберите кавычки у EOF или сгенерируйте три значения отдельно и вставьте вручную:

openssl rand -hex 32   # выполните трижды, вставьте значения в .env

Теперь опишите сам сервис в compose.yaml:

services:
  authelia:
    image: authelia/authelia:latest
    container_name: authelia
    restart: unless-stopped
    env_file: .env
    volumes:
      - ./config:/config
    networks:
      - web
    expose:
      - "9091"

networks:
  web:
    external: true

Тег latest для быстрого старта допустим, но перед вводом в продакшен зафиксируйте конкретную версию с Docker Hub (authelia/authelia:4.x.x) — так апдейты не прилетят незаметно и не сломают формат конфига между мажорными релизами. Сеть web должна быть создана заранее (docker network create web) и общей с вашим reverse proxy — без этого прокси не достучится до Authelia по имени контейнера.

Шаг 3. Основной конфиг configuration.yml

Главный файл config/configuration.yml описывает, как Authelia аутентифицирует пользователей, где хранит сессии и какие правила доступа применяет. Для одиночного сервера без внешней LDAP-базы проще всего использовать файловый провайдер пользователей и SQLite для хранения:

theme: dark
default_redirection_url: https://auth.example.com

server:
  address: 'tcp://:9091'

authentication_backend:
  file:
    path: /config/users_database.yml

access_control:
  default_policy: deny
  rules:
    - domain: "*.example.com"
      policy: two_factor

session:
  name: authelia_session
  domain: example.com
  expiration: 1h
  inactivity: 5m
  cookies:
    - domain: example.com
      authelia_url: https://auth.example.com

storage:
  local:
    path: /config/db.sqlite3

notifier:
  filesystem:
    filename: /config/notification.txt

totp:
  issuer: example.com

Разберём главное. access_control.default_policy: deny — правильная политика «по умолчанию всё закрыто», а исключения (открытые пути) добавляются отдельными правилами при необходимости. session.domain должен быть родительским доменом для всех защищённых поддоменов — Authelia ставит cookie на этот домен, чтобы одна сессия работала сразу для всех сервисов под ним. Секция notifier.filesystem подходит только для теста: письма со ссылкой сброса пароля пишутся в файл внутри контейнера, а не уходят пользователю. Для рабочей установки замените её на smtp с вашим почтовым сервером, иначе восстановление пароля и первичная регистрация через ссылку из письма не будут работать.

Шаг 4. Пользователи и хэши паролей

Файловый провайдер хранит учётки в отдельном YAML-файле. Authelia требует хэшированные пароли — сгенерируйте их встроенной командой прямо из образа, не поднимая контейнер заранее:

docker run --rm authelia/authelia:latest authelia crypto hash generate argon2 --password 'ваш-пароль'

Команда вернёт строку вида $argon2id$v=19$... — её и вставляйте в файл, plain-текст пароль нигде храниться не должен. Создайте config/users_database.yml:

users:
  admin:
    displayname: "Admin"
    password: "$argon2id$v=19$m=65536,t=3,p=4$..."
    email: admin@example.com
    groups:
      - admins

Argon2id — рекомендуемый по умолчанию алгоритм хэширования в актуальных версиях Authelia, менять его на что-то более слабое ради скорости смысла нет: генерация хэша — разовая операция при создании пользователя, а не то, что влияет на скорость последующих логинов. Для нескольких пользователей просто повторите блок с новым именем ключа и своим хэшем. При росте числа учёток и необходимости синхронизировать их с внешним каталогом файловый провайдер можно заменить на LDAP-бэкенд — но для одиночного сервера с горсткой админов файл обычно достаточен и проще в сопровождении.

Шаг 5. Подключение к Nginx как forward-auth

Запустите Authelia и убедитесь, что она поднялась без ошибок:

docker compose up -d
docker compose logs -f authelia

Дальше нужно завести в Nginx перед защищённым сервисом два элемента: внутренний location, который проксирует проверку в Authelia, и обвязку auth_request на самом сервисе. Если Nginx у вас ещё не настроен как reverse proxy для приложений, сначала разверните его по статье про Nginx как reverse proxy на Ubuntu 24.04, а затем добавьте в конфиг сервиса блок ниже:

location /internal-auth {
    internal;
    proxy_pass http://authelia:9091/api/verify;
    proxy_set_header X-Original-URL $scheme://$http_host$request_uri;
    proxy_set_header Content-Length "";
    proxy_pass_request_body off;
}

location / {
    auth_request /internal-auth;
    error_page 401 = https://auth.example.com/?rd=$scheme://$http_host$request_uri;

    auth_request_set $user $upstream_http_remote_user;
    proxy_set_header Remote-User $user;

    proxy_pass http://app-backend;
}

Логика: любой запрос к / сначала уходит внутренним подзапросом на /internal-auth, тот пересылается в Authelia, и если сессия невалидна, Nginx перехватывает ответ 401 и редиректит пользователя на страницу входа с параметром rd — куда вернуться после успешной аутентификации. Заголовок Remote-User, который Authelia прокидывает обратно, можно передавать в приложение, если оно умеет доверять аутентификации от прокси. Для Traefik схема аналогична, но описывается middleware forwardAuth с адресом http://authelia:9091/api/verify в метках контейнера — если стек уже собран на Traefik, не придётся переписывать проксирование с нуля, только добавить middleware.

Шаг 6. Проверка входа и настройка TOTP

Откройте https://auth.example.com напрямую — должна открыться страница логина Authelia. Введите логин и пароль, заданные на шаге 4. При первом входе с политикой two_factor система предложит настроить второй фактор — покажет QR-код для приложения-аутентификатора (Google Authenticator, Aegis, любое TOTP-совместимое). Отсканируйте код, введите шестизначный код подтверждения — с этого момента вход требует пароль и код каждый раз, когда истекает сессия.

После настройки TOTP зайдите на один из защищённых поддоменов — вас должно перекинуть на страницу логина Authelia с параметром rd, а после успешного входа — вернуть обратно на исходный URL уже с рабочей сессией. Если редиректа не происходит и вместо этого сразу видна страница сервиса без запроса пароля — проверьте, что блок auth_request действительно попал в активный конфиг Nginx (nginx -t и systemctl reload nginx), а домен сервиса входит в правило access_control в configuration.yml. Если, наоборот, Authelia недоступна и Nginx отдаёт 502 на внутреннем location — проверьте, что оба контейнера в одной Docker-сети web и что имя authelia резолвится изнутри сети Nginx.

Отдельно стоит подумать о защите самой Authelia от перебора: она хранит счётчик неудачных попыток и умеет временно банить по IP через встроенный regulation-модуль (regulation.max_retries и regulation.find_time в конфиге), но для дополнительного слоя на уровне сети не лишним будет fail2ban перед портом 443 или ограничение доступа к auth.example.com по списку IP, если пользователей немного и они заходят с известных адресов.

Частые вопросы