# Authentik

Deploys [authentik](https://goauthentik.io) (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:

```yaml
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

```yaml
- 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