Налаштування Authelia на VPS для

Конфігурація

Тепер, коли основні компоненти встановлено, настав час налаштувати Authelia та Caddy.

1. Конфігурація Authelia (configuration.yml)

Створіть файл configuration.yml у директорії ~/authelia/config/. Цей файл містить усі налаштування Authelia.

nano ~/authelia/config/configuration.yml

Вставте наступний приклад конфігурації. Зверніть увагу, що ми використовуємо SQLite для бази даних та локальний файл для користувачів, що спрощує початкове налаштування. Замініть your_domain.com на ваш реальний домен.

# configuration.yml
# Актуальна структура для Authelia v4.x на 2026 рік

server:
  host: 0.0.0.0
  port: 9091
  tls:
    enabled: false # Caddy оброблятиме TLS

log:
  level: debug # Змініть на 'info' або 'warn' для продакшену
  format: json

authentication_backend:
  file:
    path: /config/users_database.yml # Шлях до файлу з користувачами

session:
  domain: your_domain.com # Замініть на ваш домен
  secret: "$AUTHELIA_SESSION_SECRET" # Береться зі змінної оточення
  name: authelia_session
  expiration: 1h
  inactivity: 5m
  remember_me_duration: 1d

TOTP:
  issuer: authelia.your_domain.com # Замініть на ваш домен

access_control:
  default_policy: deny # За замовчуванням забороняємо все
  rules:
    - domain: "authelia.your_domain.com" # Доступ до самої Authelia
      policy: bypass # Не потребує автентифікації для сторінки входу
    - domain: "auth.your_domain.com" # Домен, через який буде доступна Authelia
      policy: bypass # Не потребує автентифікації для сторінки входу
    - domain: ".your_domain.com" # Захищаємо всі піддомени
      policy: two_factor # Вимагаємо двофакторну автентифікацію
      # users: ["john", "jane"] # Можна обмежити доступ конкретним користувачам

identity_providers:
  oidc:
    enabled: false # OIDC можна увімкнути пізніше для інтеграції з іншими IdP

notifier:
  smtp:
    host: "smtp.mail.com" # Замініть на ваш SMTP-сервер
    port: 587
    username: "authelia@your_domain.com" # Замініть на вашу адресу
    password: "your_smtp_password" # Пароль для SMTP
    sender: "Authelia " # Відправник
    disable_starttls: false
    disable_require_tls: false

storage:
  sqlite:
    path: /config/db.sqlite3 # Шлях до файлу бази даних SQLite

jwt_secret: "$AUTHELIA_JWT_SECRET" # Береться зі змінної оточення

duo_api:
  secret: "$AUTHELIA_DUO_API_SECRET" # Якщо використовуєте Duo Security

nano ~/authelia/config/users_database.yml

# Запустіть Authelia, якщо вона не запущена, або оновіть:
docker compose pull authelia
docker compose up -d authelia

# Потім виконайте команду для генерації хешу пароля
docker compose exec authelia authelia hash-password your_strong_password
# Приклад виводу: $argon2id$v=19$m=65536,t=3,p=4$some_salt$some_hash

# users_database.yml
users:
  john:
    display_name: John Doe
    password: "your_hashed_password_for_john" # Вставте хеш, отриманий вище
    email: john.doe@your_domain.com
    groups:
      - admins
      - developers
  jane:
    display_name: Jane Smith
    password: "your_hashed_password_for_jane" # Вставте хеш
    email: jane.smith@your_domain.com
    groups:
      - users

nano ~/authelia/Caddyfile

# Caddyfile
# Актуальна структура для Caddy v2.x на 2026 рік

# Домен для Authelia
auth.your_domain.com {
  # Автоматичний HTTPS
  tls internal # Використовуйте 'tls your_email@your_domain.com' для Let's Encrypt

  # Перенаправлення на Authelia
  reverse_proxy authelia:9091 {
    # Заголовки, необхідні для Authelia
    header_up X-Original-URL {uri}
    header_up X-Forwarded-Proto {scheme}
    header_up X-Forwarded-Host {host}
    header_up X-Forwarded-For {remote_host}
  }

  # Додаткові заголовки безпеки
  header {
    Strict-Transport-Security "max-age=31536000; includeSubDomains; preload"
    X-Content-Type-Options "nosniff"
    X-Frame-Options "SAMEORIGIN"
    X-XSS-Protection "1; mode=block"
    Referrer-Policy "same-origin"
  }
}

# Приклад програми, що захищається (наприклад, GitLab, Mattermost, Grafana)
app.your_domain.com {
  # Автоматичний HTTPS
  tls internal # Використовуйте 'tls your_email@your_domain.com' для Let's Encrypt

  # Перевірка автентифікації через Authelia
  handle_errors {
    @authelia {
      expression {http.response.status} in [401, 403]
    }
    rewrite @authelia /authelia
    reverse_proxy @authelia authelia:9091 {
      # Заголовки для Authelia
      header_up Remote-User {env.Remote-User}
      header_up Remote-Groups {env.Remote-Groups}
      header_up Remote-Name {env.Remote-Name}
      header_up Remote-Email {env.Remote-Email}
    }

    # Якщо автентифікація успішна, проксіюємо до програми
    reverse_proxy localhost:8080 # Замініть на адресу вашої програми (наприклад, localhost:3000 для Grafana)
  }

  # Якщо програма не вимагає автентифікації, але ви хочете її додати
  # handle {
  #   # Перевірка автентифікації через Authelia
  #   reverse_proxy authelia:9091 {
  #     # Заголовки для Authelia
  #     header_up Remote-User {env.Remote-User}
  #     header_up Remote-Groups {env.Remote-Groups}
  #     header_up Remote-Name {env.Remote-Name}
  #     header_up Remote-Email {env.Remote-Email}
  #   }
  #
  #   # Якщо автентифікація успішна, проксіюємо до програми
  #   reverse_proxy localhost:8080 # Замініть на адресу вашої програми
  # }

  # Додаткові заголовки безпеки
  header {
    Strict-Transport-Security "max-age=31536000; includeSubDomains; preload"
    X-Content-Type-Options "nosniff"
    X-Frame-Options "SAMEORIGIN"
    X-XSS-Protection "1; mode=block"
    Referrer-Policy "same-origin"
  }
}

cd ~/authelia                   # Переконайтеся, що ви в директорії з docker-compose.yml
docker compose down             # Зупиняємо та видаляємо старі контейнери
docker compose up -d            # Запускаємо нові контейнери з оновленою конфігурацією
docker compose logs -f authelia # Перевіряємо логи Authelia на наявність помилок
docker compose logs -f caddy    # Перевіряємо логи Caddy

Резервне копіювання та обслуговування

Налаштування Authelia — це лише початок. Вкрай важливо забезпечити регулярне резервне копіювання та своєчасне обслуговування, щоб гарантувати надійність і безпеку вашої системи.

1. Що резервувати

Для Authelia та пов'язаних з нею компонентів необхідно резервувати такі дані:

• Конфігураційні файли Authelia: ~/authelia/config/configuration.yml
• База даних користувачів Authelia: ~/authelia/config/users_database.yml (якщо використовуєте файловий бекенд) або дані БД (наприклад, ~/authelia/config/db.sqlite3 для SQLite). Якщо ви використовуєте зовнішню базу даних (PostgreSQL, MySQL), то необхідно налаштувати резервне копіювання цієї бази даних.
• Конфігурація Caddy: ~/authelia/Caddyfile
• Дані Caddy: ~/authelia/caddy_data (містить сертифікати Let's Encrypt та інші дані Caddy).

По суті, вам потрібно резервувати всю директорію ~/authelia/.

2. Простий скрипт авторезервування

Ми створимо простий скрипт, який архівуватиме потрібні директорії та зберігатиме їх з тимчасовою позначкою. Для зберігання резервних копій рекомендується використовувати зовнішнє сховище, а не той самий VPS.

nano ~/authelia/backup_authelia.sh

Вставте наступний вміст:

#!/bin/bash

# Путь к директории Authelia
AUTHELIA_DIR="/home/authelia_admin/authelia" # Замените на ваш путь

# Директория для временного хранения бэкапов на VPS
BACKUP_TEMP_DIR="/tmp/authelia_backups"

# Директория для хранения бэкапов на внешнем хранилище (пример для S3-совместимого)
# S3_BUCKET="s3://your-s3-bucket/authelia-backups/"
# AWS_CLI_PROFILE="your-aws-profile" # Если используете AWS CLI с профилем

# Создаем временную директорию, если ее нет
mkdir -p "$BACKUP_TEMP_DIR"

# Формируем имя файла бэкапа с временной меткой
TIMESTAMP=$(date +%Y%m%d%H%M%S)
BACKUP_FILE="authelia_backup_${TIMESTAMP}.tar.gz"
FULL_BACKUP_PATH="${BACKUP_TEMP_DIR}/${BACKUP_FILE}"

echo "Starting Authelia backup at ${TIMESTAMP}..."

# Создаем архив
tar -czvf "$FULL_BACKUP_PATH" -C "$(dirname "$AUTHELIA_DIR")" "$(basename "$AUTHELIA_DIR")"

if [ $? -eq 0 ]; then
    echo "Backup created successfully: $FULL_BACKUP_PATH"

    # Пример загрузки на S3-совместимое хранилище (требует установленного awscli)
    # sudo apt install awscli -y
    # aws s3 cp "$FULL_BACKUP_PATH" "$S3_BUCKET" --profile "$AWS_CLI_PROFILE"

    # Пример копирования на другой сервер по SCP (требует настроенного SSH-ключа)
    # scp "$FULL_BACKUP_PATH" user@remote_server:/path/to/remote/backups/

    # Пример удаления старых бэкапов (оставляем последние 7 дней)
    find "$BACKUP_TEMP_DIR" -name "authelia_backup_.tar.gz" -type f -mtime +7 -delete
    echo "Old backups cleaned from $BACKUP_TEMP_DIR"

else
    echo "Error creating backup."
    exit 1
fi

echo "Authelia backup script finished."

Зробіть скрипт виконуваним:

chmod +x ~/authelia/backup_authelia.sh

3. Налаштування Cron для автоматичного запуску резервного копіювання

Додайте завдання до Cron, щоб скрипт резервного копіювання запускався автоматично, наприклад, щодня о 3 годині ночі.

crontab -e

Додайте наступний рядок у кінець файлу (якщо використовуєте authelia_admin):

0 3   * /home/authelia_admin/authelia/backup_authelia.sh >> /var/log/authelia_backup.log 2>&1

Цей рядок запускає скрипт щодня о 03:00 і перенаправляє вивід у лог-файл /var/log/authelia_backup.log.

4. Куди зберігати резервні копії

Ніколи не зберігайте резервні копії на тому ж сервері, де знаходяться вихідні дані. Це зводить нанівець сенс резервного копіювання у разі виходу з ладу диска або компрометації сервера. Рекомендовані варіанти:

• Зовнішнє S3-сумісне сховище: Дешево, надійно, масштабовано (наприклад, MinIO, Wasabi, Backblaze B2). Для роботи зі скриптом знадобиться awscli.
• Окремий VPS: Ви можете орендувати невеликий VPS спеціально для зберігання резервних копій та копіювати туди архіви за допомогою SCP/SFTP.
• NAS/локальне сховище: Якщо у вас є власне мережеве сховище, можна налаштувати копіювання туди.

5. Оновлення: rolling vs maintenance window

Регулярні оновлення вкрай важливі для безпеки та стабільності Authelia і Docker.

• Оновлення ОС: Регулярно запускайте sudo apt update && sudo apt upgrade -y. Можна налаштувати автоматичні оновлення (unattended-upgrades) для патчів безпеки.
• Оновлення Docker: Оновлюйте Docker Engine та Docker Compose, дотримуючись офіційної документації. Зазвичай це робиться через apt upgrade, оскільки ми додали репозиторій Docker.
• Оновлення Authelia та Caddy: Оскільки вони працюють у Docker-контейнерах, оновлення зводиться до оновлення образів та перезапуску сервісів.

cd ~/authelia
docker compose pull authelia caddy # Скачивает последние версии образов
docker compose up -d               # Пересоздает контейнеры с новыми образами

• Стратегія оновлень:
  • Rolling updates (безперервні): Для некритичних змін або якщо у вас кластер. У контексті одного VPS це означає оновлення без тривалого простою. Для Authelia це може бути невелике вікно простою (кілька секунд/хвилин).
  • Maintenance window (вікно обслуговування): Для великих оновлень, міграцій або за наявності критично важливих сервісів. Заплануйте час, попередьте користувачів та проведіть оновлення, маючи можливість відкату.

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

Troubleshooting + FAQ

У процесі налаштування та експлуатації Authelia можуть виникати різні проблеми. Тут зібрані типові питання та способи їх вирішення.

1. Який VPS-конфіг мінімально підійде для Authelia та захищених застосунків?

Мінімально достатній конфіг для Authelia, Caddy та одного-двох легковажних застосунків (наприклад, Grafana, невелика wiki) включатиме 1 vCPU, 1 GB RAM та 25 GB SSD. Цього вистачить для експериментів та невисокого навантаження. Однак, для більш комфортної роботи та можливості розширення рекомендується 2 vCPU, 2-4 GB RAM та 50 GB SSD, особливо якщо ви плануєте захищати більш ресурсоємні сервіси або мати кілька активних користувачів. Переконайтеся, що у вас є достатньо дискового простору для Docker-образів, логів та даних усіх ваших застосунків.

2. Що вибрати — VPS чи dedicated для цього завдання?

Для більшості сценаріїв використання Authelia (особисті проєкти, команди до 50-100 осіб, захист кількох внутрішніх сервісів) VPS є оптимальним вибором. Він значно дешевший, простіший в управлінні та надає достатню продуктивність. Dedicated сервер варто розглядати лише у випадках дуже високого навантаження (тисячі активних користувачів), суворих вимог до ізоляції ресурсів, необхідності запуску вкрай ресурсоємних застосунків на тому ж хості, або якщо ви хочете мати повний контроль над апаратним забезпеченням та його конфігурацією. Для початку завжди краще вибрати VPS, а за необхідності масштабуватися до dedicated.

3. Чому Authelia не запускається або контейнер постійно перезапускається?

Що перевірити:

• Логи контейнера Authelia: docker compose logs authelia. Це перше місце, куди потрібно дивитися.
• Файл configuration.yml: Найчастіше проблеми виникають через синтаксичні помилки (відступи, одруківки) у YAML-файлі або невірні шляхи до файлів.
• Змінні оточення: Переконайтеся, що AUTHELIA_JWT_SECRET та AUTHELIA_SESSION_SECRET встановлені в docker-compose.yml і не порожні.
• Права доступу: Переконайтеся, що Docker-контейнер має права на читання файлів у /config та запис у /config/db.sqlite3.

Як виправити: Виправте помилки в configuration.yml. Використовуйте онлайн-валідатори YAML. Переконайтеся, що всі секрети згенеровані та вставлені коректно. Перезапустіть контейнери після виправлень: docker compose down && docker compose up -d.

4. Не можу отримати доступ до Authelia за доменом (Caddy не працює)?

Що перевірити:

• DNS-записи: Переконайтеся, що домен (наприклад, auth.your_domain.com) вказує на IP вашого VPS. Перевірте за допомогою dig auth.your_domain.com.
• Порти Firewall: Переконайтеся, що порти 80 та 443 відкриті на вашому VPS (sudo ufw status).
• Логи Caddy: docker compose logs caddy. Шукайте помилки, пов'язані з TLS або проксіюванням.
• Caddyfile: Перевірте синтаксис та правильність вказівки доменів та адрес проксіювання (authelia:9091).
• Сертифікати TLS: Якщо використовуєте Let's Encrypt (tls your_email@your_domain.com), переконайтеся, що домен доступний з інтернету за HTTP, інакше Caddy не зможе отримати сертифікат.

Як виправити: Виправте DNS, відкрийте порти, перевірте Caddyfile. Якщо проблема з Let's Encrypt, тимчасово використовуйте tls internal для перевірки, а потім поверніться до Let's Encrypt після усунення проблем з доступністю домену.

5. Після входу в Authelia мене не перенаправляє в застосунок, або застосунок не бачить користувача?

Що перевірити:

• Caddyfile для застосунку: Переконайтеся, що блок для вашого застосунку (наприклад, app.your_domain.com) правильно налаштований для проксіювання через Authelia та передає необхідні заголовки (Remote-User, Remote-Email тощо).
• Адреса захищеного застосунку: Переконайтеся, що reverse_proxy localhost:PORT або service_name:PORT вказує на правильну адресу та порт вашого застосунку.
• Конфігурація Authelia (access_control): Переконайтеся, що правила доступу в configuration.yml коректно налаштовані для домену вашого застосунку.
• Логи застосунку: Перевірте логи вашого захищеного застосунку. Можливо, він не налаштований на читання заголовків, що передаються Authelia, або очікує інший формат.

Як виправити: Перевірте Caddyfile та configuration.yml. Переконайтеся, що ваш застосунок підтримує автентифікацію через заголовки HTTP (Header-based authentication) або OpenID Connect (OIDC), якщо ви налаштували Authelia для OIDC. Багато застосунків мають опції для інтеграції з проксі-автентифікацією (наприклад, Nginx/Caddy auth_request).

6. Не працює 2FA (TOTP) або скидання пароля?

Що перевірити:

• Налаштування SMTP: У configuration.yml перевірте секцію notifier.smtp. Переконайтеся, що хост, порт, ім'я користувача, пароль та відправник вказані вірно. Перевірте логи Authelia на помилки відправлення пошти.
• TOTP Issuer: Переконайтеся, що TOTP.issuer у configuration.yml коректний, це впливає на відображення в автентифікаторі.
• Синхронізація часу: Переконайтеся, що час на вашому VPS синхронізовано (timedatectl). Розбіжності можуть викликати проблеми з TOTP.

Як виправити: Виправте налаштування SMTP. Встановіть ntp або systemd-timesyncd для синхронізації часу на VPS. Якщо проблема з TOTP, спробуйте переналаштувати його в Authelia.