Skip to content
SHC Docs

Avatars: libravatar, the OIDC picture claim, and why ivatar stays a tenant app

Status: proposed. The mapper is unbuilt; everything else is measurement. Date: 2026-08-07

Two delivery routes, and consumers never learn which one they got:

  • Route B: the picture claim. Keycloak computes the digest and mints a ready-made URL. The app reads a standard OIDC claim and knows nothing about libravatar. Preferred.
  • Route A: direct libravatar. The app hashes the email itself and fetches /avatar/<digest>. Needed only where the app will never read picture.

apps/ivatar stays an ordinary per-tenant catalog app. Not a built-in, not a module, not embedded in Keycloak. The reasons are structural and are recorded below because each one was reached by eliminating an alternative.

approutestate
gitlabA✅ already wired: printf templates, SHA256, d=identicon. Permanent route-A resident: its own compose comment records that GitLab never maps the picture claim (omniauth builds name/username/email only; avatar sync is LDAP-exclusive)
giteaBUPDATE_AVATAR: "true" is already set, so it consumes the claim as soon as one exists. This replaces the direct plug; do not do both
nextcloudBone setting: occ user_oidc:provider <id> --mapping-avatar=picture. user_oidc fetches the URL server-side into its own store. Default claim name is avatar, so a mismatch is silent
frappeBneeds a frappe_libravatar app, baked into the SHC-built image. v15 removed the gravatar fallback entirely; get_gravatar_url() is a deprecated stub returning ""
hulyBhardcodes the Gravatar URL into the front bundle; needs a derived image with runtime substitution. MD5 is forced: buildGravatarId stores the 32-hex digest on the person document, so moving to SHA256 later strands every existing avatar
wordpressA~12-line mu-plugin if wanted; no image build
matomo, defectdojo, dependency-tracknoneno avatar concept at all
  • One mapper, N consumers. Route A is per-app config, each with its own traps; gitea alone has three, all measured: GRAVATAR_SOURCE is inert because the compiled default is DISABLE_GRAVATAR=true; it logs a deprecation error claiming the setting will not apply which is false at that pin; and the two federation modes disagree on digest (MD5 vs SHA-256) silently, because the vendored library switched while upstream master did not.
  • Consumers never learn ivatar exists. They see a URL in a claim. The store can be moved (Keycloak-native, another server, anything), and nothing downstream notices.
  • It is where the ecosystem went. Nextcloud’s only gravatar app has been archived since 2018 while user_oidc grew first-class avatar mapping. Route A fights deprecations that keep tightening.
  • No app computes an email hash. That is the mechanic that made the original pattern a privacy problem, and it disappears.

Why not a built-in, a module, or embedded in Keycloak

Section titled “Why not a built-in, a module, or embedded in Keycloak”

Each was considered and eliminated for a different reason. Recording all three so they are not re-proposed.

Not a built-in: it is per-tenant, and built-ins are per-estate. This is structural, not a preference. Realms are already the tenant unit (keycloak/realm vapp instances), so avatars belong at realm granularity. A plug on the Keycloak stack would give every realm the same avatar server.

Not co-located with Keycloak: apps/ivatar is architectures: [amd64]. Upstream publishes an amd64-only manifest; its psycopg2-binary and Pillow wheels carry bundled shared libraries qemu-user cannot mmap, so arm64 crashes at Django import. Bundling would drag Keycloak to amd64-only on every estate. Trading the IdP’s architecture portability for avatars is a bad deal at any price.

Not reimplemented inside Keycloak: the cost is all in the upload UI. Serving is small (a RealmResourceProvider), storage is small, and with federation off the protocol is trivial: GET /avatar/<hex>?s=&d= returns bytes or a generated fallback. But a user-facing upload flow means extending the account console (React/keycloakify), and ivatar already ships one. It would also put user-uploaded blobs in the identity database.

Parked, not dead: a JVM reimplementation is the only path that gives arm64 estates avatars at all. See the gap below.

ivatar can only trust one OIDC issuer. config_local.py reads a single IVATAR_OIDC_ISSUER into one SOCIAL_AUTH_OIDC_OIDC_ENDPOINT, with one client id and secret. There is no tenant or organisation concept anywhere in its config.

Note precisely what is single-tenant: the login, not the storage. Digests are of the full email, so [email protected] and [email protected] never collide; one ivatar could physically hold every tenant’s photos. But tenant B’s users cannot log in to tenant A’s ivatar to manage their own. Storage would have federated; identity does not.

What would change this: multi-issuer support upstream, accepting N OIDC providers and scoping users to the issuer they authenticated against. That is a feature request, not a packaging decision, and it is the only thing standing between the estate and one shared instance.

Built-ins already consume sockets (keycloak ships postgres.plug.yaml and smtp.plug.yaml; traefik ships sso.plug.yaml), so this needs no new machinery, but the plug must attach at realm granularity, not to the Keycloak stack.

Both directions coexist without a cycle, because they resolve at different times:

ivatar --(oidc.plug)-------> keycloak ivatar gets its own login
keycloak --(libravatar.plug)-> ivatar keycloak gets the avatar base URL

Order: install Keycloak → install ivatar with -i oidc=<keycloak> → integrate the realm with -i libravatar=<ivatar>. The second step is the per-tenant opt-in, declared in Terraform.

The mapper itself is minted by create-oidc-client, which already mints shc-groups per client with reconcile-not-skip semantics and 409 tolerance (ce/builtin/keycloak/sso.socket.yaml). Copy that exactly.

Integrations are unique on (tenant_name, consumer_deployment_id, consumer_plug_name), so a consumer holds exactly one libravatar plug. Deploying several ivatars creates no ambiguity: being the avatar source requires someone to point at you, and that pointing is the integration. Re-integrating with a different stack swaps it.

Rejected: register many, pick the first, fall back on miss. “First” is not expressible declaratively; insertion order would make identical Terraform yield different avatar servers on different estates. And a silent fallback is actively harmful here: showing tenant A’s avatars when B was selected renders wrong faces that look completely correct, and nobody reports a face that displays. No fallback degrades to local identicons, which is indistinguishable from “no photo uploaded”, the same benign state as an unconfigured estate.

Accepted: a libravatarBaseUrl var on the realm that wins over the resolved integration. Declarative, Terraform-manageable, survives rebuilds.

Rejected: choosing the server in the Keycloak console. That is runtime UI state, not in the deployment spec, not Terraform-managed, lost on realm rebuild, and it is the admin click-ops the zero-touch bar forbids. The per-user override is different: the picture attribute is genuinely per-user data with no declarative home, and the console is the right place for it.

  • LibravatarPictureMapper in the SPI jar SHC already builds: computes the URL from the email, automatic, no per-user data. Ships on every estate and stays inert without a base URL.
  • picture user attribute declared in Realm Settings → User Profile: Keycloak renders it in its own admin and account consoles (which a protocol mapper does not affect, since those read the attribute, not the claim), and it doubles as a per-user override.
  • Hash the email lowercased and trimmed, per spec. Skipping it yields blanks with no error.
  • Emit ?d=identicon. A bare URL or d=404 returns text/html on a miss, which Nextcloud’s Content-Type whitelist silently discards.
  • ivatar must be un-gated and publicly addressed. It declares no access: today and ships blank baseUrl/secureBaseUrl. Behind forward-auth, <img> fetches bounce to a login page; with no public host the socket falls back to an internal alias no browser can resolve.
  • X200969INTDRP is a soft warning. A persisted integration edge that stops resolving is dropped from the deploy with a warning, not a failure. Uninstall the ivatar a realm points at and avatars quietly stop.
  • Name the plug explicitly: -i libravatar=<stack>. With postgres, smtp and libravatar plugs declared, the bare form hits X400973INTPLG.

Every failure mode in this document is a blank avatar, which is indistinguishable from “nobody uploaded one.” Nothing here fails loudly. That is the argument for asserting the wiring in tests rather than trusting a warning to be noticed.

arm64 estates cannot have the store. ivatar is amd64-only, so the mapper activates but has nothing to point at. Closing it means either upstream shipping arm64 wheels, or the JVM reimplementation parked above.