14c81657d7
Each of the five roles touched in this branch now ships: * meta/argument_specs.yml: typed schema for every variable in defaults/main.yml plus the optional inputs surfaced via this branch (traefik_extra_hosts, authentik_host_rewrite_domains, authentik_proxy_apps.mode / .allowed_groups, drawio_extra_domains, drawio_authentik_forward_auth*, garage_webui_authentik_forward_auth*). All five specs load cleanly through ansible-core's ArgumentSpecValidator. * README.md: replaces the ansible-galaxy boilerplate (where it was still in place) with a focused write-up — service vars, required secrets, ForwardAuth/idempotency notes, dependencies, and a working example playbook. authentik and garage READMEs are rewritten to cover the new knobs while preserving their existing content.
131 lines
4 KiB
Markdown
131 lines
4 KiB
Markdown
# 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
|
|
|
|
- Traefik network (`authentik_traefik_network`, default `proxy`)
|
|
- 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
|