Keycloak User Storage SPI: Writes, Queries, Caching
A read-only User Storage provider is three interfaces. Making it searchable, writable and fresh is three more, and each one has a default implementation that will quietly do the wrong thing if you leave it alone:
UserQueryMethodsProvider— listing and searching. Its one abstract method receives aMap<String, String>of filters, and every key you do not read is a filter you have silently ignored.UserCountMethodsProvider— the user count. Override the wrong overload and Keycloak answersusers/countby streaming your entire user base through the JVM.UserRegistrationProvider—addUserandremoveUser. Once you implement it, the realm's public registration page writes into your external system.
Plus the user cache, which sits above all of them, is the reason a write you make outside Keycloak does not show up, and is configured by five words in a dropdown nobody reads.
Keycloak 26.8.2 (quay.io/keycloak/keycloak:26.8.2, start-dev, H2 dev-file database,
single container), built with Temurin JDK 25 compiling to release 21, Maven 3.9.15. Every
command, log line, call count and timing below is copied from a real run on 2026-11-16
against a 50-user store. The official
Server Developer Guide — User Storage SPI
documents what each interface means; this page is what the server actually does with them.
This continues
Keycloak User Storage SPI: read-only lookup,
which built the legacy-rest provider, its HTTP client and its UserModel adapter. The
code below extends that provider. If you have not read it, start there — the Maven artifact
split alone will cost you an hour.
What part 1 left out, and what each piece costs
| You want | Interface to add | What it costs |
|---|---|---|
| Users listed and searchable in the console | UserQueryMethodsProvider | one store call per page, plus up to one per row |
| A count on the realm page | UserCountMethodsProvider | one call, or a full scan if you miss the overload |
| Create and delete through Keycloak | UserRegistrationProvider | your public registration page now writes to the legacy system |
| Edit profile fields | setters on a writable adapter | no transaction, no rollback |
| Password changes written back | a real CredentialInputUpdater.updateCredential | you own password policy enforcement |
| Control over staleness | cachePolicy on the component | freshness traded against latency, per realm |
UserQueryProvider is the combination of the first two, and implementing it is the same
work. The split exists so a provider can be countable without being searchable.
1. Queries: the params map is the whole interface
UserQueryMethodsProvider has exactly one abstract method:
Stream<UserModel> searchForUserStream(RealmModel realm, Map<String, String> params,
Integer firstResult, Integer maxResults);
Everything else on the interface — the String search overloads, getGroupMembersStream,
getRoleMembersStream — has a default that funnels into it. So that map is the entire
query surface of your provider, and it carries two different kinds of key.
Reserved keys are namespaced and come from UserModel:
| Constant | Literal value |
|---|---|
UserModel.SEARCH | keycloak.session.realm.users.query.search |
UserModel.EXACT | keycloak.session.realm.users.query.exact |
UserModel.INCLUDE_SERVICE_ACCOUNT | keycloak.session.realm.users.query.include_service_account |
UserModel.GROUPS | keycloak.session.realm.users.query.groups |
UserModel.IDP_ALIAS, IDP_USER_ID | …query.idp_alias, …query.idp_user_id |
UserModel.CREATED_AFTER, CREATED_BEFORE | …query.created_after, …query.created_before |
Unreserved keys are plain: username, email, firstName, lastName — and
anything else is a user attribute the caller is filtering on. That last sentence is the
part the guide does not say, and its own example ends at
String usernameSearchString = params.get("username");.
Here is what that costs. The admin API's attribute filter is ?q=key:value, and against a
provider that reads only username:
kcadm.sh get users -r legacy-demo -q 'q=dept:research' --fields username
[ { "username" : "ada" }, { "username" : "alan" }, { "username" : "grace" },
{ "username" : "linus" }, { "username" : "user01" }, … 50 rows … ]
Two users have dept=research. The console shows all fifty, with no error anywhere, because
the filter was handed to the provider as params["dept"] = "research" and dropped on the
floor. An ignored filter is not a slow filter; it is a wrong answer.
The rule that makes this safe is short: read the keys you understand, and treat every key you do not as a filter you must still apply.
private static final String QUERY_PREFIX = "keycloak.session.realm.users.query.";
private static final Set<String> PROFILE_KEYS =
Set.of(UserModel.USERNAME, UserModel.EMAIL, UserModel.FIRST_NAME, UserModel.LAST_NAME);
@Override
public Stream<UserModel> searchForUserStream(RealmModel realm, Map<String, String> params,
Integer firstResult, Integer maxResults) {
int first = firstResult == null ? 0 : firstResult;
int max = maxResults == null ? Integer.MAX_VALUE : maxResults;
boolean exact = Boolean.parseBoolean(params.get(UserModel.EXACT));
// Anything that is not reserved and not a profile field is an attribute filter.
Map<String, String> attributeFilters = new LinkedHashMap<>();
for (Map.Entry<String, String> e : params.entrySet()) {
if (e.getKey().startsWith(QUERY_PREFIX) || PROFILE_KEYS.contains(e.getKey())) {
continue;
}
attributeFilters.put(e.getKey(), e.getValue());
}
String search = params.get(UserModel.SEARCH);
if (search == null) {
search = params.getOrDefault(UserModel.USERNAME,
params.getOrDefault(UserModel.EMAIL,
params.getOrDefault(UserModel.FIRST_NAME, params.get(UserModel.LAST_NAME))));
}
if (search != null) {
search = search.replace("*", "").trim();
}
if (attributeFilters.isEmpty()) {
return client.search(search, first, max).stream().map(u -> adapt(realm, u));
}
// The store has no combined filter endpoint, so narrow on the first attribute and
// apply the rest here. Paging comes after filtering, never before.
Map.Entry<String, String> head = attributeFilters.entrySet().iterator().next();
String needle = search == null ? "" : search.toLowerCase();
return client.searchByAttribute(head.getKey(), head.getValue()).stream()
.filter(u -> attributeFilters.entrySet().stream().allMatch(
f -> u.attributes().getOrDefault(f.getKey(), List.of()).contains(f.getValue())))
.filter(u -> needle.isEmpty() || matches(u, needle, exact))
.skip(first)
.limit(max)
.map(u -> adapt(realm, u));
}
### after: -q 'q=dept:research'
[ { "username" : "ada" }, { "username" : "alan" } ]
### -q 'q=dept:compilers'
[ { "username" : "grace" } ]
Three details decide whether this behaves under load:
maxResultsis nullable, andnullmeans "all of them". Treating it as0returns an empty page; treating it as unbounded is correct and is what the admin API relies on.*is a wildcard the caller may send literally. Strip it before it reaches a store that would match it as a character.- Filter before you page. Narrowing in the store and slicing afterwards is the only order that gives a stable page 2; the reverse silently drops rows.
If your store can express the whole filter, push all of it down. The in-memory filter above
is a stopgap for a store with one attribute index, and it loads the full attribute match set
into the JVM before paging — fine at fifty users, not at five hundred thousand.
2. Counting is not searching, and the overload matters
The guide shows public int getUsersCount(RealmModel realm). Implement exactly that, ask for
a count, and watch your store:
kcadm.sh get users/count -r legacy-demo
### the legacy service's access log, in full:
GET /users?search=&first=0&max=2147483647
50 comes back and it is correct. It was computed by streaming every user out of your
external system, building an adapter for each one, and calling .count(). The chain is all
defaults: the admin endpoint passes a params map, so getUsersCount(RealmModel, Map) is
called, and its default implementation delegates to searchForUserStream(realm, params) —
which itself defaults to the four-argument form with null, null. Hence max=2147483647.
Worse, getUsersCount(RealmModel)'s own default delegates to getUsersCount(RealmModel, boolean), whose default is:
throw new RuntimeException("Not implemented");
So override the map overload — the one the admin API actually reaches — and the others alongside it:
@Override
public int getUsersCount(RealmModel realm) {
return client.count();
}
@Override
public int getUsersCount(RealmModel realm, Map<String, String> params) {
return client.count(); // narrow this if params carry filters you support
}
@Override
public int getUsersCount(RealmModel realm, boolean includeServiceAccount) {
return client.count(); // federated users are never service accounts
}
### after: the access log for the same request
GET /users/count
One call, 0.03 s, against an unbounded scan. If your store cannot count cheaply either, say so with an estimate rather than a scan — a count nobody reads is not worth a full table walk on every realm page load.
3. What a page of users actually costs
Queries are cheap. Turning their results into admin API representations is not. Against the 50-user store, on a cold cache:
| Request | Calls to the store | Time |
|---|---|---|
GET /users?max=50&briefRepresentation=true | 1 | 0.31 s |
GET /users?max=50&briefRepresentation=false | 51 | 3.17 s |
| the same full request, second time | 51 | 2.51 s |
| the same full request, third time | 1 | 0.07 s |
Fifty-one is one query plus one lookup per row, and the extra lookup is not yours. It comes from representation building:
at io.example.keycloak.storage.LegacyRestStorageProvider.getUserById(…)
at org.keycloak.storage.UserStorageManager.getUserById(UserStorageManager.java:582)
at org.keycloak.models.cache.infinispan.UserCacheSession.getUserById(UserCacheSession.java:241)
at org.keycloak.models.cache.infinispan.UserCacheSession.getNotBeforeOfUser(UserCacheSession.java:994)
at org.keycloak.models.utils.ModelToRepresentation.toRepresentation(ModelToRepresentation.java:336)
at org.keycloak.services.resources.admin.UsersResource.lambda$toRepresentation$6(UsersResource.java:589)
A full representation carries notBefore, and reading it resolves each user by id
through the cache. A brief one does not. The same listing is one call or fifty-one
depending on a query parameter the caller chose, and kcadm.sh get users chooses the
expensive one.
Two practical consequences. Make getUserById cheap, because it is called once per row
on a path you did not write. And do not benchmark with kcadm.sh get users: it is the
most expensive shape of the request, not a typical one.
The third row of that table is not a typo. The cache is populated on the first pass — our
onCache callback fired fifty times during it — and the second identical request still
re-read every row before the third was served from memory. Measure your own warm-up rather
than assuming one request primes the cache.
4. Writes need a different adapter
Part 1's adapter extends AbstractUserAdapter, which throws ReadOnlyException from every
setter. For writes, the base class is AbstractUserAdapterFederatedStorage, and the
difference between the two is more than permissions:
AbstractUserAdapter | AbstractUserAdapterFederatedStorage | |
|---|---|---|
| Setters | throw ReadOnlyException | write to Keycloak's federated storage tables |
credentialManager() | you must implement it | implemented for you |
getAttribute(String) | present | absent — it is not on UserModel |
| Roles, groups, required actions | realm defaults only | stored per user, in Keycloak |
That third row bites immediately: part 1's adapter has @Override public List<String> getAttribute(String name), and moving the class to the federated base fails to compile with
method does not override or implement a method from a supertype. getAttribute is declared
on AbstractUserAdapter alone; UserModel has getAttributeStream and getFirstAttribute.
Keep the helper, drop the annotation.
The second row is the one that costs a day. The base class's setters do not write to your
external store. They write to FED_USER_ATTRIBUTE and friends — Keycloak's own tables, for
federated users. If your getters read the external record, as they must, then a profile edit
goes into Keycloak, your getter never looks there, and the edit disappears:
kcadm.sh update users/f:…:grace -r legacy-demo -s lastName=Hopper-EDITED
### no error, no output: HTTP 204
### the legacy store: "lastName": "Hopper"
### Keycloak, read back: "lastName" : "Hopper"
The admin console says User updated. Nothing changed anywhere. There is no log line.
So override every setter whose value your getters read, and push it to the store:
public class LegacyUserAdapter extends AbstractUserAdapterFederatedStorage {
private final LegacyUserClient client;
private LegacyUser user; // replaced by each write's response
public LegacyUserAdapter(KeycloakSession session, RealmModel realm, ComponentModel model,
LegacyUserClient client, LegacyUser user) {
super(session, realm, model);
this.client = client;
this.user = user;
this.storageId = new StorageId(model.getId(), user.username());
}
@Override public String getUsername() { return user.username(); }
@Override public String getEmail() { return user.email(); }
@Override public String getFirstName() { return user.firstName(); }
@Override public String getLastName() { return user.lastName(); }
@Override public boolean isEnabled() { return user.enabled(); }
@Override public boolean isEmailVerified() { return user.emailVerified(); }
// client.patch() PUTs the fragment to /users/{username} and returns the updated record.
@Override public void setEmail(String v) { patch("{\"email\":" + quote(v) + "}"); }
@Override public void setFirstName(String v) { patch("{\"firstName\":" + quote(v) + "}"); }
@Override public void setLastName(String v) { patch("{\"lastName\":" + quote(v) + "}"); }
@Override public void setEnabled(boolean v) { patch("{\"enabled\":" + v + "}"); }
@Override public void setEmailVerified(boolean v) { patch("{\"emailVerified\":" + v + "}"); }
private void patch(String json) {
user = client.patch(user.username(), json);
}
@Override
public void setAttribute(String name, List<String> values) {
switch (name) {
case UserModel.USERNAME -> setUsername(first(values));
case UserModel.EMAIL -> setEmail(first(values));
case UserModel.FIRST_NAME -> setFirstName(first(values));
case UserModel.LAST_NAME -> setLastName(first(values));
default -> patch(attributeJson(name, values));
}
}
@Override
public void setSingleAttribute(String name, String value) {
setAttribute(name, value == null ? List.of() : List.of(value));
}
@Override
public void removeAttribute(String name) {
setAttribute(name, List.of());
}
}
setAttribute has to special-case the four profile fields because Keycloak 26 writes the
whole user profile through attributes: an admin edit to lastName arrives as
setAttribute("lastName", ["…"]), not as setLastName.
What federated storage is genuinely for
The base class is not a trap everywhere. It is the right answer for everything your external store does not model. Roles, groups and required actions on a federated user persist in Keycloak, and the external system never hears about them:
kcadm.sh update users/f:…:grace -r legacy-demo -s 'requiredActions=["UPDATE_PASSWORD"]'
kcadm.sh get users/f:…:grace/groups -r legacy-demo --fields name
{ "username" : "grace", "requiredActions" : [ "UPDATE_PASSWORD" ] }
[ { "name" : "engineers" } ]
### the legacy record, unchanged:
{"username": "grace", "email": "grace@legacy.example", "firstName": "Grace",
"lastName": "Hopper", "enabled": true, "attributes": {"dept": ["compilers"]}}
The line to hold is: federated storage for what your store does not have, write-through for what it does. Mixing them on the same field is what makes an edit vanish.
5. There is no transaction, and there is no rollback
UserModel has one setter per field, so Keycloak creates a user by calling addUser and
then setting fields one at a time. Creating a single user through the admin API:
GET /users?search=edsger%40legacy.example&first=0&max=2 ← duplicate-email check
GET /users/edsger%40legacy.example
GET /users/edsger ← duplicate-username check
POST /users ← addUser
PUT /users/edsger ← email
PUT /users/edsger ← firstName
PUT /users/edsger ← lastName
PUT /users/edsger ← enabled
Eight calls, four of them one field each. Now make the store reject the third PUT:
### admin API:
For more on this error consult the server log. [unknown_error]
### the legacy store:
{"username": "barbara", "enabled": true, "email": "barbara@legacy.example",
"firstName": "Barbara"}
A user that exists, half-populated, with no password and no lastName. Keycloak reported a
failure and rolled back its own side; your store has no idea a transaction was in progress.
Retrying the identical request does not repair it:
User exists with same email
Somebody now cleans that up by hand. Three ways out, in increasing order of effort:
- Make the external write idempotent by username so a retry converges instead of colliding. Cheapest, and it covers most of the damage.
- Buffer in the adapter and flush once. Collect the setters in memory and enlist a
KeycloakTransactionwithsession.getTransactionManager().enlist(...), flushing from itscommit()and discarding onrollback(). One write per user instead of five, and a Keycloak-side failure never reaches your store at all. - Reconcile, if the store cannot offer either. A nightly job that finds users with no
lastNameis not elegant, but it is honest about what the SPI guarantees, which is nothing.
Pick before you ship, not after the first half-written user.
6. Registration goes wherever addUser points
This is the consequence people do not expect. Turn on Realm settings → Login → User registration with a writable provider installed, fill in the public registration form, and:
### the legacy service's access log during one signup
GET /users?search=katherine%40legacy.example&first=0&max=2
GET /users/katherine
POST /users
PUT /users/katherine × 4
PUT /users/katherine/password
GET /users/katherine
{"username": "katherine", "email": "katherine@legacy.example",
"firstName": "Katherine", "lastName": "Johnson", "enabled": true}
The new account and its password are in the legacy system. The subsequent login returns
200. If that legacy system is a database you were planning to decommission, you have just
made it load-bearing for signups.
The opt-out is documented on the interface rather than in the guide, and it is a return value:
All storage providers that implement this interface will be looped through. If this method returns
null, then the next storage provider'saddUser()method will be called. If no storage providers handle the add, then the user will be created in local storage.
So a provider that can search and update but should not own new users returns null:
@Override
public UserModel addUser(RealmModel realm, String username) {
if (!allowRegistration) {
return null; // next provider, then Keycloak's own storage
}
return adapt(realm, client.create(username));
}
kcadm.sh create users -r legacy-demo -s username=margaret -s enabled=true
Created new user with id '738e67b5-2044-4a8d-bbbb-d78c22469fcd'
### a plain UUID, not f:<component>:<id> — and the legacy store returns 404 for margaret
Make it a config property on the factory. "Which system owns new users" is a deployment decision, and it changes during a migration.
removeUser has a matching subtlety in its contract: if you are using the import
strategy, Keycloak removes the imported local user for you and you must not remove it
yourself. Deleting the component is safe either way — removing the federation provider made
zero calls to the external store, and simply took its users out of Keycloak.
7. Passwords, written back
CredentialInputUpdater.updateCredential is where part 1 threw ReadOnlyException. A
writable provider sends it on:
@Override
public boolean updateCredential(RealmModel realm, UserModel user, CredentialInput input) {
if (!supportsCredentialType(input.getType())) {
return false;
}
client.setPassword(user.getUsername(), input.getChallengeResponse());
UserStorageUtil.userCache(session).evict(realm, user);
return true;
}
kcadm.sh set-password -r legacy-demo --username ada --new-password new-engine
PUT /users/ada/password
### direct grant with the new password: 200
### direct grant with the old password: 400 invalid_grant
Two things you now own. Password policy — Keycloak validates against the realm policy
before calling you, but anything your store enforces is yours to report; the open-source
keycloak-user-migration provider
handles the reverse case well, adding UPDATE_PASSWORD when a legacy password fails the new
realm's policy rather than rejecting the login. And hashing: the credential arrives as
plaintext in getChallengeResponse(), so if the external store does not hash it, you must.
8. Caching: what is cached, and how to let go of it
Keycloak caches the user object, never the credential check. The policy lives on the component, and its five values are the whole of your freshness control:
cachePolicy | Behaviour | Extra keys |
|---|---|---|
DEFAULT | cache until something invalidates it | — |
NO_CACHE | every read hits your store | — |
MAX_LIFESPAN | evict a fixed time after caching | maxLifespan, in milliseconds |
EVICT_DAILY | evict at a wall-clock time each day | evictionHour, evictionMinute |
EVICT_WEEKLY | evict at a wall-clock time each week | evictionDay, evictionHour, evictionMinute |
maxLifespan being milliseconds is worth stating because the console labels it in units it
does not use. With maxLifespan=10000 and a change made directly in the external store:
t=0s Lifespan-A (store changed to Lifespan-B at t=1s)
t=4s Lifespan-A
t=8s Lifespan-B
t=12s Lifespan-B
Ten seconds of guaranteed staleness, which is exactly what was asked for.
Writes made through Keycloak do not need any of this — they invalidate as they go. Writes
made outside Keycloak need an eviction, and UserCache is how:
UserStorageUtil.userCache(session).evict(realm, user); // one user
UserStorageUtil.userCache(session).evict(realm); // the whole realm
session.getProvider(UserCache.class) returns the same UserCacheSession object and is what
the guide shows. The form you will find in older code, session.userCache(), no longer
exists on KeycloakSession in 26.8.2 — that is a compile error, not a deprecation. There
is also cacheInvalidBefore on the component, which is what the console's Clear cache
button sets: a timestamp below which every cached entry is treated as stale. Bumping it is
the bulk version of evict(realm).
If you need the external record on the cached object — to avoid re-fetching it on the next
read — OnUserCache is the hook:
@Override
public void onCache(RealmModel realm, CachedUserModel cached, UserModel delegate) {
if (delegate instanceof LegacyUserAdapter adapter) {
cached.getCachedWith().put(LEGACY_SNAPSHOT, adapter.legacyUser());
}
}
getCachedWith() is a map that rides along with the cache entry and is evicted with it. It
fires once per user per cache fill — fifty times for a cold listing of fifty users — so keep
what you put in it small and immutable. It is a cache, not a session.
9. When the store is down, your queries lie
Part 1's rule was that a failed lookup must throw rather than return "no user", because rendering an outage as your account does not exist is worse than an error. That rule holds on the login path. It does not survive the query path, and this is new behaviour worth knowing about.
With the external service stopped, and a client that throws on every failure:
kcadm.sh get users -r legacy-demo -q max=5 --fields username
kcadm.sh get users/count -r legacy-demo
[ ]
0
Both succeeded. The exception is in the log, as a warning:
WARN [org.keycloak.storage.UserStorageManager] User storage provider LegacyRestStorageProvider
failed during query operation. Continuing with other providers for graceful degradation. This
may indicate an issue with external user store connectivity (e.g., LDAP server down).
Keycloak deliberately degrades queries so that one broken federation provider cannot take the admin console down. That is the right call for a realm with several providers, and it means an empty user list is not evidence of an empty store. Meanwhile the same outage on the login path is still loud:
500 unknown_error
Two things follow. Alert on that WARN, because it is the only signal that your console is showing a fiction. And never let a tool that reconciles, exports or bulk-deletes users work from a query result without checking it against the count and the provider's health — "the federation returned zero users" and "there are zero users" are the same JSON.
When you should not implement any of this
The most-deployed user storage provider in this ecosystem implements none of it.
keycloak-user-migration — the
just-in-time migration provider, which we ship on every cluster —
has no UserQueryMethodsProvider, no UserRegistrationProvider and no writable adapter. Its
getUserByUsername does something else entirely:
UserModel userModel = session.users().addUser(realm, legacyUser.getUsername());
userModel.setFederationLink(model.getId());
userModel.setEmail(legacyUser.getEmail());
// … roles, groups, required actions, TOTP credentials
It writes the user into Keycloak on first login, and on the first successful password check it moves the credential across and severs the federation link. After that the user is a normal local user: searchable, writable, cacheable, with none of the code on this page.
That is the import strategy, and it is a different answer to the same question. Federation
keeps the external store authoritative forever and makes every one of the problems above
yours. Import makes Keycloak authoritative and leaves you with a finite migration instead.
Keycloak slow migration vs fast migration is the
decision; make it before you write a UserQueryMethodsProvider, because the correct amount
of this code for a migration is usually none.
And if the external store is LDAP or Active Directory, all of this already exists: Keycloak's own LDAP provider implements the same interfaces, with write-back, mappers and a sync job you would otherwise be building.
When it goes wrong
An admin edit reports success and changes nothing. A setter you did not override went to federated storage while your getter read the external record. Section 4.
A filtered list returns everyone. An unreserved params key — an attribute filter — was ignored. Section 1.
The realm page is slow and your store's logs show a full scan. getUsersCount(RealmModel, Map) is not overridden. Section 2.
Listing users is slow but searching is fast. Full representations resolve each row by id.
Compare with briefRepresentation=true before blaming the query. Section 3.
method does not override or implement a method from a supertype on getAttribute.
AbstractUserAdapterFederatedStorage does not declare it; AbstractUserAdapter does.
New signups appear in the legacy database. The registration page uses
UserRegistrationProvider. Return null from addUser to send them to Keycloak instead.
Section 6.
A user exists in the external store but Keycloak refuses to create them. A previous create failed partway and left a record behind. Section 5.
The console shows zero users and no error. Query degradation during an outage. Check the
UserStorageManager warning. Section 9.
Next steps
- Keycloak User Storage SPI: read-only lookup — the provider this page extends, and the Maven artifact split.
- Your first Keycloak SPI: build, package, deploy — the packaging loop both pages assume.
- Connect Keycloak to LDAP or Active Directory — the same interfaces, already implemented, with write-back.
- Keycloak managed vs unmanaged attributes — why
setAttributecarries profile fields. - Keycloak slow migration vs fast migration — federate or import, decided before you write any of this.
- User migration — the provider that takes the other road.
- Use
kcadm.sh: the Keycloak admin CLI — thecomponentsanduserscommands above, in context. - More Keycloak tutorials.
- Official reference: User Storage SPI.
- Clean up:
docker rm -f kc.