Wiki major update

updated with recent documentation
2026-01-21 19:18:39 -05:00
parent 30e0481685
commit ef55974b50
98 changed files with 32244 additions and 10 deletions
--- a/wiki/service-docs/authelia.md
+++ b/wiki/service-docs/authelia.md
@@ -0,0 +1,602 @@
+# Authelia - Single Sign-On & Two-Factor Authentication
+
+## Table of Contents
+- [Overview](#overview)
+- [What is Authelia?](#what-is-authelia)
+- [Why Use Authelia?](#why-use-authelia)
+- [How It Works](#how-it-works)
+- [Configuration in AI-Homelab](#configuration-in-ai-homelab)
+- [Official Resources](#official-resources)
+- [Educational Resources](#educational-resources)
+- [Docker Configuration](#docker-configuration)
+- [User Management](#user-management)
+- [Advanced Topics](#advanced-topics)
+- [Troubleshooting](#troubleshooting)
+
+## Overview
+
+**Category:** Core Infrastructure  
+**Docker Image:** [authelia/authelia](https://hub.docker.com/r/authelia/authelia)  
+**Default Stack:** `core.yml`  
+**Web UI:** `https://auth.${DOMAIN}`  
+**Authentication:** Self-authenticating (login portal)
+
+## What is Authelia?
+
+Authelia is an open-source authentication and authorization server providing single sign-on (SSO) and two-factor authentication (2FA) for your applications via a web portal. It acts as a gatekeeper between Traefik and your services.
+
+### Key Features
+- **Single Sign-On (SSO):** Log in once, access all protected services
+- **Two-Factor Authentication:** TOTP (Google Authenticator, Authy), WebAuthn, Security Keys
+- **Access Control:** Per-service, per-user, per-network rules
+- **Session Management:** Remember devices, revoke sessions
+- **Identity Verification:** Email verification for password resets
+- **Security Policies:** Custom policies per service (one_factor, two_factor, bypass)
+- **Lightweight:** Minimal resource usage
+- **Integration:** Works seamlessly with Traefik via ForwardAuth
+
+## Why Use Authelia?
+
+1. **Enhanced Security:** Add 2FA to services that don't support it natively
+2. **Centralized Authentication:** One login portal for all services
+3. **Granular Access Control:** Control who can access what
+4. **Remember Devices:** Don't re-authenticate on trusted devices
+5. **Protection Layer:** Extra security even if a service has vulnerabilities
+6. **Free & Open Source:** No licensing costs
+7. **Privacy:** Self-hosted, your data stays with you
+
+## How It Works
+
+```
+User → Traefik → Authelia (Check Auth) → Service
+                    ↓
+              Not Authenticated
+                    ↓
+              Login Portal
+                    ↓
+            Username/Password
+                    ↓
+              2FA (TOTP/WebAuthn)
+                    ↓
+              Cookie Issued
+                    ↓
+            Access Granted
+```
+
+### Authentication Flow
+
+1. **User accesses** `https://sonarr.yourdomain.com`
+2. **Traefik** sends request to Authelia (ForwardAuth middleware)
+3. **Authelia checks** for valid authentication cookie
+4. **If not authenticated:**
+   - Redirects to `https://auth.yourdomain.com`
+   - User enters username/password
+   - User completes 2FA challenge
+   - Authelia issues authentication cookie
+5. **If authenticated:**
+   - Authelia checks access control rules
+   - If authorized, request forwarded to service
+6. **Session remembered** for configured duration
+
+### Integration with Traefik
+
+Services protected by Authelia use a special middleware:
+
+```yaml
+labels:
+  - "traefik.http.routers.sonarr.middlewares=authelia@docker"
+```
+
+This tells Traefik to verify authentication before allowing access.
+
+## Configuration in AI-Homelab
+
+### Directory Structure
+
+```
+/opt/stacks/core/authelia/
+├── configuration.yml    # Main configuration
+├── users_database.yml   # User accounts and passwords
+└── db.sqlite3          # Session/TOTP storage (auto-generated)
+```
+
+### Main Configuration (`configuration.yml`)
+
+```yaml
+server:
+  host: 0.0.0.0
+  port: 9091
+
+log:
+  level: info
+
+theme: dark
+
+totp:
+  issuer: yourdomain.com
+
+authentication_backend:
+  file:
+    path: /config/users_database.yml
+    password:
+      algorithm: argon2id
+      iterations: 1
+      salt_length: 16
+      parallelism: 8
+      memory: 64
+
+access_control:
+  default_policy: deny
+  
+  rules:
+    # Bypass auth for public services
+    - domain: "public.yourdomain.com"
+      policy: bypass
+    
+    # One-factor for internal networks
+    - domain: "*.yourdomain.com"
+      policy: one_factor
+      networks:
+        - 192.168.1.0/24
+    
+    # Two-factor for everything else
+    - domain: "*.yourdomain.com"
+      policy: two_factor
+
+session:
+  name: authelia_session
+  domain: yourdomain.com
+  expiration: 1h
+  inactivity: 5m
+  remember_me_duration: 1M
+
+regulation:
+  max_retries: 5
+  find_time: 10m
+  ban_time: 15m
+
+storage:
+  local:
+    path: /config/db.sqlite3
+
+notifier:
+  filesystem:
+    filename: /config/notification.txt
+  # Alternative: SMTP for email notifications
+  # smtp:
+  #   username: your-email@gmail.com
+  #   password: your-app-password
+  #   host: smtp.gmail.com
+  #   port: 587
+  #   sender: your-email@gmail.com
+```
+
+### Users Database (`users_database.yml`)
+
+```yaml
+users:
+  john:
+    displayname: "John Doe"
+    password: "$argon2id$v=19$m=65536,t=3,p=4$BpLnfgDsc2WD8F2q$qQv8kuZHAOhqx7/Ju3qNqawhKhh9q9L6KUXCv7RQ0MA"
+    email: john@example.com
+    groups:
+      - admins
+      - users
+  
+  jane:
+    displayname: "Jane Smith"
+    password: "$argon2id$v=19$m=65536,t=3,p=4$..."
+    email: jane@example.com
+    groups:
+      - users
+```
+
+### Generating Password Hashes
+
+```bash
+# Using Docker
+docker run --rm authelia/authelia:latest authelia crypto hash generate argon2 --password 'YourPasswordHere'
+
+# Or from within the container
+docker exec -it authelia authelia crypto hash generate argon2 --password 'YourPasswordHere'
+```
+
+### Environment Variables
+
+```bash
+AUTHELIA_JWT_SECRET=your-super-secret-jwt-key-min-32-chars
+AUTHELIA_SESSION_SECRET=your-super-secret-session-key-min-32-chars
+AUTHELIA_STORAGE_ENCRYPTION_KEY=your-super-secret-storage-key-min-32-chars
+```
+
+**Generate secure secrets:**
+```bash
+# Generate random 64-character hex strings
+openssl rand -hex 32
+```
+
+## Official Resources
+
+- **Website:** https://www.authelia.com
+- **Documentation:** https://www.authelia.com/docs/
+- **GitHub:** https://github.com/authelia/authelia
+- **Docker Hub:** https://hub.docker.com/r/authelia/authelia
+- **Community:** https://discord.authelia.com
+- **Configuration Examples:** https://github.com/authelia/authelia/tree/master/examples
+
+## Educational Resources
+
+### Videos
+- [Authelia - The BEST Authentication Platform (Techno Tim)](https://www.youtube.com/watch?v=u6H-Qwf4nZA)
+- [Secure Your Self-Hosted Apps with Authelia (DB Tech)](https://www.youtube.com/watch?v=4UKOh3ssQSU)
+- [Authelia Setup with Traefik (Wolfgang's Channel)](https://www.youtube.com/watch?v=g7oUvxGqvPw)
+- [Two-Factor Authentication Explained](https://www.youtube.com/watch?v=0mvCeNsTa1g)
+
+### Articles & Guides
+- [Authelia Official Documentation](https://www.authelia.com/docs/)
+- [Integration with Traefik](https://www.authelia.com/integration/proxies/traefik/)
+- [Access Control Configuration](https://www.authelia.com/configuration/security/access-control/)
+- [Migration from Organizr/Authelia v3](https://www.authelia.com/docs/configuration/migration.html)
+
+### Concepts to Learn
+- **Single Sign-On (SSO):** Authentication once for multiple applications
+- **Two-Factor Authentication (2FA):** Second verification method (TOTP, WebAuthn)
+- **TOTP:** Time-based One-Time Password (Google Authenticator)
+- **WebAuthn:** Web Authentication standard (Yubikey, Touch ID)
+- **ForwardAuth:** Proxy authentication delegation
+- **LDAP:** Lightweight Directory Access Protocol (user directories)
+- **Session Management:** Cookie-based authentication tracking
+- **Argon2:** Modern password hashing algorithm
+
+## Docker Configuration
+
+### Complete Service Definition
+
+```yaml
+authelia:
+  image: authelia/authelia:latest
+  container_name: authelia
+  restart: unless-stopped
+  networks:
+    - traefik-network
+  volumes:
+    - /opt/stacks/core/authelia:/config
+  environment:
+    - TZ=America/New_York
+    - AUTHELIA_JWT_SECRET=${AUTHELIA_JWT_SECRET}
+    - AUTHELIA_SESSION_SECRET=${AUTHELIA_SESSION_SECRET}
+    - AUTHELIA_STORAGE_ENCRYPTION_KEY=${AUTHELIA_STORAGE_ENCRYPTION_KEY}
+  labels:
+    - "traefik.enable=true"
+    - "traefik.http.routers.authelia.rule=Host(`auth.${DOMAIN}`)"
+    - "traefik.http.routers.authelia.entrypoints=websecure"
+    - "traefik.http.routers.authelia.tls.certresolver=letsencrypt"
+    
+    # ForwardAuth Middleware
+    - "traefik.http.middlewares.authelia.forwardAuth.address=http://authelia:9091/api/verify?rd=https://auth.${DOMAIN}"
+    - "traefik.http.middlewares.authelia.forwardAuth.trustForwardHeader=true"
+    - "traefik.http.middlewares.authelia.forwardAuth.authResponseHeaders=Remote-User,Remote-Groups,Remote-Name,Remote-Email"
+```
+
+### Protecting Services
+
+Add the Authelia middleware to any service:
+
+```yaml
+myservice:
+  image: myapp:latest
+  labels:
+    - "traefik.enable=true"
+    - "traefik.http.routers.myservice.rule=Host(`myservice.${DOMAIN}`)"
+    - "traefik.http.routers.myservice.entrypoints=websecure"
+    - "traefik.http.routers.myservice.tls.certresolver=letsencrypt"
+    - "traefik.http.routers.myservice.middlewares=authelia@docker"  # <-- Add this
+  networks:
+    - traefik-network
+```
+
+## User Management
+
+### Adding Users
+
+1. **Generate password hash:**
+   ```bash
+   docker exec -it authelia authelia crypto hash generate argon2 --password 'SecurePassword123!'
+   ```
+
+2. **Add to `users_database.yml`:**
+   ```yaml
+   users:
+     newuser:
+       displayname: "New User"
+       password: "$argon2id$v=19$m=65536..."  # Paste hash here
+       email: newuser@example.com
+       groups:
+         - users
+   ```
+
+3. **Restart Authelia:**
+   ```bash
+   docker restart authelia
+   ```
+
+### Removing Users
+
+Simply remove the user block from `users_database.yml` and restart.
+
+### Resetting Passwords
+
+Generate a new hash and replace the password field, then restart Authelia.
+
+### Group-Based Access Control
+
+```yaml
+access_control:
+  rules:
+    # Only admins can access admin panel
+    - domain: "admin.yourdomain.com"
+      policy: two_factor
+      subject:
+        - "group:admins"
+    
+    # Users can access media services
+    - domain:
+        - "plex.yourdomain.com"
+        - "jellyfin.yourdomain.com"
+      policy: one_factor
+      subject:
+        - "group:users"
+```
+
+## Advanced Topics
+
+### SMTP Email Notifications
+
+Configure email for password resets and notifications:
+
+```yaml
+notifier:
+  smtp:
+    username: your-email@gmail.com
+    password: your-app-password  # Use app-specific password
+    host: smtp.gmail.com
+    port: 587
+    sender: your-email@gmail.com
+    subject: "[Authelia] {title}"
+```
+
+### LDAP Authentication
+
+For advanced setups with Active Directory or FreeIPA:
+
+```yaml
+authentication_backend:
+  ldap:
+    url: ldap://ldap.example.com
+    base_dn: dc=example,dc=com
+    username_attribute: uid
+    additional_users_dn: ou=users
+    users_filter: (&({username_attribute}={input})(objectClass=person))
+    additional_groups_dn: ou=groups
+    groups_filter: (&(member={dn})(objectClass=groupOfNames))
+    user: cn=admin,dc=example,dc=com
+    password: admin-password
+```
+
+### Per-Service Policies
+
+```yaml
+access_control:
+  rules:
+    # Public services (no auth)
+    - domain: "public.yourdomain.com"
+      policy: bypass
+    
+    # Internal network only (one factor)
+    - domain: "internal.yourdomain.com"
+      policy: one_factor
+      networks:
+        - 192.168.1.0/24
+    
+    # High security (two factor required)
+    - domain:
+        - "banking.yourdomain.com"
+        - "finance.yourdomain.com"
+      policy: two_factor
+```
+
+### Network-Based Rules
+
+```yaml
+access_control:
+  rules:
+    # Bypass for local network
+    - domain: "*.yourdomain.com"
+      policy: bypass
+      networks:
+        - 192.168.1.0/24
+        - 172.16.0.0/12
+    
+    # Require 2FA from external networks
+    - domain: "*.yourdomain.com"
+      policy: two_factor
+```
+
+### Custom Session Duration
+
+```yaml
+session:
+  expiration: 12h        # Session expires after 12 hours
+  inactivity: 30m        # Session expires after 30 min inactivity
+  remember_me_duration: 1M  # Remember device for 1 month
+```
+
+## Troubleshooting
+
+### Cannot Access Login Portal
+
+```bash
+# Check if Authelia is running
+docker ps | grep authelia
+
+# View logs
+docker logs authelia
+
+# Check configuration syntax
+docker exec authelia authelia validate-config /config/configuration.yml
+
+# Test connectivity
+curl http://localhost:9091/api/health
+```
+
+### Services Not Requiring Authentication
+
+```bash
+# Verify middleware is applied
+docker inspect service-name | grep authelia
+
+# Check Traefik dashboard for middleware
+# Visit: https://traefik.yourdomain.com
+
+# Verify Authelia middleware definition
+docker logs traefik | grep authelia
+
+# Test ForwardAuth directly
+curl -I -H "Host: service.yourdomain.com" http://authelia:9091/api/verify
+```
+
+### Login Not Working
+
+```bash
+# Check users_database.yml syntax
+docker exec authelia cat /config/users_database.yml
+
+# Verify password hash
+docker exec authelia authelia crypto hash validate argon2 --password 'YourPassword' --hash '$argon2id...'
+
+# Check logs for authentication attempts
+docker logs authelia | grep -i auth
+
+# Verify JWT and session secrets are set
+docker exec authelia env | grep SECRET
+```
+
+### 2FA Not Working
+
+```bash
+# Check TOTP configuration
+docker exec authelia cat /config/configuration.yml | grep -A5 totp
+
+# Verify time synchronization (critical for TOTP)
+docker exec authelia date
+date  # Compare with host
+
+# Check TOTP database
+sqlite3 /opt/stacks/core/authelia/db.sqlite3 "SELECT * FROM totp_configurations;"
+
+# Reset 2FA for user (delete TOTP entry)
+sqlite3 /opt/stacks/core/authelia/db.sqlite3 "DELETE FROM totp_configurations WHERE username='username';"
+```
+
+### Session Issues
+
+```bash
+# Check session configuration
+docker exec authelia cat /config/configuration.yml | grep -A10 session
+
+# Clear session database
+sqlite3 /opt/stacks/core/authelia/db.sqlite3 "DELETE FROM user_sessions;"
+
+# Verify domain matches
+# session.domain should match your base domain
+# Example: session.domain: yourdomain.com
+#          Services: *.yourdomain.com
+```
+
+### Configuration Validation
+
+```bash
+# Validate full configuration
+docker exec authelia authelia validate-config /config/configuration.yml
+
+# Check for common issues
+docker logs authelia | grep -i error
+docker logs authelia | grep -i warn
+```
+
+## Security Best Practices
+
+1. **Strong Secrets:** Use 32+ character random secrets for JWT, session, and storage encryption
+2. **Enable 2FA:** Require two-factor for external access
+3. **Network Policies:** Use bypass for trusted networks, two_factor for internet
+4. **Session Management:** Set appropriate expiration and inactivity timeouts
+5. **Regular Updates:** Keep Authelia updated for security patches
+6. **Email Notifications:** Configure SMTP for password reset security
+7. **Backup:** Regularly backup `users_database.yml` and `db.sqlite3`
+8. **Rate Limiting:** Configure `regulation` to prevent brute force
+9. **Log Monitoring:** Review logs for failed authentication attempts
+10. **Use HTTPS Only:** Never expose Authelia over plain HTTP
+
+## Common Use Cases
+
+### Home Access (No Auth)
+
+```yaml
+- domain: "*.yourdomain.com"
+  policy: bypass
+  networks:
+    - 192.168.1.0/24
+```
+
+### Friends & Family (One Factor)
+
+```yaml
+- domain:
+    - "plex.yourdomain.com"
+    - "jellyfin.yourdomain.com"
+  policy: one_factor
+```
+
+### Admin Services (Two Factor)
+
+```yaml
+- domain:
+    - "dockge.yourdomain.com"
+    - "portainer.yourdomain.com"
+  policy: two_factor
+  subject:
+    - "group:admins"
+```
+
+### VPN Required
+
+```yaml
+- domain: "admin.yourdomain.com"
+  policy: bypass
+  networks:
+    - 10.8.0.0/24  # Gluetun VPN network
+```
+
+## Summary
+
+Authelia is your homelab's security layer. It:
+- Adds authentication to any service
+- Provides SSO across all applications
+- Enables 2FA even for services that don't support it
+- Offers granular access control
+- Protects against unauthorized access
+- Integrates seamlessly with Traefik
+
+Setting up Authelia properly is one of the most important security steps for your homelab. Take time to understand access control rules and test your configuration thoroughly. Always keep the `users_database.yml` and `db.sqlite3` backed up, as they contain critical authentication data.
+
+## Related Services
+
+- **[Traefik](traefik.md)** - Reverse proxy that integrates with Authelia for authentication
+- **[DuckDNS](duckdns.md)** - Dynamic DNS required for SSL certificates
+- **[Sablier](sablier.md)** - Lazy loading that can work with Authelia-protected services
+
+## See Also
+
+- **[SSO Bypass Guide](../docker-guidelines.md#when-to-use-authelia-sso)** - When to disable authentication for services
+- **[2FA Setup](../getting-started.md#set-up-2fa-with-authelia)** - Enable two-factor authentication
+- **[Access Control Rules](../docker-guidelines.md#authelia-bypass-example-jellyfin)** - Configure bypass rules for specific services