Wiki major update
updated with recent documentation
This commit is contained in:
kelinfoxy
256
wiki/Authelia-Customization.md
Normal file
256
wiki/Authelia-Customization.md
Normal file
@@ -0,0 +1,256 @@
|
||||
# Authelia Customization Guide
|
||||
|
||||
This guide covers how to customize Authelia for your specific needs.
|
||||
|
||||
## Available Customization Options
|
||||
|
||||
### 1. Branding and Appearance
|
||||
Edit `/opt/stacks/core/authelia/configuration.yml`:
|
||||
|
||||
```yaml
|
||||
# Custom logo and branding
|
||||
theme: dark # Options: light, dark, grey, auto
|
||||
|
||||
# No built-in web UI for configuration
|
||||
# All settings managed via YAML files
|
||||
```
|
||||
|
||||
### 2. User Management
|
||||
Users are managed in `/opt/stacks/core/authelia/users_database.yml`:
|
||||
|
||||
```yaml
|
||||
users:
|
||||
username:
|
||||
displayname: "Display Name"
|
||||
password: "$argon2id$v=19$m=65536..." # Generated with authelia hash-password
|
||||
email: user@example.com
|
||||
groups:
|
||||
- admins
|
||||
- users
|
||||
```
|
||||
|
||||
Generate password hash:
|
||||
```bash
|
||||
docker run --rm authelia/authelia:4.37 authelia crypto hash generate argon2 --password 'yourpassword'
|
||||
```
|
||||
|
||||
### 3. Access Control Rules
|
||||
Customize who can access what in `configuration.yml`:
|
||||
|
||||
```yaml
|
||||
access_control:
|
||||
default_policy: deny
|
||||
|
||||
rules:
|
||||
# Public services (no auth)
|
||||
- domain:
|
||||
- "jellyfin.yourdomain.com"
|
||||
- "plex.yourdomain.com"
|
||||
policy: bypass
|
||||
|
||||
# Admin only services
|
||||
- domain:
|
||||
- "dockge.yourdomain.com"
|
||||
- "portainer.yourdomain.com"
|
||||
policy: two_factor
|
||||
subject:
|
||||
- "group:admins"
|
||||
|
||||
# All authenticated users
|
||||
- domain: "*.yourdomain.com"
|
||||
policy: one_factor
|
||||
```
|
||||
|
||||
### 4. Two-Factor Authentication (2FA)
|
||||
- TOTP (Time-based One-Time Password) via apps like Google Authenticator, Authy
|
||||
- Configure in `configuration.yml` under `totp:` section
|
||||
- Per-user enrollment via Authelia UI at `https://auth.${DOMAIN}`
|
||||
|
||||
### 5. Session Management
|
||||
Edit `configuration.yml`:
|
||||
|
||||
```yaml
|
||||
session:
|
||||
name: authelia_session
|
||||
expiration: 1h # How long before re-login required
|
||||
inactivity: 5m # Timeout after inactivity
|
||||
remember_me_duration: 1M # "Remember me" checkbox duration
|
||||
```
|
||||
|
||||
### 6. Notification Settings
|
||||
Email notifications for password resets, 2FA enrollment:
|
||||
|
||||
```yaml
|
||||
notifier:
|
||||
smtp:
|
||||
host: smtp.gmail.com
|
||||
port: 587
|
||||
username: your-email@gmail.com
|
||||
password: app-password
|
||||
sender: authelia@yourdomain.com
|
||||
```
|
||||
|
||||
## No Web UI for Configuration
|
||||
|
||||
⚠️ **Important**: Authelia does **not** have a configuration web UI. All configuration is done via YAML files:
|
||||
- `/opt/stacks/core/authelia/configuration.yml` - Main settings
|
||||
- `/opt/stacks/core/authelia/users_database.yml` - User accounts
|
||||
|
||||
This is **by design** and makes Authelia perfect for AI management and security-first approach:
|
||||
- AI can read and modify YAML files
|
||||
- Version control friendly
|
||||
- No UI clicks required
|
||||
- Infrastructure as code
|
||||
- Secure by default
|
||||
|
||||
**Web UI Available For:**
|
||||
- Login page: `https://auth.${DOMAIN}`
|
||||
- User profile: Change password, enroll 2FA
|
||||
- Device enrollment: Manage trusted devices
|
||||
|
||||
## Alternative with Web UI: Authentik
|
||||
|
||||
If you need a web UI for user management, Authentik is included in the alternatives stack:
|
||||
- **Authentik**: Full-featured SSO with web UI for user/group management
|
||||
- Access at: `https://authentik.${DOMAIN}`
|
||||
- Includes PostgreSQL database and Redis cache
|
||||
- More complex but offers GUI-based configuration
|
||||
- Deploy via Dockge when needed
|
||||
|
||||
**Other Alternatives:**
|
||||
- **Keycloak**: Enterprise-grade SSO with web UI
|
||||
- **Authelia + LDAP**: Use LDAP with web management (phpLDAPadmin, etc.)
|
||||
|
||||
## Quick Configuration with AI
|
||||
|
||||
Since all Authelia configuration is file-based, you can use the AI assistant to:
|
||||
- Add/remove users
|
||||
- Modify access rules
|
||||
- Change session settings
|
||||
- Update branding
|
||||
- Enable/disable features
|
||||
|
||||
Just ask: "Add a new user to Authelia" or "Change session timeout to 2 hours"
|
||||
|
||||
## Common Customizations
|
||||
|
||||
### Adding a New User
|
||||
|
||||
1. Generate password hash:
|
||||
```bash
|
||||
docker run --rm authelia/authelia:4.37 authelia crypto hash generate argon2 --password 'newuserpassword'
|
||||
```
|
||||
|
||||
2. Edit `/opt/stacks/core/authelia/users_database.yml`:
|
||||
```yaml
|
||||
users:
|
||||
admin:
|
||||
# existing admin user...
|
||||
|
||||
newuser:
|
||||
displayname: "New User"
|
||||
password: "$argon2id$v=19$m=65536..." # paste generated hash
|
||||
email: newuser@example.com
|
||||
groups:
|
||||
- users
|
||||
```
|
||||
|
||||
3. Restart Authelia:
|
||||
```bash
|
||||
cd /opt/stacks/core
|
||||
docker compose restart authelia
|
||||
```
|
||||
|
||||
### Bypass SSO for Specific Service
|
||||
|
||||
Edit the service's Traefik labels to remove the Authelia middleware:
|
||||
|
||||
```yaml
|
||||
# Before (SSO protected)
|
||||
labels:
|
||||
- "traefik.http.routers.service.middlewares=authelia@docker"
|
||||
|
||||
# After (bypass SSO)
|
||||
labels:
|
||||
# - "traefik.http.routers.service.middlewares=authelia@docker" # commented out
|
||||
```
|
||||
|
||||
### Change Session Timeout
|
||||
|
||||
Edit `/opt/stacks/core/authelia/configuration.yml`:
|
||||
```yaml
|
||||
session:
|
||||
expiration: 12h # Changed from 1h to 12h
|
||||
inactivity: 30m # Changed from 5m to 30m
|
||||
```
|
||||
|
||||
Restart Authelia to apply changes.
|
||||
|
||||
### Enable SMTP Notifications
|
||||
|
||||
Edit `/opt/stacks/core/authelia/configuration.yml`:
|
||||
```yaml
|
||||
notifier:
|
||||
smtp:
|
||||
host: smtp.gmail.com
|
||||
port: 587
|
||||
username: your-email@gmail.com
|
||||
password: your-app-password # Use app-specific password
|
||||
sender: authelia@yourdomain.com
|
||||
subject: "[Authelia] {title}"
|
||||
```
|
||||
|
||||
### Create Admin-Only Access Rule
|
||||
|
||||
Edit `/opt/stacks/core/authelia/configuration.yml`:
|
||||
```yaml
|
||||
access_control:
|
||||
rules:
|
||||
# Admin-only services
|
||||
- domain:
|
||||
- "dockge.yourdomain.duckdns.org"
|
||||
- "traefik.yourdomain.duckdns.org"
|
||||
- "portainer.yourdomain.duckdns.org"
|
||||
policy: two_factor
|
||||
subject:
|
||||
- "group:admins"
|
||||
|
||||
# All other services - any authenticated user
|
||||
- domain: "*.yourdomain.duckdns.org"
|
||||
policy: one_factor
|
||||
```
|
||||
|
||||
Restart Authelia after changes.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### User Can't Log In
|
||||
|
||||
1. Check password hash format in users_database.yml
|
||||
2. Verify email address matches
|
||||
3. Check Authelia logs: `docker logs authelia`
|
||||
|
||||
### 2FA Not Working
|
||||
|
||||
1. Ensure time sync on server: `timedatectl`
|
||||
2. Check TOTP configuration in configuration.yml
|
||||
3. Regenerate QR code for user
|
||||
|
||||
### Sessions Expire Too Quickly
|
||||
|
||||
Increase session expiration in configuration.yml:
|
||||
```yaml
|
||||
session:
|
||||
expiration: 24h
|
||||
inactivity: 1h
|
||||
```
|
||||
|
||||
### Can't Access Specific Service
|
||||
|
||||
Check access control rules - service domain may be blocked by default_policy: deny
|
||||
|
||||
## Additional Resources
|
||||
|
||||
- [Authelia Documentation](https://www.authelia.com/docs/)
|
||||
- [Authelia Service Docs](service-docs/authelia.md)
|
||||
- [Getting Started Guide](getting-started.md)
|
||||
Reference in New Issue
Block a user