The SSO display-name var
Canonical name: keycloak.displayName (OIDC) / saml.displayName (SAML).
Canonical value: the provider NOUN. Keycloak, Acme SSO, Corp Login,
never a whole caption like Login with Keycloak.
Every app in the catalogue that renders the identity provider’s name on its login page spells that knob the same way. This page is why, and what to do when an app does not fit.
The rule
Section titled “The rule”keycloak: displayName: "Keycloak" keycloak: displayName@string: Name of the SSO provider shown on the login page (default Keycloak); the catalogue-wide name for this knobThe render site composes whatever shape the upstream field wants:
| upstream field wants | render |
|---|---|
a bare label (GitLab label, Postiz ..._DISPLAY_NAME, allauth name, Windmill display_name, SonarQube providerName, OpenReplay OIDC_PROVIDER_NAME, huly OPENID_DISPLAY_NAME) | {{ vars.oidc.displayName | default('Keycloak') }} |
a whole button caption (Immich buttonText, Dependency-Track OIDC_LOGIN_BUTTON_TEXT, DefectDojo ..._LOGIN_BUTTON_TEXT, LibreChat OPENID_BUTTON_LABEL) | Login with {{ vars.oidc.displayName | default('Keycloak') }} |
Why a noun, and why displayName
Section titled “Why a noun, and why displayName”Why a noun. Half the upstream fields are bare labels and half are whole
captions. A noun composes into both; a caption composes into neither. Storing
Login with Keycloak and feeding it to allauth’s name produces
“Sign in with Login with Keycloak”. There is no direction in which a caption
decomposes back into a noun, so the noun is the only value that can be the
single source.
Why displayName over the alternatives that were in the tree:
buttonText(immich) names a surface, not a thing, and half the surfaces are not buttons: Gitea’s is a source list, Superset’s is a provider dropdown, allauth also prints it on the account-connections page. It is also inherently caption-shaped.providerName/sourceNamecollide with the load-bearing identifier fields sitting right next to them: Frappe autonames its Social Login Key rowfrappe.scrub(provider_name), Superset keysOAUTH_PROVIDERSonname, allauth keys onprovider_id, Gitea builds its callback path from the source name. Giving the cosmetic knob one of those names invites an operator to change a label and move a callback URL.buttonLabelwas proposed for librechat in the 2026-07-14 vars audit; it has the same surface-naming and caption-shape problems asbuttonText.displayNameis protocol-neutral (it reads correctly undersaml:as well askeycloak:), is the term OIDC/SAML metadata itself uses for a human-readable provider name, and was already the plurality spelling in the tree (huly, openreplay).
Exceptions
Section titled “Exceptions”gitea: keycloak.sourceName, and it stays. Gitea derives the OAuth2
callback path from the login source’s name (/user/oauth2/<name>/callback) and
has no separate display field. The var is an identifier that is also
displayed. Renaming it moves the redirect URI and invalidates outstanding
sessions, so it must remain a deliberate decision distinct from relabelling a
button. gitea therefore carries no displayName.
The same fact is why gitea’s oidc.plug.yaml interpolates sourceName
into redirectUris rather than hardcoding keycloak there. The literal was a
live defect: any operator who set keycloak.sourceName to another value minted
a Keycloak client whose redirect_uri no longer matched the path gitea
actually calls back on, and every login died on invalid_redirect_uri. The
interpolation renders byte-identical while sourceName holds its default.
librechat: default is SSO, not Keycloak. The app shipped
OPENID_BUTTON_LABEL: "Login with SSO" hardcoded. Standardising the var name
must not silently relabel every existing install’s button, so librechat’s
per-app default is SSO and it still renders Login with SSO. Changing the
text is an operator’s --var away.
The two renames: clean break, no aliases
Section titled “The two renames: clean break, no aliases”Two apps had already shipped a differently named var for this knob, declared
in app.yaml, so an operator could have set either:
| app | old var | new var |
|---|---|---|
| immich | keycloak.buttonText (a whole caption) | keycloak.displayName (the noun) |
| sonarqube | saml.providerName | saml.displayName |
Both are renamed outright. No alias is kept and no deprecated key is left
declared, per the repo’s standing doctrine; see
Legacy and breaking changes, whose rule is that a
one-way conversion of old data is fine but code that keeps accepting or
reading the old shape indefinitely is not. A DEPRECATED twin declared beside
the canonical key is exactly that shape.
What this costs, precisely:
- A fresh install renders the same text it rendered before. Immich’s
default moves from the caption
Login with Keycloakto the nounKeycloakand the plug composesLogin within front of it; SonarQube’s default was already the bare nounKeycloak. Both outputs are byte-identical. - An existing install that never touched the old key also renders
identically. Its persisted
modules.<app>.vars.<old key>row (the HUD install form prefills every field fromvars.yamland submits it as an explicit override,modules/hud/install_flow.go) is simply orphaned: nothing reads it, and the new key’s default produces the same string. - An existing install that CUSTOMISED the old key loses that customisation
on the next render, because nothing maps the old row to the new key. That
operator re-sets it once with
shc config set modules.immich.vars.oidc.displayName '<noun>'(note: the noun now, not the whole caption) or the SonarQube equivalent. This is the whole cost of the rename and it is stated inlegacy-and-breaking.md§1a so it is not discovered on a login page.
Known gaps (not closed by this pass)
Section titled “Known gaps (not closed by this pass)”- ciso-assistant, frappe, superset, wordpress, netbird,
nextcloud carry
provider_name/name/provider_idliterals that are IDENTIFIERS, not labels. They are deliberately left hardcoded; see the per-app comments.