rick-infra/roles/authentik

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

# 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

# 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

# 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

- hosts: auth_servers
  roles:
    - postgresql
    - valkey
    - podman
    - caddy
    - authentik

With Tags

# 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

systemctl status authentik-pod
systemctl status authentik-server  
systemctl status authentik-worker

Check Logs

journalctl -u authentik-server -f
journalctl -u authentik-worker -f

Check Socket Connectivity

# 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

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

# 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

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
}