Authentik¶

Authentik is the cluster's identity provider. Every platform UI sits behind one login instead of a chart-default password each — and Hubble UI, which ships no authentication at all, would otherwise publish every network flow in the cluster to anyone who could reach the hostname.

At a glance¶

Configuration¶

Two integration styles¶

OIDC, for applications that can do it themselves: ArgoCD and Grafana map group membership to a role. Proxy, for the rest: the hostname resolves to Authentik's embedded outpost, a reverse proxy that authenticates the request and only then forwards it to the backend. It needs nothing from the application and protects exactly as far as nothing else can reach the backend.

flowchart LR
    U([Browser]) --> GW[infra-gateway / apps-gateway]
    GW -->|argo, monitoring, OIDC workloads| APP[ArgoCD / Grafana / OIDC workloads]
    APP -.->|OIDC redirect to auth.k8s.wlkr.ch| AK[Authentik]
    GW -->|hubble, rook, prometheus, alertmanager, home, flowscape, analytics, extractor-admin| AK
    AK -->|authenticated| BE[Hubble UI / Ceph dashboard / ...]

One hostname¶

Authentik answers on auth.k8s.wlkr.ch only, on apps-gateway, which the LAN reaches through the router's local record and the outside through Route53. Every OIDC client and the embedded outpost use that one name.

The outpost is why there is only one. A proxied application's route points at authentik-server, but the login itself is an OAuth dance: the outpost sends the browser to the outpost's authentik_host to authenticate and gets it back on the application's own hostname. With Authentik on two names and authentik_host on the LAN-only one, an application on apps-gateway worked at home and redirected outside users to a name that does not resolve. blueprints.yaml pins authentik_host because the embedded outpost otherwise fills it from web.base_url on first start and never updates it.

Where the proxied routes point¶

A proxied application's route lives with the application: Hubble's in payload/platform/cilium/, Rook's in payload/platform/rook-ceph/, Prometheus's and Alertmanager's in payload/platform/monitoring/, and Home Assistant's, Flowscape's, Umami's, Wollbi-Fescht's, Wollbi Adventsfenster's and the Extractor admin UI's in the workloads repository, each with authentik-server as backendRef. Gateway API forbids a cross-namespace backendRef unless the target namespace grants it, so referencegrant.yaml here allows HTTPRoute objects from exactly those namespaces to that Service only. A proxied workload is therefore two pull requests, by design: a workload cannot take itself out from behind the authentication layer on its own.

Database¶

database.yaml is a CloudNativePG Cluster with replicas, the only one on the cluster that has any. Every login on every platform UI goes through Authentik, so its database must survive a node drain: with one instance a reboot kills the database; with replicas, one takes over within a minute, once enablePDB: false lets the drain evict the primary. The chart's own Postgres subchart is off — both rules are in the contract.

The replicas only survive a node loss while they sit on separate nodes, which the operator's own preferred anti-affinity does not guarantee — hence the topologySpreadConstraints block, under the rule in Replica placement.

Chart values¶

Where a blueprint lives¶

Providers and applications are blueprints, so a rebuild reproduces them. !Find resolves objects Authentik ships, !KeyOf references another entry in the same blueprint, and !Env reads an environment variable, which keeps client secrets out of Git. blueprints_discovery runs on worker startup, hourly and on a file watcher, asynchronously, so anything configuring itself against a provider must tolerate it not existing yet.

One issuer for OpenCloud¶

OpenCloud's web, desktop, iOS and Android clients are four OIDC clients with IDs fixed by the clients, so four providers in Authentik, each under an application of its own. The server and the native clients verify every token against one issuer, and Authentik derives a provider's issuer from its application slug, so the four would disagree. All four therefore use issuer_mode: global, whose issuer is the bare hostname, and the HTTPRoute rewrites /.well-known/openid-configuration on that hostname to the opencloud application's discovery document, which is where OpenCloud and its clients fetch it. The document names the global issuer and the shared endpoints, so it serves the other three providers as well. Nothing else uses the root path: every other provider is found under its slug.

User settings flow¶

Dependency-Track keys its accounts on the preferred_username claim, so a user who could rename themselves could take over another's account. 05-user-settings.yaml therefore gives the default brand its own user settings flow with no username field; a username changes only under Directory → Users. It replaces the brand's flow instead of editing the default one because the default blueprint rewrites its own objects on every upgrade, and because the System → Settings switch default_user_change_username is not a model a blueprint can set.

Authentication flow¶

auth.k8s.wlkr.ch is reachable from the Internet, and the default authentication flow lets a user without a device in on a password alone. 06-authentication.yaml gives the default brand its own flow out of the default identification, password and login stages, with two additions. It is an own flow for the same reason as the user settings flow: the default blueprint rewrites its own objects on every upgrade.

To lift a lockout early, delete the score under Customization → Policies → Reputation scores.

Bootstrap credentials¶

Authentik's built-in bootstrap blueprint creates akadmin from AUTHENTIK_BOOTSTRAP_PASSWORD only while no akadmin exists, and reads nothing from it afterwards. 06-authentication.yaml then sets the account is_active: false: a password-only superuser that never logs in is the one worth guessing, and a disabled one authenticates nowhere. The blueprint touches only is_active, so the password and the authentik Admins membership stay for break-glass.

Break-glass is ak shell from a cluster-admin kubeconfig, which nothing in Authentik can lock out:

kubectl -n authentik exec deploy/authentik-server -c server -- ak shell -c \
  'from authentik.core.models import User; User.objects.filter(username="akadmin").update(is_active=True)'

Then log in with bootstrap-password from OpenBao — see Generated secrets — enrol a second factor like any user, and switch the account off again with the same command and is_active=False: a blueprint is re-applied only when its file changes, so nothing switches it off for you.

A cluster installed before the token was dropped still holds it: delete authentik-bootstrap-token under Directory → Tokens and App passwords, once the worker has restarted without the variable.

Groups and roles¶

Authorisation is group membership. The blueprints create these groups; membership is set by hand under Directory → Groups:

Every infra application carries a policy binding to infra-users, so an account outside it, such as a wollbi editor's, is refused by Authentik before the application sees it. The four role groups have infra-users as their parent, and Authentik counts a child group's members as members of the parent. Grafana only sees the groups a user belongs to directly, and with role_attribute_strict it refuses a login that matches none of its three. ArgoCD's policy.default is empty, so a user in neither ArgoCD group gets no access. The wollbi sites bind wollbi-editors instead. Home Assistant and Umami have no binding: they have logins of their own.

Usage¶

Client secrets¶

The OIDC client IDs and secrets are generated once into OpenBao and read by both sides — Authentik through !Env, ArgoCD and Grafana through their own ExternalSecret — so a rebuilt Authentik gets the same credentials and nothing is copied out of a UI. The PushSecret in secrets.yaml writes kv/authentik/config once — see Generated secrets — with the secret key, the bootstrap password and the ArgoCD and Grafana client pairs; its Password generator's secretKeys is the list of keys. A workload's client credentials go in the workload's own path (Dependency-Track's in kv/dependency-track/config, each read by its own secrets-<workload>.yaml, mounted optional): rewriting kv/authentik/config would rotate the secret key that signs every session and token, and External Secrets fails an ExternalSecret whole when one key is missing, so a shared one would leave a cluster without the workload with no AUTHENTIK_SECRET_KEY either.

The first administrator is created through akadmin, switched on for the occasion as in Bootstrap credentials; the steps are in Quickstart step 12.

Adding an application¶

1. Generate its client credentials into OpenBao with a PushSecret beside the workload's own ExternalSecret, and read them here with an ExternalSecret mounted optional, like secrets-dependency-track.yaml. A public client (PKCE, as OpenCloud's web and native clients) has no credentials: its client IDs are fixed by the client and sit in the blueprint in clear, so this step and step 3 do not apply.
2. Mount the workload's blueprint: in application.yaml, a configMap source named authentik-blueprint-<application> with optional: true under worker.volumes, in the projected.sources of blueprints-workloads.
3. Hand the worker the credentials: in the same file, a secretRef to authentik-secrets-<workload> with optional: true under global.envFrom, and bump homelab.wlkr.ch/secret-generation.
4. Add the provider and application blueprint: an OAuth2 provider with grant_types, or a proxy provider added to the outpost's providers: list.
5. For a proxied application, point its HTTPRoute at authentik-server, add its namespace to referencegrant.yaml, and add a toEndpoints rule for its pods to the authentik-server policy in payload/platform/security/network-policies/authentik.yaml: the outpost dials the backend, and without the rule the login succeeds and the request after it times out.
6. Bind infra-users to an infra application in the blueprint, as an authentik_policies.policybinding with the application as target. An application with no binding is open to every Authentik account.

Adding a user¶

1. Create the account under Directory → Users.
2. Add it to infra-users, or to a role group from Groups and roles, under Directory → Groups. Membership is not blueprinted because that would put a username in the repository, and only a superuser passes the bindings without it.

Health check¶

When every login fails, in this order:

1. Server and worker are Ready and the database is healthy:

   kubectl -n authentik get pods,clusters
   

2. The discovery document names the one hostname as issuer:

   curl -s https://auth.k8s.wlkr.ch/application/o/argocd/.well-known/openid-configuration | jq .issuer
   

3. The embedded outpost is healthy (Outposts in the admin UI, or):

   kubectl -n authentik logs deploy/authentik-server | grep -i outpost | tail
   

4. The worker applied the blueprints — a failed one names its file:

   kubectl -n authentik logs deploy/authentik-worker | grep -i blueprint | tail
   

Pitfalls¶

Recovery¶

When Authentik is down¶

Single sign-on is a single point of failure for logging in at all. The ArgoCD path needs a working kubectl, so keep a kubeconfig off-cluster.

ArgoCD — re-enable the local admin account by merging a pull request that sets admin.enabled in payload/argocd/values.yaml; the argocd Application self-heals, so a kubectl patch on argocd-cm is reverted at the next reconcile. ArgoCD syncs the merge without a login. Then restart the server, which generates argocd-initial-admin-secret, and read the password as in Quickstart. Revert the pull request once Authentik is back.

kubectl -n argocd rollout restart deploy/argocd-server

Grafana — the login form is hidden, not removed: the admin account works through the API, and GF_AUTH_DISABLE_LOGIN_FORM=false brings the form back.

Proxied dashboards have no bypass; port-forward instead:

kubectl -n kube-system port-forward svc/hubble-ui 8080:80
kubectl -n monitoring port-forward svc/kube-prometheus-stack-prometheus 9090:9090

ArgoCD's API key account¶

Disabling the local admin also removes its apiKey capability. If a token is needed, add an account scoped to what the token is for rather than re-enabling admin:

The claude account is one, for the in-cluster agents; see Agent account. The shape:

configs:
  cm:
    accounts.mcp: apiKey
  rbac:
    policy.csv: |
      p, role:mcp, applications, get, */*, allow
      g, mcp, role:mcp