authentik and SSO

TOW bundles authentik as an optional identity provider for enterprise sign-in: SSO, MFA, and upstream LDAP, SAML, and OIDC sources. TOW itself always talks plain OIDC to authentik.

The easiest way to enable it is during installation: answer authentik at the sign-in question (or pass --auth authentik) and the installer generates the secrets, enables the Compose profile, writes agreeing values into .env and config/tow.yaml, and runs the one-shot bootstrap job that configures authentik itself. This page explains what that produces and the variations you can choose instead.

The default layout: /authentik/ on your domain

The installer serves authentik under your TOW domain (https://tow.example.com/authentik/), so no extra DNS or certificates are needed. The following moving parts must agree; the installer writes all of them:

File	Setting	Value
.env	COMPOSE_PROFILES	authentik
.env	AUTHENTIK_PUBLIC_URL	https://tow.example.com/authentik
.env	AUTHENTIK_WEB__PATH	/authentik/
.env	AUTHENTIK_PATH_ENABLED	true
config/tow.yaml	auth.mode	oidc
config/tow.yaml	auth.oidc.issuer	https://tow.example.com/authentik/application/o/tow/
config/tow.yaml	auth.oidc.client_id	tow

The one-shot bootstrap job creates the TOW application, OIDC provider, and signing key inside authentik. Run it again whenever you change these values or upgrade authentik:

docker compose --profile authentik run --rm authentik-bootstrap

Sign in to authentik's admin interface at /authentik/ with AUTHENTIK_BOOTSTRAP_EMAIL and AUTHENTIK_BOOTSTRAP_PASSWORD from .env. The first successful OIDC login to TOW becomes the TOW server administrator; later OIDC users need an invite or an already-linked account.

Alternative: authentik on its own subdomain

To serve authentik at https://auth.example.com instead, set in .env:

AUTHENTIK_PUBLIC_URL=https://auth.example.com
AUTHENTIK_WEB__PATH=/
AUTHENTIK_PATH_ENABLED=false

and in config/tow.yaml:

auth:
  mode: oidc
  oidc:
    issuer: https://auth.example.com/application/o/tow/
    client_id: tow

The stack does not expose authentik directly; publish its port through an ignored compose.override.yaml and put your edge proxy in front of it:

compose.override.yaml

services:
  authentik-server:
    ports:
      - "127.0.0.1:9000:9000"

Reconcile with docker compose up -d --wait, re-run the bootstrap job, and add an edge-proxy server block for auth.example.com that forwards to 127.0.0.1:9000 (WebSocket upgrade headers included, as in production hardening).

Public self-service signup

Public signup needs working email delivery, and it needs an enrollment flow inside authentik.

Two switches, two readers

auth.signup.enabled in config/tow.yaml is read by TOW at runtime. SIGNUP_ENABLED in .env is read only by the bootstrap job, which creates or updates the tow-public-enrollment flow. Set both, then re-run the bootstrap. After upgrading an existing authentik deployment, re-run the bootstrap with SIGNUP_ENABLED=true again: the bundled enrollment flow requires separate first and last name fields.

1. In .env: SIGNUP_ENABLED=true

2. In config/tow.yaml:

   auth:
     signup:
       enabled: true
       oidc_start_url: https://tow.example.com/authentik/if/flow/tow-public-enrollment/

3. Apply:

   docker compose --profile authentik run --rm authentik-bootstrap
   docker compose restart backend email-worker

After verification, TOW applies a valid invite first, then joins an organisation with a verified matching email domain, and otherwise creates a new workspace for the user.

Organisation-managed providers (LDAP, SAML, upstream OIDC)

On top of the bundled authentik, organisation admins can connect their own identity sources from Settings → Organisation → Authentication. The installer enables this (auth.organization_auth.enabled: true) and generates the required ORG_AUTH_SECRET_KEY. Domain-based sign-in routing stays disabled until the organisation verifies its domain.

Provider-specific values (Google, Entra, Okta, generic LDAP/SAML/OIDC) are in the provider setup guide.

Operational notes

• Authentik state (its database and volumes) is included automatically in managed backups while the profile is active.
• The bootstrap job is idempotent; re-running it updates the existing application and provider rather than duplicating them.
• Keep AUTHENTIK_BOOTSTRAP_TOKEN and AUTHENTIK_SECRET_KEY stable; they are generated once at install time.
• User deletion for authentik accounts is governed by the privacy settings; see user deactivation and deletion.