Skip to content

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.


Last update: September 23, 2026