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
The short version
Section titled “The short version”Two delivery routes, and consumers never learn which one they got:
- Route B: the
pictureclaim. 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 readpicture.
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.
Allocation
Section titled “Allocation”| app | route | state |
|---|---|---|
| gitlab | A | ✅ 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) |
| gitea | B | UPDATE_AVATAR: "true" is already set, so it consumes the claim as soon as one exists. This replaces the direct plug; do not do both |
| nextcloud | B | one 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 |
| frappe | B | needs a frappe_libravatar app, baked into the SHC-built image. v15 removed the gravatar fallback entirely; get_gravatar_url() is a deprecated stub returning "" |
| huly | B | hardcodes 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 |
| wordpress | A | ~12-line mu-plugin if wanted; no image build |
| matomo, defectdojo, dependency-track | none | no avatar concept at all |
Why route B is preferred
Section titled “Why route B is preferred”- One mapper, N consumers. Route A is per-app config, each with its own
traps; gitea alone has three, all measured:
GRAVATAR_SOURCEis inert because the compiled default isDISABLE_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_oidcgrew 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.
Why per-tenant is forced
Section titled “Why per-tenant is forced”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.
Wiring
Section titled “Wiring”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 loginkeycloak --(libravatar.plug)-> ivatar keycloak gets the avatar base URLOrder: 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.
Selection is not a registry
Section titled “Selection is not a registry”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.
Both halves, deliberately
Section titled “Both halves, deliberately”LibravatarPictureMapperin 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.pictureuser 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 ord=404returnstext/htmlon 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 blankbaseUrl/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. X200969INTDRPis 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>. Withpostgres,smtpandlibravatarplugs declared, the bare form hitsX400973INTPLG.
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.
Known gap
Section titled “Known gap”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.