Zum Inhalt

Authentik role

Deploy Authentik, an open-source Identity Provider (IdP) with support for SAML, OAuth2, OIDC, LDAP, and more, via Traefik reverse proxy.

Usage

Configure Authentik credentials in your inventory:

1
2
3
4
5
6
7
# vars/main.yml
registry_username: your_registry_user
registry_password: your_registry_password
authentik_pg_user: authentik
authentik_pg_password: your_secure_database_password
authentik_secret_key: long_random_secret_key_50_chars_minimum
authentik_initpass: your_initial_admin_password

Include the role in your playbook:

1
2
3
4
# playbooks/proxmox/deploy_docker_idp.yml
- hosts: docker_idp
  roles:
    - role: authentik

The role provides these tags: - authentik-install - Deploy Authentik with PostgreSQL and Redis - authentik-uninstall - Remove Authentik stack

Docs

Deploy Authentik to your Docker host:

1
ansible-playbook -i inventory/hosts.yml playbooks/proxmox/deploy_docker_idp.yml --tags authentik-install

Remove Authentik installation:

1
ansible-playbook -i inventory/hosts.yml playbooks/proxmox/deploy_docker_idp.yml --tags authentik-uninstall

Configuration Details

The role deploys Authentik 2025.10 with: - Custom Images: From private Gitea registry - Database: PostgreSQL 17 Alpine with health checks - Cache: Redis Alpine with persistence - Server: Authentik web server and API - Worker: Background task processor - Traefik Integration: Automatic HTTPS via Traefik - Email: Mailpit integration for notifications - Persistent Storage: Volumes for database, Redis, media, and templates

Architecture

The deployment consists of four containers:

  1. authentik_db - PostgreSQL 17 database
  2. authentik_redis - Redis cache and message broker
  3. authentik_server - Web UI and API (port 9443)
  4. authentik_worker - Background jobs and tasks

Accessing Authentik

After deployment, Authentik is available at: - URL: https://authentik.rwcloud.ch - Port: 9443 (internal, accessed via Traefik)

Initial login: - Username: akadmin - Password: Configured via authentik_initpass

Important: Change the admin password immediately after first login!

Email Configuration

The role automatically configures Mailpit integration: - SMTP Host: mailpit.rwcloud.ch:1025 - From Address: authentik@rwcloud.ch - Protocol: SMTP (no authentication)

Authentik will send: - User registration emails - Password reset emails - Enrollment invitations - Event notifications

Secret Key

The authentik_secret_key is critical for encryption: - Minimum 50 characters - Used for cookie and session encryption - Never change after initial deployment (will invalidate sessions)

Generate a secure secret: 

1
openssl rand -base64 60

Health Checks

The deployment includes health checks:

PostgreSQL: 

1
pg_isready -d authentik -U authentik

Redis: 

1
redis-cli ping | grep PONG

Server and worker wait for healthy database and Redis before starting.

Storage

Five volumes are created: - postgres17 - PostgreSQL database data - redis - Redis persistence (RDB snapshots every 60 seconds) - media - Uploaded media files (logos, backgrounds) - custom-templates - Custom email and notification templates

Networks

Two networks are used: - authentik (internal) - Database and Redis communication - proxy (external) - Traefik reverse proxy access

Supported Protocols

Authentik supports multiple authentication protocols:

  • OAuth2 / OpenID Connect (OIDC) - Modern web applications
  • SAML - Enterprise applications
  • LDAP - Legacy applications
  • Proxy Provider - Forward authentication
  • SCIM - User provisioning

Setting Up Applications

  1. Login to Authentik → https://authentik.rwcloud.ch

  2. Create Application:

  3. Admin Interface → Applications → Create
  4. Name: Your application name

  5. Slug: app-identifier

  6. Create Provider:

  7. Choose provider type (OAuth2/SAML/LDAP/Proxy)
  8. Configure redirect URIs
  9. Set client ID and secret

  10. Configure scopes and claims

  11. Bind Provider to Application

  12. Configure Application:

  13. Use generated client ID and secret
  14. Set redirect URI: https://app.example.com/oauth2/callback
  15. Configure issuer URL: https://authentik.rwcloud.ch/application/o/app-slug/

OAuth2 / OIDC Example

For OIDC applications:

1
2
3
4
5
# Application configuration
client_id: generated_client_id
client_secret: generated_client_secret
issuer_url: https://authentik.rwcloud.ch/application/o/myapp/
redirect_url: https://myapp.example.com/oauth2/callback

LDAP Provider

For applications requiring LDAP:

  1. Create LDAP provider in Authentik
  2. Note the bind DN and password
  3. Configure application: 
    1
2
3
    LDAP Server: authentik-server:389
Bind DN: cn=ldapservice,ou=users,dc=ldap,dc=goauthentik,dc=io
Base DN: dc=ldap,dc=goauthentik,dc=io

User Management

Authentik provides: - User registration (optional) - Email verification - Password policies - MFA (TOTP, WebAuthn, SMS) - Social login integration - Group-based access control - Fine-grained permissions

Flows

Customize authentication flows: - Login flow (authentication stages) - Enrollment flow (user registration) - Recovery flow (password reset) - Authorization flow (OAuth consent)

Policies

Create policies for access control: - Expression policies (Python code) - Group membership policies - Password policies - Reputation policies - Event matcher policies

Integration Examples

Gitea (via OIDC): - Admin → Site Administration → Authentication Sources - Add OAuth2 source: OpenID Connect - Provider URL: https://authentik.rwcloud.ch/application/o/gitea/.well-known/openid-configuration

Grafana (via OIDC): 

1
2
3
4
5
6
7
[auth.generic_oauth]
enabled = true
client_id = grafana_client_id
client_secret = grafana_client_secret
auth_url = https://authentik.rwcloud.ch/application/o/authorize/
token_url = https://authentik.rwcloud.ch/application/o/token/
api_url = https://authentik.rwcloud.ch/application/o/userinfo/

Nextcloud (via SAML): - Install "SSO & SAML authentication" app - Configure SAML IdP: https://authentik.rwcloud.ch - Import metadata from Authentik

Monitoring

Check container health:

1
2
3
4
docker ps | grep authentik
docker logs authentik_server
docker logs authentik_worker
docker exec authentik_db pg_isready

View application logs in Authentik UI: - Admin Interface → Events → Logs

Backup

Critical data to backup: - PostgreSQL database (volume: postgres17) - Redis data (volume: redis) - Media files (volume: media) - Secret key (stored in inventory)

Updates

Update to latest Authentik version:

  1. Change image version in install.yml

  2. Re-run deployment: 

    1
    ansible-playbook -i inventory/hosts.yml playbooks/proxmox/deploy_docker_idp.yml --tags authentik-install

  3. Check release notes: https://goauthentik.io/docs/releases/

Resources