Keycloak

Overview

Keycloak is the identity provider for every service. It runs on the server against the host PostgreSQL and keeps no local state.

Property Value
Public endpoints https://id.yhkze.net (login, registration, OIDC), /admin refused
Account page https://id.yhkze.net redirects to /realms/internal/account/ (password, TOTP, sessions)
Admin console https://id-admin.yhkze.net, WireGuard peers only
Module modules/features/keycloak.nix
Configuration tofu/keycloak/ (OpenTofu)
Forward auth modules/features/oauth2-proxy.nix, https://sso.yhkze.net

Two realms separate operators from the public:

Realm Members Registration Second factor
internal Operators, friends, service accounts Off, accounts are created by an admin TOTP on step-up, reference Two-Tier Login
public Users of product applications Open, account active after email verification Optional
master Keycloak administrators only Off TOTP

A user of public does not exist in internal, so no self-registered account can reach an infra client. Operators sign in to public applications with their internal account through the “yhkze account” button, which brokers to the internal realm.

flowchart LR
    subgraph keycloak["Keycloak (id.yhkze.net)"]
        internal["realm internal"]
        public["realm public"]
        public -- "identity provider: internal" --> internal
    end
    internal --> clients["Forgejo · OpenCloud · OpenBao<br/>Argo CD · Kargo · Open WebUI"]
    internal --> o2p["oauth2-proxy (sso.yhkze.net)"]
    o2p --> fwd["Routes with sso@file<br/>(yhkze.net/usfqk8s, /usfqsrv)"]
    public --> apps["Product applications"]

Clients

Every client lives in the internal realm. Group names reach clients as a flat list in the groups claim of the ID token, access token and userinfo response.

Client Type Groups used
forgejo Confidential forgejo (required to sign in), forgejo_admin
opencloud Public opencloud_admin, opencloud_readwrite, opencloud_service_group, opencloud_readonly
openbao Confidential openbao_admin, openbao_readonly (external group aliases)
argocd Public, PKCE argocd_admin, k8s_<project>_{maintainer,viewer}
kargo Public, PKCE kargo_admin, k8s_<project>_{maintainer,viewer}
open-webui Confidential open_webui (required to sign in), open_webui_admin
oauth2-proxy Confidential, PKCE none
public-broker Confidential none, used by the public realm’s identity provider

Group names are matched verbatim by the charts and apps repos (Argo CD policy.csv, Kargo values, apps/promotion/<project>.yaml), by OpenBao group aliases and by the modules above. A rename has to land in all of them.

The public realm holds the clients of product applications:

Client Type Notes
rgxr Public, PKCE Sign-in and sign-up from the browser; audience mapper puts rgxr in the access token, which the rgxr API verifies

Confidential client secrets are the SOPS values forgejo/oidc-client-secret, openbao/oidc-client-secret, open-webui/oidc-client-secret, oauth2-proxy/client-secret and keycloak/public-broker-secret.

Configuration with OpenTofu

Realms, clients, groups, scopes and the identity provider are declared in tofu/keycloak/. Users are data, not configuration, and never appear there.

The state holds every client secret, so it is committed encrypted with a passphrase from SOPS (keycloak/tofu-state-passphrase). OpenTofu authenticates as the master-realm client tofu.

scripts/keycloak-tofu.nu decrypts every input from SOPS into the process environment and runs tofu against the admin hostname, so it needs WireGuard. Review a change, then apply it:

nix develop path:.#keycloak --command nu scripts/keycloak-tofu.nu plan
nix develop path:.#keycloak --command nu scripts/keycloak-tofu.nu apply

Commit tofu/keycloak/terraform.tfstate after every apply.

Two-Tier Login

The internal realm’s browser flow, browser-step-up (tofu/keycloak/internal.tf), has two levels of authentication. TOTP belongs to the account, not to a client: one credential answers every level-2 prompt.

flowchart TD
    A[login] --> B{SSO session at the requested level?}
    B -->|yes| Z[signed in]
    B -->|no| C[level 1: password]
    C --> D{role otp_required?}
    D -->|yes| E[TOTP]
    D -->|no| F{client minimum ACR 2?}
    E --> F
    F -->|yes| G[level 2: TOTP]
    F -->|no| Z
    G --> Z
Level Asks for Lasts Applies to
1 Password SSO session (10 h) Every client by default
2 TOTP That login only Clients in local.step_up_clients (openbao)

Per client — a client listed in local.step_up_clients gets minimum.acr.value = 2, so its logins reach level 2 even inside a password-only SSO session. A per-client flow override would not: the session cookie satisfies it before any second factor runs.

Per group — groups granted the realm role otp_required (keycloak_group_roles.internal_otp_required, currently forgejo_admin) answer TOTP on every new session, whatever the client.

Users without TOTP enroll inline the first time either rule applies. Configure OTP is not a default required action, and removing a pending one from a user (Users → Required user actions) is the only per-user cleanup; both the flow and the rules above are tofu-owned, so change them in code.

Users

Adding an internal user — in the admin console, realm internal → Users → Add user with username, email and name, join the groups the person needs, then Credentials → Credential reset → Update Password. The person receives an email with a link valid for 12 hours. TOTP is enrolled later, the first time a login needs it.

Account roles — the account page needs default-roles-internal, which users created in the admin console get automatically. Users loaded through Partial import do not; grant the role under Users → Role mapping.

Public users register themselves on any application’s sign-in page and activate the account from the verification email.

Emails leave through the server’s mail server as [email protected] (SOPS smtp/users/srv).

Forward Auth

Routes whose backend has no login of its own add the sso@file Traefik middleware. oauth2-proxy answers it: a signed-in request passes, a signed-out one goes to the internal realm’s login and comes back with a session cookie valid on every yhkze.net host. Any internal user may pass.

For a route declared through Docker labels:

traefik.http.routers.<name>.middlewares: "sso@file"

Theme

Every realm uses the yhkze theme (resources/keycloak-theme/), set as the server default with spi-theme--default in modules/features/keycloak.nix. Only the login pages are restyled, as a riso-printed zine page: cream paper, black ink and one accent ink, the wallpaper printed as a three-tone plate in a ruled panel, the scene’s name in vertical kanji beside the form. The other theme types (account console, admin console, email, welcome page) inherit Keycloak’s stock themes unchanged; they exist only because the server default applies to every type.

The login theme extends base, Keycloak’s unstyled templates: login/theme.properties maps the templates’ class hooks to the classes in login/resources/css/yhkze.css, so the HTML still comes from Keycloak and new pages or fields after an upgrade are styled automatically.

Wallpapers — login/resources/js/wallpaper.js picks one per browser session, so a sign-in flow keeps its scene from page to page; portrait photos join the pool only on portrait screens. The build in keycloak.nix derives everything else from resources/keycloak-theme/wallpapers/:

Adding a wallpaper takes a JPEG in that directory and an entry in wallpapers.toml:

[[wallpaper]]
name = "kyoto"          # file name without .jpg
kanji = "京都"          # set beside the form
orientation = "landscape"
# accent = "#e9b3c2"    # only where the derived colour misses the scene

Keycloak caches themes, so a change takes effect after the deploy restarts it.

Administration

The master realm holds the administrator account keycloak_admin. Its first password is SOPS keycloak/admin-password; the first login forces a new password and TOTP enrolment. Read it with:

sops decrypt --extract '["keycloak"]["admin-password"]' hosts/server/secrets/secrets.yaml

Lost admin access — Keycloak can create a temporary admin service account against the existing database; reference https://www.keycloak.org/server/bootstrap-admin-recovery. SOPS keycloak/bootstrap-client-secret is reserved as its secret, and scripts/keycloak-tofu.nu --bootstrap authenticates OpenTofu with a client named bootstrap.

Health — curl 127.0.0.1:8181/health/ready on the server.