Authentik¶
Authentik is an open-source identity provider for modern SSO. It supports OAuth2/OIDC, SAML, LDAP, and more.
The Docker image comes from ghcr.io/goauthentik/server.
Setup¶
Without automated bootstrap, complete Authentik's initial setup flow after the first deployment:
https://authentik.demo.ops.ag/if/flow/initial-setup/
Authentik retains its upstream akadmin bootstrap administrator as a recovery identity. For an automated first start, set authentik.bootstrap_enabled: true and provide authentik.bootstrap_email.
To provision the normal growneticsOS administrator, also set authentik.managed_admin_enabled: true. Each deploy then reconciles the configured user (default username admin) into growneticsOS Users, growneticsOS Admins, and the upstream authentik Admins group. Existing memberships are preserved. The managed username cannot be akadmin.
The managed administrator receives the encrypted global default_password only when the account is created. Ordinary deploys reconcile its profile and memberships but never reset or rotate its password.
Recovery¶
The two Authentik identities and recovery files are:
akadmin recovery password: settings/passwords/authentik_admin_password
API token: settings/passwords/authentik_bootstrap_token
managed admin username: authentik.managed_admin_username (default admin)
managed admin password: encrypted global default_password, create-only
Ordinary deploys do not rotate either administrator password. Use akadmin and its recovery password to repair or unlock the managed administrator. Keep both files private; the API token is used by Ansible for reconciliation.
Authentik stores its data in /var/homelabos/authentik/data/.
Authentik's embedded proxy outpost is used for Traefik forward authentication, so the worker does not receive the host Docker socket. This avoids granting a web-facing identity service root-equivalent control of the Docker host. A separately managed outpost can be added later behind a restricted Docker socket proxy if needed.
Automatic dashboard cards¶
Every enabled HomelabOS service with a web UI automatically gets a launch card
on the Authentik user dashboard. Reconciliation runs during a full deploy and
during make update_one authentik, once the Authentik API is reachable.
A service is selected when it is enabled and its metadata declares a positive
port. Authentik itself is excluded, as are meta-services with no UI. Launch
URLs derive the same way the deploy does: the service's domain when set,
otherwise its subdomain plus the base domain.
Cards created this way are marked with:
meta_publisher: growneticsOS (managed link)
That marker defines what the automation owns:
- Applications that have a provider (OIDC or LDAP) are never modified or pruned. When a service later gains single sign-on, its own OIDC reconciliation takes over the application and the link automation leaves it alone.
- Providerless applications without the exact marker are treated as hand-made and are never modified or pruned.
- Marked providerless cards are removed once their service is disabled.
Authentik applications have no generic attributes field, which is why the
marker lives in meta_publisher.
Most roles are discovered through roles/<service>/service.yml. A role whose
metadata lives elsewhere — such as the docs site, deployed by
roles/homelabos_docs — declares a dashboard.yml descriptor beside its tasks
instead:
---
service_name: docs
full_service_name: HomelabOS Documentation
description: Documentation for enabled HomelabOS services.
port: 80
Two metadata files resolving to the same service key fail the deploy closed and name both paths, rather than one silently overriding the other.
Access¶
It is available at https://authentik.demo.ops.ag/ or http://authentik.demo.ops.ag/
Security enable/disable https_only and auth¶
To enable https_only or auth set the service config to True
settings/config.yml
authentik:
https_only: True
auth: True
Traefik integration¶
Authentik can protect other HomelabOS services via Traefik forward auth. See the Authentik Traefik docs after creating a proxy provider and outpost in the Authentik admin UI.