RU

Приложения

Защита сервисов с помощью Authelia и Caddy

Разверните Authelia на Debian или Ubuntu с Docker и Caddy: портал аутентификации, двухфакторная аутентификация, раздельные секреты, правила доступа, обновления и резервное копирование.

8 мин чтения, обновлено 18 ноября 2026 г.

На этой странице

Ваши значения

Укажите их один раз, и команды в руководстве обновятся.

Это руководство объясняет, как поставить Authelia перед вашими веб-приложениями. Обратный прокси Caddy для каждого запроса спрашивает у Authelia, можно ли пропустить посетителя. Если посетитель не опознан, его отправляют на портал входа, который требует пароль и второй фактор.

К концу руководства https://app.ваш-домен.com будет доступен только после двухфакторной аутентификации на https://auth.ваш-домен.com. Секреты будут отделены от конфигурации, а вы научитесь обновлять установку и делать её резервные копии.

Заказать сервер

Это руководство подходит для серверов, которыми вы управляете самостоятельно:

Предварительные требования

  • Сервер под управлением Debian 12 или 13 либо Ubuntu 22.04 или 24.04
  • Доступ по SSH под пользователем с правами sudo
  • Docker Engine и Docker Compose, установленные по руководству Установка Docker Engine и Docker Compose
  • Caddy, установленный по руководству Caddy как обратный прокси с автоматическим HTTPS
  • Домен, DNS-зоной которого вы управляете, с записями auth.ваш-домен.com и app.ваш-домен.com, указывающими на IP_ВАШЕГО_СЕРВЕРА
  • Защищаемое приложение, которое слушает только локально, здесь на 127.0.0.1:3000
  • Учётная запись SMTP для отправки кодов подтверждения и сброса паролей

Используемые порты

Порт Направление Назначение Нужно ли открывать
80/tcp Входящий Проверка сертификата и перенаправление на HTTPS Да
443/tcp Входящий Портал Authelia и защищённые приложения Да
443/udp Входящий HTTP/3 Рекомендуется
9091/tcp Локальный Authelia, только на 127.0.0.1 Нет
3000/tcp Локальный Приложение из примера Нет

Authelia также доверяет заголовкам X-Forwarded-*, которые передаёт ей прокси. Поэтому её порт никогда не должен быть доступен из Интернета.

Шаг 1: создайте каталоги и секреты

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

Терминал
sudo mkdir -p /opt/authelia/config /opt/authelia/secrets
for name in JWT_SECRET SESSION_SECRET STORAGE_ENCRYPTION_KEY; do
  openssl rand -hex 64 | sudo tee "/opt/authelia/secrets/$name" > /dev/null
done
sudo nano /opt/authelia/secrets/SMTP_PASSWORD

В последнем файле укажите пароль вашей учётной записи SMTP, один в первой строке.

Шаг 2: создайте первого пользователя

Вычислите отпечаток вашего пароля. Команда запросит пароль дважды:

Терминал
sudo docker run --rm -it authelia/authelia:4.39.28 authelia crypto hash generate argon2

Она выведет строку, начинающуюся с Digest:. Создайте файл пользователей:

Терминал
sudo nano /opt/authelia/config/users.yml

Скопируйте только значение, начинающееся с $argon2id$, в апострофах:

YAML
users:
  ВАШ_ПОЛЬЗОВАТЕЛЬ:
    disabled: false
    displayname: 'Admin'
    password: '$argon2id$v=19$m=65536,t=3,p=4$...'
    email: 'admin@ваш-домен.com'
    groups:
      - 'admins'

На этот адрес электронной почты приходят коды подтверждения: он должен быть действующим.

Шаг 3: напишите конфигурацию

Терминал
sudo nano /opt/authelia/config/configuration.yml
YAML
server:
  address: 'tcp://:9091/'

log:
  level: 'info'

totp:
  issuer: 'auth.ваш-домен.com'

authentication_backend:
  file:
    path: '/config/users.yml'
    password:
      algorithm: 'argon2'

session:
  cookies:
    - domain: 'ваш-домен.com'
      authelia_url: 'https://auth.ваш-домен.com'
      default_redirection_url: 'https://app.ваш-домен.com'

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

regulation:
  modes:
    - 'user'
    - 'ip'
  max_retries: 3
  find_time: '2 minutes'
  ban_time: '10 minutes'

notifier:
  smtp:
    address: 'submission://smtp.ваш-домен.com:587'
    username: 'authelia@ваш-домен.com'
    sender: 'Authelia <authelia@ваш-домен.com>'

access_control:
  default_policy: 'deny'
  rules:
    - domain: 'app.ваш-домен.com'
      policy: 'two_factor'
Раздел Назначение
authentication_backend Учётные записи читаются из users.yml, пароли хранятся в Argon2id
session.cookies Защищаемый домен и адрес портала, обязательно по HTTPS
storage База SQLite, подходящая для одного экземпляра Authelia
regulation Временная блокировка после трёх неудачных попыток за две минуты
notifier Отправка писем. submission:// использует STARTTLS, submissions:// использует прямой TLS
access_control Всё запрещено, кроме того, что разрешает правило

Шаг 4: запустите Authelia

Терминал
sudo nano /opt/authelia/compose.yaml
YAML
services:
  authelia:
    image: authelia/authelia:4.39.28
    restart: unless-stopped
    user: "8091:8091"
    environment:
      TZ: "Europe/Paris"
      AUTHELIA_IDENTITY_VALIDATION_RESET_PASSWORD_JWT_SECRET_FILE: /secrets/JWT_SECRET
      AUTHELIA_SESSION_SECRET_FILE: /secrets/SESSION_SECRET
      AUTHELIA_STORAGE_ENCRYPTION_KEY_FILE: /secrets/STORAGE_ENCRYPTION_KEY
      AUTHELIA_NOTIFIER_SMTP_PASSWORD_FILE: /secrets/SMTP_PASSWORD
    volumes:
      - ./config:/config
      - ./secrets:/secrets:ro
    ports:
      - "127.0.0.1:9091:9091"

Контейнер работает от имени пользователя без привилегий. Дайте ему доступ к его файлам и больше никому:

Терминал
sudo chown -R 8091:8091 /opt/authelia/config /opt/authelia/secrets
sudo chmod 700 /opt/authelia/config /opt/authelia/secrets
sudo find /opt/authelia/config /opt/authelia/secrets -type f -exec chmod 600 {} +

Проверьте конфигурацию, затем запустите службу:

Терминал
cd /opt/authelia
sudo docker compose run --rm authelia authelia config validate --config /config/configuration.yml
sudo docker compose up -d
sudo docker compose logs --tail=30 authelia
curl -fsS http://127.0.0.1:9091/api/health

Проверка должна вывести Configuration parsed and loaded successfully without errors. В журналах должна быть строка Listening for non-TLS connections, а последняя команда должна вернуть {"status":"OK"}.

Трафик между Caddy и Authelia остаётся на локальной петле сервера. Посетители же попадают на портал только по HTTPS.

Шаг 5: настройте Caddy

Если вы используете UFW, разрешите веб-порты:

Терминал
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw allow 443/udp

Добавьте эти два сайта в /etc/caddy/Caddyfile или в файл из /etc/caddy/sites/:

caddyfile
auth.ваш-домен.com {
	reverse_proxy 127.0.0.1:9091
}

app.ваш-домен.com {
	forward_auth 127.0.0.1:9091 {
		uri /api/authz/forward-auth
		copy_headers Remote-User Remote-Groups Remote-Email Remote-Name
	}

	reverse_proxy 127.0.0.1:3000
}

forward_auth обращается к Authelia перед каждым запросом. Если доступ разрешён, Caddy копирует личность пользователя в заголовки Remote-* и передаёт запрос приложению. В противном случае он возвращает ответ Authelia, как правило перенаправление на портал.

Проверьте и примените конфигурацию:

Терминал
sudo caddy fmt --overwrite /etc/caddy/Caddyfile
sudo -u caddy caddy validate --config /etc/caddy/Caddyfile --adapter caddyfile
sudo systemctl reload caddy

Шаг 6: зарегистрируйте второй фактор

  1. Откройте https://app.ваш-домен.com в окне приватного просмотра. Вы попадёте на портал.
  2. Войдите под именем ВАШ_ПОЛЬЗОВАТЕЛЬ с паролем, выбранным на шаге 2.
  3. Нажмите Регистрация устройства.
  4. Введите одноразовый код, полученный по электронной почте, чтобы подтвердить свою личность.
  5. Добавьте Одноразовый пароль в своём приложении TOTP или Ключ безопасности WebAuthn.
  6. Подтвердите второй фактор: вы будете перенаправлены в приложение.

Другие устройства можно будет добавить в Настройки портала. По возможности зарегистрируйте не менее двух методов, чтобы не зависеть от одного устройства.

Проверка результата

Терминал
curl -si https://app.ваш-домен.com | grep -iE '^(HTTP|location)'
sudo ss -ltnp | grep -E ':(3000|9091) '

Первая команда должна вернуть код 302 и адрес https://auth.ваш-домен.com/ с параметром rd. Вторая должна показать только 127.0.0.1.

С вашего компьютера http://IP_ВАШЕГО_СЕРВЕРА:3000 и http://IP_ВАШЕГО_СЕРВЕРА:9091 не должны отвечать. Наконец, выполните эти проверки в приватном окне:

  • один лишь пароль не даёт доступа к приложению;
  • неверный код TOTP отклоняется;
  • после выхода с портала приложение снова запрашивает аутентификацию.

Повторяйте эти проверки после каждого изменения прокси или правил доступа.

Добавление сервисов и уточнение правил

Чтобы защитить другой сервис, добавьте сайт Caddy с тем же блоком forward_auth, затем правило Authelia. Правила читаются по порядку, и применяется первое подходящее.

YAML
access_control:
  default_policy: 'deny'
  rules:
    - domain: 'status.ваш-домен.com'
      resources:
        - '^/api/health$'
      policy: 'bypass'
    - domain: 'admin.ваш-домен.com'
      subject:
        - 'group:admins'
      policy: 'two_factor'
    - domain: 'app.ваш-домен.com'
      policy: 'two_factor'
Политика Действие
deny Доступ запрещён
bypass Без аутентификации: используйте только для действительно публичных путей
one_factor Запрашивается пароль
two_factor Запрашиваются пароль и второй фактор

Все сервисы должны находиться в домене, объявленном в session.cookies. Чтобы добавить пользователя, дополните users.yml. После любого изменения конфигурации или пользователей перезапускайте Authelia:

Терминал
cd /opt/authelia
sudo docker compose restart authelia

Сессии хранятся в памяти: этот перезапуск завершает сессии всех пользователей.

Обновление Authelia

Прочитайте примечания к выпуску, сделайте резервную копию, затем замените номер версии в compose.yaml:

Терминал
cd /opt/authelia
sudo nano compose.yaml
sudo docker compose pull
sudo docker compose run --rm authelia authelia config validate --config /config/configuration.yml
sudo docker compose up -d
sudo docker compose logs --tail=30 authelia

При запуске Authelia автоматически переносит свою базу на схему новой версии. Поэтому предварительная резервная копия — ваш путь отката. Затем повторите проверки из раздела проверки результата.

Резервное копирование и восстановление

Каталог /opt/authelia содержит всё состояние установки: конфигурацию, пользователей, базу SQLite и секреты. Ненадолго остановите службу, чтобы получить согласованную копию:

Терминал
cd /opt/authelia
sudo docker compose stop authelia
sudo tar -czpf "/root/authelia-$(date +%F).tar.gz" -C /opt authelia
sudo docker compose start authelia
sudo chmod 600 "/root/authelia-$(date +%F).tar.gz"

Этот архив содержит ваши секреты и отпечатки паролей. Скопируйте его за пределы сервера в зашифрованное хранилище.

Чтобы проверить, что архив пригоден, не затрагивая работающий экземпляр, замените имя архива, затем проверьте ключ шифрования на копии:

Терминал
sudo install -d -m 700 /root/authelia-test
sudo tar -xzpf /root/authelia-2026-11-18.tar.gz -C /root/authelia-test
cd /root/authelia-test/authelia
sudo docker compose -p authelia-test run --rm authelia authelia storage encryption check --verbose --config /config/configuration.yml
sudo docker compose -p authelia-test down
cd /
sudo rm -rf /root/authelia-test

Ожидаемый результат — Storage Encryption Key Validation: SUCCESS.

Чтобы восстановить архив на сервере, где уже установлены Docker и Caddy:

Терминал
cd /opt/authelia
sudo docker compose down
cd /
sudo mv /opt/authelia "/opt/authelia.old-$(date +%F)"
sudo tar -xzpf /root/authelia-2026-11-18.tar.gz -C /opt
cd /opt/authelia
sudo docker compose up -d

Если что-то пошло не так

Всегда начинайте с журналов:

Терминал
cd /opt/authelia
sudo docker compose logs --tail=100 authelia

secrets: error loading secret path /secrets/...

Указанный файл отсутствует или недоступен для чтения. Проверьте его имя, затем повторите команды chown и chmod из шага 4.

notifier: please ensure only one of the 'smtp' or 'filesystem' notifier is configured

Вы используете filesystem, но AUTHELIA_NOTIFIER_SMTP_PASSWORD_FILE всё ещё присутствует в compose.yaml. Удалите эту строку, затем снова выполните sudo docker compose up -d.

One or more providers had fatal failures performing startup checks

Необходимый сервис не запустился. Чаще всего Authelia не может подключиться к SMTP-серверу или использовать его. Причину указывают предыдущие строки с ошибками: адрес, порт, учётные данные или заблокированный исходящий порт.

the configured encryption key does not appear to be valid for this database

STORAGE_ENCRYPTION_KEY не совпадает с ключом, которым была создана база. Верните правильный ключ из резервной копии. Чтобы сменить его намеренно, используйте команду authelia storage encryption change-key.

the system clock is not synchronized accurately enough with the configured NTP server

Часы сервера отстают или спешат, из-за чего коды TOTP были бы недействительны. Проверьте синхронизацию:

Терминал
timedatectl status

Target URL does not appear to have a relevant session cookies configuration

Домен приложения не охвачен session.cookies. Проверьте domain в configuration.yml и имя, используемое в Caddyfile.

Target URL ... has an insecure scheme

Запрос приходит по HTTP. Все защищаемые приложения должны работать по HTTPS. Убедитесь, что сайт Caddy указан под публичным доменным именем, без префикса http://.

Access to '...' is forbidden to user '...'

Пользователь вошёл, но ни одно правило не разрешает ему доступ. Проверьте порядок правил, домен и группы в users.yml.

Пароль отклоняется, хотя он верный

После нескольких неудачных попыток учётная запись или IP-адрес блокируется на время ban_time. Дождитесь окончания срока или снимите блокировку с учётной записи:

Терминал
cd /opt/authelia
sudo docker compose exec authelia authelia storage bans user revoke ВАШ_ПОЛЬЗОВАТЕЛЬ --config /config/configuration.yml

Для IP-адреса используйте authelia storage bans ip revoke ВАШ_IP.

Ошибка 502 в браузере

Caddy не может подключиться к Authelia или к приложению. Проверьте оба локально:

Терминал
curl -fsS http://127.0.0.1:9091/api/health
curl -I http://127.0.0.1:3000

Ссылки