WIP: Authentik role with Quadlet pod approach - debugging container service generation
- Created authentik.pod file for proper pod definition - Removed superfluous authentik-pod.container file - Updated container templates to reference pod correctly - Issue: Quadlet still reports 'pod authentik is not Quadlet based' - Container services not being generated (only pod service works)
This commit is contained in:
227
roles/authentik/README.md
Normal file
227
roles/authentik/README.md
Normal file
@@ -0,0 +1,227 @@
|
||||
# Authentik Role
|
||||
|
||||
Self-contained Authentik authentication server deployment using Podman and Unix sockets.
|
||||
|
||||
## Overview
|
||||
|
||||
This role deploys Authentik as a containerized authentication service with:
|
||||
- **Unix socket IPC** for PostgreSQL and Valkey
|
||||
- **Rootless Podman** with systemd integration via Quadlet
|
||||
- **Self-contained permissions** management
|
||||
- **Caddy reverse proxy** configuration
|
||||
|
||||
## Architecture
|
||||
|
||||
```
|
||||
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
|
||||
│ Caddy Proxy │ │ Authentik Pod │ │ Infrastructure │
|
||||
│ │ │ │ │ │
|
||||
│ auth.jnss.me │───▶│ ┌─────────────┐ │ │ PostgreSQL │
|
||||
│ :443 │ │ │ Server │ │◄──▶│ (Unix Socket) │
|
||||
│ │ │ │ :9443 │ │ │ │
|
||||
│ │ │ └─────────────┘ │ │ Valkey │
|
||||
│ │ │ ┌─────────────┐ │◄──▶│ (Unix Socket) │
|
||||
│ │ │ │ Worker │ │ │ │
|
||||
│ │ │ └─────────────┘ │ │ │
|
||||
└─────────────────┘ └─────────────────┘ └─────────────────┘
|
||||
```
|
||||
|
||||
## Dependencies
|
||||
|
||||
- `postgresql` role (provides Unix socket infrastructure)
|
||||
- `valkey` role (provides Unix socket infrastructure)
|
||||
- `podman` role (provides container runtime)
|
||||
- `caddy` role (provides reverse proxy infrastructure)
|
||||
|
||||
## Configuration
|
||||
|
||||
### Required Variables
|
||||
|
||||
```yaml
|
||||
# Domain configuration
|
||||
authentik_domain: "auth.jnss.me"
|
||||
|
||||
# Database credentials
|
||||
authentik_db_password: "{{ vault_authentik_db_password }}"
|
||||
authentik_secret_key: "{{ vault_authentik_secret_key }}"
|
||||
authentik_default_admin_password: "{{ vault_authentik_admin_password }}"
|
||||
|
||||
# Infrastructure socket enablement
|
||||
postgresql_unix_socket_enabled: true
|
||||
valkey_unix_socket_enabled: true
|
||||
```
|
||||
|
||||
### Optional Variables
|
||||
|
||||
```yaml
|
||||
# Service configuration
|
||||
authentik_service_enabled: true
|
||||
authentik_service_state: "started"
|
||||
|
||||
# Container version
|
||||
authentik_version: "latest"
|
||||
|
||||
# Email configuration
|
||||
authentik_email_enabled: false
|
||||
authentik_email_host: "smtp.example.com"
|
||||
```
|
||||
|
||||
## Vault Variables Required
|
||||
|
||||
```yaml
|
||||
# Database password
|
||||
vault_authentik_db_password: "secure_db_password"
|
||||
|
||||
# Authentik secret key (generate with: openssl rand -base64 32)
|
||||
vault_authentik_secret_key: "long_random_secret_key"
|
||||
|
||||
# Admin user password
|
||||
vault_authentik_admin_password: "secure_admin_password"
|
||||
|
||||
# Existing infrastructure passwords
|
||||
vault_valkey_password: "valkey_password"
|
||||
```
|
||||
|
||||
## Usage
|
||||
|
||||
### Basic Deployment
|
||||
|
||||
```yaml
|
||||
- hosts: auth_servers
|
||||
roles:
|
||||
- postgresql
|
||||
- valkey
|
||||
- podman
|
||||
- caddy
|
||||
- authentik
|
||||
```
|
||||
|
||||
### With Tags
|
||||
|
||||
```yaml
|
||||
# Deploy only database setup
|
||||
ansible-playbook site.yml -t database
|
||||
|
||||
# Deploy only containers
|
||||
ansible-playbook site.yml -t containers
|
||||
|
||||
# Deploy only Caddy config
|
||||
ansible-playbook site.yml -t caddy
|
||||
```
|
||||
|
||||
## File Structure
|
||||
|
||||
```
|
||||
authentik/
|
||||
├── defaults/main.yml # Default variables
|
||||
├── handlers/main.yml # Service handlers
|
||||
├── meta/main.yml # Role dependencies
|
||||
├── tasks/
|
||||
│ ├── main.yml # Main orchestration
|
||||
│ ├── database.yml # Database setup
|
||||
│ └── cache.yml # Cache setup
|
||||
├── templates/
|
||||
│ ├── authentik.env.j2 # Environment variables
|
||||
│ ├── authentik.caddy.j2 # Caddy configuration
|
||||
│ ├── authentik-pod.container # Pod Quadlet file
|
||||
│ ├── authentik-server.container # Server Quadlet file
|
||||
│ └── authentik-worker.container # Worker Quadlet file
|
||||
└── README.md
|
||||
```
|
||||
|
||||
## Systemd Services
|
||||
|
||||
The role creates the following systemd services:
|
||||
|
||||
- `authentik-pod.service` - Main pod container
|
||||
- `authentik-server.service` - Web server container
|
||||
- `authentik-worker.service` - Background worker container
|
||||
|
||||
## Networking
|
||||
|
||||
- **External**: HTTPS via Caddy on port 443
|
||||
- **Internal**: Containers bind to `127.0.0.1:9000` (HTTP) and `127.0.0.1:9443` (HTTPS)
|
||||
- **Database**: Unix socket at `/var/run/postgresql/.s.PGSQL.5432`
|
||||
- **Cache**: Unix socket at `/var/run/valkey/valkey.sock`
|
||||
|
||||
## Security Features
|
||||
|
||||
- **Rootless containers** via Podman
|
||||
- **Unix socket IPC** eliminates network exposure
|
||||
- **User isolation** with dedicated `authentik` system user
|
||||
- **Group-based socket access** for PostgreSQL and Valkey
|
||||
- **TLS termination** at Caddy proxy
|
||||
- **Security headers** configured in Caddy
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Check Service Status
|
||||
|
||||
```bash
|
||||
systemctl status authentik-pod
|
||||
systemctl status authentik-server
|
||||
systemctl status authentik-worker
|
||||
```
|
||||
|
||||
### Check Logs
|
||||
|
||||
```bash
|
||||
journalctl -u authentik-server -f
|
||||
journalctl -u authentik-worker -f
|
||||
```
|
||||
|
||||
### Check Socket Connectivity
|
||||
|
||||
```bash
|
||||
# Test PostgreSQL socket
|
||||
sudo -u authentik psql -h /var/run/postgresql -U authentik authentik
|
||||
|
||||
# Test Valkey socket
|
||||
sudo -u authentik redis-cli -s /var/run/valkey/valkey.sock -n 1 ping
|
||||
```
|
||||
|
||||
### Verify Container Status
|
||||
|
||||
```bash
|
||||
podman --user authentik pod ps
|
||||
podman --user authentik ps
|
||||
```
|
||||
|
||||
## Post-Deployment
|
||||
|
||||
1. **Access Web Interface**: Navigate to `https://auth.jnss.me`
|
||||
2. **Login**: Use admin credentials from vault variables
|
||||
3. **Configure Providers**: Set up OAuth2/SAML providers for services
|
||||
4. **Create Applications**: Configure applications for SSO integration
|
||||
|
||||
## Maintenance
|
||||
|
||||
### Update Containers
|
||||
|
||||
```yaml
|
||||
# Update to specific version
|
||||
authentik_version: "2024.2.0"
|
||||
```
|
||||
|
||||
### Backup Data
|
||||
|
||||
Important directories to backup:
|
||||
- `{{ authentik_data_dir }}` - Application data
|
||||
- `{{ authentik_media_dir }}` - Uploaded media
|
||||
- PostgreSQL database dump
|
||||
- Vault variables
|
||||
|
||||
## Integration Examples
|
||||
|
||||
### Protect Service with Authentik
|
||||
|
||||
```caddy
|
||||
service.example.com {
|
||||
forward_auth https://auth.jnss.me {
|
||||
uri /outpost.goauthentik.io/auth/caddy
|
||||
copy_headers Remote-User Remote-Name Remote-Email Remote-Groups
|
||||
}
|
||||
|
||||
reverse_proxy localhost:8080
|
||||
}
|
||||
```
|
||||
Reference in New Issue
Block a user