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]
    GW -->|argo, monitoring| APP[ArgoCD / Grafana]
    APP -.->|OIDC redirect| AK[Authentik]
    GW -->|hubble, rook, prometheus, alertmanager| AK
    AK -->|authenticated| BE[Hubble UI / Ceph dashboard / ...]

Two hostnames¶

An OIDC client used from outside the local network needs an authorize endpoint that resolves there. Authentik builds every published URL from the request, so each name serves a self-consistent OpenID configuration with no configuration. Proxied applications never redirect to either: their route points at authentik-server, so the whole flow happens on their own hostname.

Where the proxied routes point¶

Hubble's route stays in payload/platform/cilium/, Rook's in payload/platform/rook-ceph/ and Home Assistant'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 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. Prometheus and Alertmanager have no route of their own, so theirs are in httproute.yaml here; the outpost is their only authentication.

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.

Groups and roles¶

Authorisation is group membership. Create these in Authentik and add users:

ArgoCD's policy.default is empty, so a user in neither ArgoCD group gets no access; Grafana falls back to Viewer. Access to a proxied application is bound to the application in Authentik itself.

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. make bao-secrets does this; by hand:

bao kv put kv/authentik/config \
  secret-key="$(openssl rand -base64 60 | tr -d '\n')" \
  postgres-password="$(openssl rand -base64 32 | tr -d '\n')" \
  bootstrap-password="$(openssl rand -base64 24 | tr -d '\n')" \
  bootstrap-token="$(openssl rand -hex 32)" \
  argocd-client-id="$(openssl rand -hex 16)" \
  argocd-client-secret="$(openssl rand -base64 48 | tr -d '\n')" \
  grafana-client-id="$(openssl rand -hex 16)" \
  grafana-client-secret="$(openssl rand -base64 48 | tr -d '\n')"

Then log in at auth.infra.k8s.wlkr.ch as akadmin with bootstrap-password and create the groups above.

Adding an application¶

1. Generate its client credentials into OpenBao and add them to bao-secrets.sh and an ExternalSecret (a workload's own, mounted optional, like secrets-nextcloud.yaml).
2. Bump homelab.wlkr.ch/secret-generation in application.yaml.
3. Add the provider and application blueprint: an OAuth2 provider with grant_types, or a proxy provider added to the outpost's providers: list.
4. For a proxied application, point its HTTPRoute at authentik-server and add its namespace to referencegrant.yaml.
5. Bind the groups or policies that may reach it, in Authentik.

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:

kubectl -n argocd patch cm argocd-cm --type merge \
  -p '{"data":{"admin.enabled":"true"}}'
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:

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