## Описание

Authelia Authentication - централизованная система аутентификации и авторизации для всех сервисов экосистемы aepif.ru. Обеспечивает Single Sign-On (SSO), двухфакторную аутентификацию и гранулярное управление доступом.

## Архитектура системы

```mermaid
graph TB
    A[User Request] --> B[Traefik Reverse Proxy]
    B --> C{Authelia Middleware}
    C -->|Authenticated| D[Target Service]
    C -->|Not Authenticated| E[Authelia Login Page]
    
    E --> F[User Authentication]
    F --> G[Session Storage - Redis]
    F --> H[User Database - File]
    
    G --> I[Session Validation]
    I --> D
    
    subgraph "Authelia Container"
        E
        F
        I
        J[TOTP 2FA]
        K[Password Reset]
    end
    
    subgraph "Redis Container"
        G
        L[Session Data]
    end
    
    subgraph "Configuration"
        H
        M[Access Control Rules]
        N[Notification Settings]
    end
```

## Основные компоненты

### Authelia Server
- **Назначение**: Центральный сервер аутентификации
- **Домен**: `auth.aepif.ru`
- **Порт**: 9091
- **Технология**: Go-based authentication server
- **Особенности**:
  - Forward Authentication integration с Traefik
  - TOTP двухфакторная аутентификация
  - Password reset через файловые уведомления
  - Детальные политики доступа

### Redis Session Store
- **Назначение**: Хранение пользовательских сессий
- **Технология**: Redis 7 Alpine
- **Контейнер**: `auth_redis`
- **Особенности**:
  - Персистентное хранение сессий
  - Защита паролем (`Ll8qlQ3rgBFo4Syq`)
  - Быстрый доступ к данным сессий
  - Автоматическое истечение сессий

### File-based User Database
- **Назначение**: Хранение пользователей и их данных
- **Файл**: `/config/users_database.yml`
- **Особенности**:
  - Argon2id хеширование паролей
  - Группы пользователей для управления доступом
  - Email адреса для уведомлений

## Конфигурация

### Docker Compose
Основная конфигурация в `/DOCKER/auth/docker-compose.yml`:

```yaml
services:
  redis:
    image: redis:7-alpine
    container_name: auth_redis
    command: redis-server --requirepass Ll8qlQ3rgBFo4Syq
    
  authelia:
    image: authelia/authelia:latest
    container_name: authelia
    depends_on:
      - redis
    volumes:
      - ./authelia:/config
    networks:
      - proxy  # Подключение к Traefik
```

### Основная конфигурация
Файл `/DOCKER/auth/authelia/configuration.yml`:

```yaml
jwt_secret: 4odTQ0TqW2Ej8m8Cm3K6Wn3VTvg09Mb2Yi4CUzuIPUsHB3fpF54+NbIAqo6+CREA
default_redirection_url: https://notes.aepif.ru

server:
  host: 0.0.0.0
  port: 9091

totp:
  issuer: aepif.ru

session:
  domain: aepif.ru
  expiration: 1h
  inactivity: 5m
  redis:
    host: redis
    port: 6379
    password: Ll8qlQ3rgBFo4Syq
```

## Политики доступа

### Access Control Rules
Текущие правила доступа:

```yaml
access_control:
  default_policy: deny  # По умолчанию запрещен доступ
  rules:
    - domain: notes.aepif.ru
      policy: one_factor    # Требует логин/пароль
    - domain: git.aepif.ru
      policy: bypass        # Собственная авторизация Gitea
    - domain: webhook.aepif.ru
      policy: bypass        # API с токеном
    - domain: auth.aepif.ru
      policy: bypass        # Сама страница входа
```

### Типы политик
- **bypass**: Доступ без аутентификации через Authelia
- **one_factor**: Требует только логин/пароль
- **two_factor**: Требует логин/пароль + TOTP код
- **deny**: Полный запрет доступа

## Пользователи и группы

### Структура пользователей
Файл `users_database.yml`:

```yaml
users:
  admin:
    displayname: "Administrator"
    password: "$argon2id$..." # Хешированный пароль Argon2id
    email: epifantsev1aa@gmail.com
    groups:
      - admins    # Администраторская группа
      - users     # Базовая группа пользователей
```

### Управление паролями
- **Хеширование**: Argon2id (высокий уровень безопасности)
- **Reset процедура**: Через файловые уведомления
- **Требования**: Минимальная длина, сложность

## Двухфакторная аутентификация

### TOTP Configuration
- **Issuer**: `aepif.ru`
- **QR Code**: Автоматическая генерация для настройки
- **Backup Codes**: Коды восстановления доступа
- **Приложения**: Google Authenticator, Authy, 1Password

### Настройка TOTP
1. Первый вход с логином/паролем
2. Сканирование QR кода мобильным приложением
3. Подтверждение TOTP кода
4. Сохранение backup кодов

## Интеграция с Traefik

### Forward Auth Middleware
Traefik labels для защищенных сервисов:

```yaml
labels:
  - traefik.http.middlewares.authelia.forwardauth.address=http://authelia:9091/api/verify?rd=https://auth.aepif.ru
  - traefik.http.middlewares.authelia.forwardauth.trustForwardHeader=true
  - traefik.http.middlewares.authelia.forwardauth.authResponseHeaders=Remote-User,Remote-Groups,Remote-Name,Remote-Email
```

### Headers передача
Authelia передает в backend сервисы:
- **Remote-User**: Username аутентифицированного пользователя
- **Remote-Groups**: Группы пользователя
- **Remote-Name**: Display name
- **Remote-Email**: Email адрес

## Сессии и безопасность

### Session Management
- **Время жизни**: 1 час активной сессии
- **Неактивность**: 5 минут до автоматического выхода
- **Хранение**: Redis с паролем
- **Domain**: `.aepif.ru` (работает для всех поддоменов)

### Regulation (Rate Limiting)
Защита от брутфорса:

```yaml
regulation:
  max_retries: 3      # Максимум попыток входа
  find_time: 2m       # Период для подсчета попыток  
  ban_time: 5m        # Время блокировки
```

### Безопасность
- **JWT Secret**: Секретный ключ для подписи токенов
- **Session Secret**: Ключ для шифрования сессий
- **Encryption Key**: Ключ для шифрования хранилища
- **Secure Headers**: Автоматические заголовки безопасности

## Уведомления

### File Notifier
- **Файл**: `/config/notification.txt`
- **Назначение**: Password reset уведомления
- **Формат**: Простой текстовый файл

### Email Integration (Future)
Для полноценных email уведомлений потребуется настройка SMTP:
- Password reset emails
- 2FA setup notifications
- Security alerts

## Мониторинг

### Health Checks
```bash
# Проверка доступности Authelia
curl -I https://auth.aepif.ru

# Проверка API здоровья
curl https://auth.aepif.ru/api/health

# Логи Authelia
docker logs authelia -f

# Проверка Redis
docker exec auth_redis redis-cli -a Ll8qlQ3rgBFo4Syq ping
```

### Metrics
- **Authentication attempts**: Успешные/неуспешные попытки входа
- **Session statistics**: Активные сессии, время жизни
- **2FA usage**: Статистика использования TOTP
- **Access denials**: Заблокированные запросы

## Структура файлов

```
/DOCKER/auth/
├── docker-compose.yml    # Конфигурация Authelia + Redis
├── authelia/            # Конфигурация Authelia
│   ├── configuration.yml # Основная конфигурация
│   ├── users_database.yml # База пользователей  
│   ├── db.sqlite3        # SQLite база данных (для хранения состояния)
│   └── notification.txt  # Файл уведомлений
└── volumes/
    └── redis_data/      # Данные Redis
```

## Troubleshooting

### Общие проблемы
1. **Не работает аутентификация**: Проверить сеть `proxy`, статус контейнеров
2. **Сессии не сохраняются**: Проверить подключение к Redis
3. **TOTP не работает**: Синхронизировать время на сервере и устройстве
4. **Password reset**: Проверить файл уведомлений

### Логи отладки
```yaml
# В configuration.yml для детальных логов
log:
  level: debug
```

## Backup и восстановление

### Критически важные данные
- **configuration.yml**: Основная конфигурация
- **users_database.yml**: База пользователей
- **db.sqlite3**: Состояние системы (2FA secrets, etc.)
- **redis_data**: Активные сессии

### Процедура backup
```bash
# Backup конфигурации Authelia
tar czf authelia_config_backup.tar.gz -C /DOCKER/auth/authelia .

# Backup Redis данных
docker exec auth_redis redis-cli -a Ll8qlQ3rgBFo4Syq BGSAVE
```

## Связанные сервисы

- **[[Мой сервер/Traefik Reverse Proxy/Обзор системы|Traefik]]** - интеграция через Forward Auth middleware
- **[[Мой сервер/Second Mind Setup/Обзор системы|Second Mind]]** - защита доступа к заметкам
- **Redis** - хранение сессий и состояния

## Связанные документы

- **[[Authelia Authentication - Конфигурации]]** - детальные настройки всех компонентов
- **[[Authelia Authentication - Развертывание]]** - пошаговая установка
- **[[Authelia Authentication - Администрирование]]** - управление пользователями и мониторинг