digitalboard.core/roles/authentik

Authentik

Deploys authentik (server + worker + Postgres) as a Docker Compose stack behind Traefik, with all resources provisioned via templated blueprints.

What this role does

• Renders the Compose stack with traefik labels and an optional split-horizon host rewrite (see below)
• Provisions local users, groups, OIDC apps, Proxy/ForwardAuth apps, LDAP apps and outposts, and Entra ID OAuth sources via blueprints
• Configures the login screen (visible sources, local login fields)
• Supports declarative cleanup via authentik_removed_* lists

Variables

Full spec with types and defaults: meta/argument_specs.yml. The most common overrides:

Service

• authentik_domains (required, list): FQDNs the router accepts. First entry is the canonical hostname; further entries cover internal *.int.* names for server-to-server traffic.
• authentik_secret_key (required): PG fernet / signing secret. Generate with openssl rand -base64 60.
• authentik_postgres_password (required).
• authentik_image, authentik_port, authentik_log_level.

Split-horizon host rewrite

authentik_host_rewrite_domains lists hostnames that should reach the authentik container but make it generate URLs (OIDC issuer, password reset links, etc.) as if the request had arrived on authentik_domains[0].

For each entry the role:

• Creates a dedicated traefik router on that hostname
• Routes it to a URL-based loadbalancer service that disables passHostHeader, so the upstream Host header becomes the canonical FQDN
• Pins X-Forwarded-Host via middleware so the iss claim stays aligned with the public hostname browsers see

Use case: an internal auth.int.example.com keeps server-to-server traffic in the LAN, but Keycloak/Nextcloud/etc. still receive issuer URLs matching auth.example.com.

Blueprints

The role renders blueprints for:

• Local users (authentik_local_users)
• Groups (authentik_groups)
• OIDC applications (authentik_oidc_apps)
• Proxy applications (authentik_proxy_apps)
• Proxy outposts (authentik_proxy_outposts)
• LDAP applications (authentik_ldap_apps)
• LDAP outpost (authentik_ldap_outpost)
• Entra ID sources (authentik_entra_sources)
• Login-screen source visibility (authentik_login_sources)

Secrets are passed via the authentik_blueprint_env env-var indirection so they never land in rendered blueprint YAML on disk.

Proxy apps: mode and group restrictions

Each entry in authentik_proxy_apps supports:

• mode (default forward_single): one of proxy, forward_single, forward_domain
• allowed_groups: when set, a PolicyBinding is emitted per group on the application. authentik OR-evaluates bindings, so users in any listed group pass and users in none are denied.

Example:

authentik_proxy_apps:
  - slug: drawio
    name: drawio
    external_host: "https://drawio.example.com"
    mode: forward_single
    allowed_groups:
      - drawio-users
      - admins

Removing resources

Move slugs from the active list to the matching removal list:

• authentik_removed_oidc_apps
• authentik_removed_proxy_apps
• authentik_removed_local_users

After authentik has applied the deletion blueprint, remove the slug from the list to keep state clean.

Dependencies

• Run digitalboard.core.base first (Docker) and have the community.docker collection installed; the role drives the stack via community.docker.docker_compose_v2.
• Traefik network (authentik_traefik_network, default proxy) must exist beforehand (e.g. created by the traefik role); it is referenced as an external network in the Compose file.
• Internal backend network (authentik_backend_network, default backend).

Example playbook

- hosts: identity_servers
  roles:
    - role: digitalboard.core.authentik
      vars:
        authentik_domains:
          - "auth.example.com"
          - "auth.int.example.com"
        authentik_host_rewrite_domains:
          - "auth.int.example.com"
        authentik_secret_key: "{{ vault_authentik_secret_key }}"
        authentik_postgres_password: "{{ vault_authentik_pg_password }}"
        authentik_proxy_apps:
          - slug: drawio
            name: drawio
            external_host: "https://drawio.example.com"
            mode: forward_single
            allowed_groups: [drawio-users]

License

MIT-0