Skip to content
SHC Docs

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.

vars.yaml
keycloak:
displayName: "Keycloak"
app.yaml
keycloak:
displayName@string: Name of the SSO provider shown on the login page (default Keycloak); the catalogue-wide name for this knob

The render site composes whatever shape the upstream field wants:

upstream field wantsrender
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. 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 / sourceName collide with the load-bearing identifier fields sitting right next to them: Frappe autonames its Social Login Key row frappe.scrub(provider_name), Superset keys OAUTH_PROVIDERS on name, allauth keys on provider_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.
  • buttonLabel was proposed for librechat in the 2026-07-14 vars audit; it has the same surface-naming and caption-shape problems as buttonText.
  • displayName is protocol-neutral (it reads correctly under saml: as well as keycloak:), 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).

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.

Two apps had already shipped a differently named var for this knob, declared in app.yaml, so an operator could have set either:

appold varnew var
immichkeycloak.buttonText (a whole caption)keycloak.displayName (the noun)
sonarqubesaml.providerNamesaml.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 Keycloak to the noun Keycloak and the plug composes Login with in front of it; SonarQube’s default was already the bare noun Keycloak. 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 from vars.yaml and 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 in legacy-and-breaking.md §1a so it is not discovered on a login page.
  • ciso-assistant, frappe, superset, wordpress, netbird, nextcloud carry provider_name / name / provider_id literals that are IDENTIFIERS, not labels. They are deliberately left hardcoded; see the per-app comments.