Защита сервисов с помощью Authelia и Caddy
Разверните Authelia на Debian или Ubuntu с Docker и Caddy: портал аутентификации, двухфакторная аутентификация, раздельные секреты, правила доступа, обновления и резервное копирование.
На этой странице
Ваши значения
Укажите их один раз, и команды в руководстве обновятся.
Это руководство объясняет, как поставить 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$, в апострофах:
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.ymlserver:
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.yamlservices:
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/:
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: зарегистрируйте второй фактор
- Откройте
https://app.ваш-домен.comв окне приватного просмотра. Вы попадёте на портал. - Войдите под именем
ВАШ_ПОЛЬЗОВАТЕЛЬс паролем, выбранным на шаге 2. - Нажмите Регистрация устройства.
- Введите одноразовый код, полученный по электронной почте, чтобы подтвердить свою личность.
- Добавьте Одноразовый пароль в своём приложении TOTP или Ключ безопасности WebAuthn.
- Подтвердите второй фактор: вы будете перенаправлены в приложение.
Другие устройства можно будет добавить в Настройки портала. По возможности зарегистрируйте не менее двух методов, чтобы не зависеть от одного устройства.
Проверка результата
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. Правила читаются по порядку, и применяется первое подходящее.
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 autheliasecrets: 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 statusTarget 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