2026-08-25 · run 2026-08-25-s15-unmanaged-attributes

S15: upgrading does not hide custom attributes; *re-creating the realm* discards them

Summary

S15's hypothesis was wrong, and the truth is worse.

The hypothesis: upgrading across 23 → 24, where the declarative user profile became the default, makes existing custom attributes invisible to the admin API — a data-visibility regression triggered purely by upgrading.

It does not. A realm created on 23.0.7 with users carrying department and employeeId shows those attributes through the admin API on 23.0.7, on 24.0.5 and on 26.7.1, unchanged at every hop. An in-place upgrade preserves them, because the migration sets that realm's unmanagedAttributePolicy to ENABLED.

What actually loses attributes is creating a realm on 24+. Such a realm has no unmanagedAttributePolicy, and then the admin API:

• silently discards custom attributes on write — HTTP 201, and zero rows reach the database; and
• hides any that reach the database by another route — 2 rows present, attributes: null returned.

So the danger is not the upgrade. It is a realm created on a new version.

⚠ CORRECTED 2026-08-26. This paragraph originally read "every path that produces a new realm on a new version: export/import migration, a rebuilt environment, disaster recovery, or simply a realm created after the upgrade." That generalisation is wrong. Run C exported a 23.0.7 realm and imported it into 24.0.5, 25.0.6, 26.0.0 and 26.7.1: all six USER_ATTRIBUTE rows survive, the admin API returns them, and the realm still accepts new ones — because the import sets unmanagedAttributePolicy=ENABLED, exactly as the in-place migration does. See 2026-08-26-runC-realm-export-import-23-to-24.

The path measured below — a realm created through the admin API — is the one that loses attributes. The measurements in this record stand; the inference from them to a class of untested paths did not.

Environment

Results

The upgrade path: no regression at any hop

Users created on 23.0.7 with attributes: {department, employeeId}:

Migration timings: 23.0.7 → 24.0.5 in 18s, 24.0.5 → 26.7.1 in 17s.

Two controls ruled out the other candidate explanations. Users inserted by direct SQL — the way seed-sql.sh does it, with long_value_hash left NULL — returned their attributes through the admin API on 26.7.1 just as admin-API-created users did, both before and after a restart. The seeding method is not the variable, and neither is the hash column.

The realm's birth version is the variable

On the same 26.7.1 server, side by side:

The user creation succeeded. It returned 201. The attributes were simply not persisted, and nothing said so.

The policy governs both sides, independently

Toggling unmanagedAttributePolicy on born26 and re-testing:

The last row is the S15 scenario as originally described: the data is present and invisible. The middle row shows the fix. And the first row shows the part nobody warns about — with the policy unset, the write is a no-op that reports success.

Setting the policy to ENABLED does not recover attributes that were discarded earlier. There is nothing to recover.

Verification

Publishable extract

Upgrading Keycloak does not hide your custom user attributes. Rebuilding the realm deletes them, and tells you it worked.

Keycloak 24 made the declarative user profile the default, and the widely repeated warning is that custom attributes go invisible when you cross that boundary. We tested it: a realm created on 23.0.7 with users carrying department and employeeId, upgraded in place to 24.0.5 and on to 26.7.1. The attributes were returned by the admin API at every hop, unchanged. The in-place upgrade sets that realm's unmanagedAttributePolicy to ENABLED, and everything keeps working.

Then we created a new realm on 26.7.1 and posted the identical user:

POST /admin/realms/born26/users   →  HTTP 201
select count(*) from user_attribute where user_id = ...  →  0
GET  /admin/realms/born26/users?username=...   →  "attributes": null

The request succeeded. The attributes were never written. Nothing warned us. A realm created on 24 or later has no unmanagedAttributePolicy, and with it unset the admin API accepts custom attributes and drops them on the floor.

The same policy hides rows that got there another way. We inserted attributes straight into Postgres, confirmed two rows, and the admin API still answered attributes: null. Turning the policy on makes both problems go away — but it does not bring back what was discarded, because that was never stored.

So the risk is not the upgrade. It is every path that produces a new realm on a new version: export-and-reimport migrations, environment rebuilds, disaster recovery, and any realm created after the upgrade. Those are precisely the paths people take because they consider them safer than an in-place upgrade.

One query tells you which kind of realm you have:

GET /admin/realms/{realm}/users/profile   →   .unmanagedAttributePolicy

If it is absent, your custom attributes are not being stored.

We nearly published the opposite of this. Our own large test realms were built on 26.0.0 and showed exactly the attributes: null symptom the folklore predicts — and we had written it down as an upgrade regression before checking where the realm came from.