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"]
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.
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 applyCommit tofu/keycloak/terraform.tfstate after every
apply.
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.
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).
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"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/:
scripts/keycloak-theme-palette.nu writes
palette.css: each photo’s accent, a pastel of its most
characterful colour that black text reads on at 7:1, plus its
kanjiAdding 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 sceneKeycloak caches themes, so a change takes effect after the deploy restarts it.
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.yamlLost 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.