Before diagrams and architecture, let’s build a clear mental model of the problem this feature solves.

The problem: not every user lives in Keycloak’s own database

By default, Keycloak stores users — their credentials, profile attributes, and role assignments — in its own internal database. That works well for new deployments. But many organizations already have users living somewhere else: a decades-old relational database, a proprietary HR platform, a legacy authentication system tied to a mainframe. Migrating all of that data into Keycloak’s own store is often risky, sometimes technically difficult, and occasionally simply not allowed by policy. Custom User Storage Providers exist precisely for this situation.

The formal definition

A User Storage Provider is an implementation of Keycloak’s User Storage SPI (Service Provider Interface) that allows an external system to act as a source of user data for a realm. A Custom User Storage Provider is one an organization builds itself — as opposed to Keycloak’s built-in providers for common systems like LDAP directories — to connect to a bespoke or proprietary user store that Keycloak has no ready-made integration for.

What “federation” really means here

This capability is often described as user federation, because it lets Keycloak federate — that is, incorporate and present as its own — user records that physically live in an external system. From the perspective of any application relying on Keycloak, a federated user looks exactly like a normal Keycloak user; the federation happens transparently underneath.

Why this matters beyond just convenience

Avoiding a bulk migration isn’t only about saving engineering effort — it’s often about risk. A one-time migration of sensitive credential and profile data carries real chances of data loss, corruption, or a window where two systems disagree about who a user is and what they’re allowed to do. Keeping the external system as the live source of truth, and simply teaching Keycloak to ask it questions, sidesteps that entire category of migration risk, at the cost of an ongoing dependency on that external system’s availability — a trade-off explored in depth later in this post.

A Custom User Storage Provider isn’t one single piece of code — it’s a small set of cooperating parts that plug into Keycloak’s provider framework.

The Service Provider Interface (SPI) model

Keycloak is built around a plugin architecture called SPIs, which let developers extend or replace specific pieces of Keycloak’s behavior without modifying Keycloak’s own codebase. The User Storage SPI is one such extension point, specifically dedicated to sourcing user data from external systems.

How the pieces fit together

Picture Keycloak’s core as a hotel front desk that doesn’t personally know every guest but knows exactly which department to call to check. When a guest’s name doesn’t match anyone in the front desk’s own guest list, the front desk calls the affiliated corporate housing office (the external data source) through a dedicated phone line (the provider instance) built specifically for that purpose (the provider factory’s configuration). The guest still checks in through the same front desk, never realizing their record actually lives somewhere else entirely.

flowchart LR
    KC[Keycloak Core] -->|user lookup request| SPI[User Storage SPI]
    SPI --> PF[Provider Factory]
    PF --> PI[Provider Instance]
    PI -->|query| EXT[External Data Source
e.g. legacy database]
    EXT -->|user record| PI
    PI -->|federated user| KC
        

Optional capabilities a provider can implement

Not every provider needs to do everything. A provider might only support looking users up by username, treating the external system as strictly read-only — useful when the external system is authoritative and shouldn’t be modified through Keycloak at all. Another provider might additionally implement full user management, letting administrators create, update, and delete records in the external system directly through the Keycloak admin console.

Registering a provider with a realm

Once a provider’s code is deployed alongside Keycloak, an administrator enables it for a specific realm through the User Federation section of the admin console, configuring connection details specific to that provider — such as a database connection string, an internal API endpoint, or authentication credentials the provider itself needs to reach the external system. A single realm can have multiple providers active at once, each potentially responsible for a different subset of users or a different external system entirely.

Priority ordering among multiple providers

When more than one provider is configured for the same realm, Keycloak consults them in a defined priority order until one recognizes the requested user. This lets an organization layer several external sources together — for example, checking a primary HR database first, and falling back to a secondary legacy system only if the first doesn’t recognize the username — without needing a single provider to understand every possible source at once.

What actually happens inside Keycloak the moment it needs information about a federated user?

Caching to avoid hammering the external system

Because querying an external system on every single request could be slow or place heavy load on that system, Keycloak supports caching federated user data locally for a configurable period. Cached data is periodically refreshed or invalidated, striking a balance between performance and staying reasonably current with changes made directly in the external system.

Handling lookups that don’t match anything

Not every lookup succeeds. When neither Keycloak’s local store nor any registered provider recognizes a given username or email, the request simply fails as “user not found,” exactly as it would in a purely native Keycloak setup. Providers are typically written to fail this check quickly and cheaply, since a busy login page might be checking many attempted usernames that don’t correspond to any real account, and a slow “not found” response is just as costly to performance as a slow successful one.

Mapping fields between two different data shapes

An external system’s data rarely lines up perfectly with Keycloak’s own expectations for a user record. A legacy database might store a name as a single combined field, while Keycloak expects separate first and last name attributes; it might use a numeric employee ID as its primary identifier, where Keycloak expects a username. Part of building the provider is deciding, deliberately, how these mismatches get resolved — decisions that, once made, become a durable part of how that organization’s identities are represented going forward.

Let’s trace a full request end to end, using a realistic scenario: a user logging in whose account lives entirely in a legacy HR database.

sequenceDiagram
    participant User
    participant KC as Keycloak
    participant Provider as Custom Storage Provider
    participant HR as Legacy HR Database

    User->>KC: Enter username and password
    KC->>KC: Check internal user store (not found)
    KC->>Provider: Delegate lookup for username
    Provider->>HR: Query for matching employee record
    HR-->>Provider: Return employee data
    Provider-->>KC: Map to Keycloak user model
    KC->>Provider: Validate submitted password
    Provider->>HR: Check credential against stored value
    HR-->>Provider: Valid / Invalid
    Provider-->>KC: Credential result
    KC-->>User: Login success or failure
        

Lifecycle of a federated user’s data

Import versus no-import providers

Some deployments configure a provider to “import” federated users into Keycloak’s local store on first lookup, after which Keycloak treats that user largely as its own, periodically re-syncing from the source. Others use a strict no-import model, where Keycloak never persists the user’s data locally at all and always queries the external system fresh. The right choice depends on how authoritative and available the external system is expected to remain over time.

Choosing between import and no-import in practice

An import model tends to suit organizations that expect the external system to eventually be retired — imported users gradually become fully native Keycloak users over time, easing the path toward decommissioning the legacy source entirely. A no-import model suits the opposite situation: an external system that will remain the permanent source of truth indefinitely, where treating Keycloak’s copy as anything more than a transient, cached view would risk the two systems drifting out of sync.

Custom User Storage Providers aren’t all built the same way — the right shape depends on what the external system can and should be allowed to do.

Comparing the patterns side by side

It’s worth seeing this approach next to the other ways organizations connect Keycloak to existing user data.

The pattern across every alternative is familiar: each solves part of the puzzle while giving something else up — either the unified login experience, or the ability to avoid migration, or compatibility with a non-standard system. A Custom User Storage Provider is the option organizations reach for specifically when they need all three at once and no built-in provider already covers their particular external system.

Combining approaches in a single realm

These options aren’t always mutually exclusive. A realm might use the built-in LDAP provider for its standard corporate directory, a custom provider for a legacy proprietary system acquired through a merger, and identity brokering for a small set of external partner organizations that already run their own full authentication systems — all coexisting within the same realm, each handling the population of users it’s best suited for.

Building a custom integration is powerful, but it comes with genuine engineering and operational responsibilities.

Weighing the trade-off honestly

The right decision usually comes down to how long the external system is expected to remain in place, and how much engineering capacity exists to build and maintain the provider well. A system being retired within a year might not justify the investment of a custom provider at all — a simpler, well-planned bulk migration could be less overall effort. A system expected to remain authoritative for the foreseeable future, by contrast, often makes the ongoing maintenance cost of a custom provider clearly worthwhile compared to the alternative of forcing a migration that isn’t really wanted.

Because a custom provider sits directly in the authentication path, its implementation quality has a direct impact on the security of every login it handles.

Treating the provider as part of the trusted computing base

Because the provider’s code runs with direct access to authentication decisions, it deserves the same code review, testing, and security scrutiny as any other authentication-critical component — not the lighter treatment sometimes given to internal integration glue code. A vulnerability in the provider is functionally a vulnerability in Keycloak’s login path itself.

The service account problem

Because a provider typically needs its own credentials to query the external system — a service account, an API key, a database connection string — those credentials become a high-value target in their own right. They should be stored using Keycloak’s own credential vault or an equivalent secrets management approach, never embedded directly in configuration files or source code, and rotated on the same schedule an organization applies to its other privileged service accounts.

Because a custom provider introduces a dependency on an external system, operating it well means watching that dependency closely.

What to watch

What to log

Recording which provider handled a given lookup, how long the external query took, and whether it succeeded or failed gives administrators a clear trail for diagnosing authentication problems that span both Keycloak and the external system — without which a login failure could be misdiagnosed as a Keycloak bug when the real cause lies entirely on the other side of the integration.

Setting up early warning for external dependency health

Because the external system’s health is now directly tied to Keycloak’s ability to authenticate users, it’s worth alerting on that system’s own health signals — not just Keycloak’s — well before a full outage occurs. A gradually rising query latency on the external side, for instance, is a useful early warning that gives an operations team time to investigate before it turns into visible login failures for real users.

Some ways of building a custom provider age well as usage scales. Others quietly become fragile.

Patterns worth adopting

A checklist-style chapter distilling the operational wisdom from the sections above.

Planning for eventual retirement

Even a well-built custom provider is often, by design, a bridge rather than a permanent destination. Teams that plan from the outset for how and when the external system might eventually be retired — whether through gradual import into Keycloak’s native store or a deliberate future migration — tend to avoid the common trap of a “temporary” integration quietly becoming permanent infrastructure nobody budgeted to maintain indefinitely.

Custom User Storage Providers show up wherever an organization’s real user data lives somewhere Keycloak doesn’t natively understand.

No — LDAP integration uses Keycloak’s built-in provider designed specifically for LDAP and Active Directory. A Custom User Storage Provider is something an organization builds for a system with no existing built-in integration.

Not necessarily — it depends on whether the provider is configured to import users locally or to always query the external system fresh, without persisting a local copy.

Yes, if it implements the relevant capability interfaces — though many deployments deliberately keep the provider read-only to avoid unnecessarily expanding what Keycloak can change in the external system.

Behavior depends entirely on how the provider is implemented — a well-designed provider fails predictably and may be able to rely on recently cached data for a short window, while a poorly designed one can cause a full authentication outage.

No — federation is transparent to relying applications. A federated user looks identical to a native Keycloak user from the perspective of any application consuming tokens issued by Keycloak.

Not always — if the legacy system already exposes a standard protocol like LDAP, or has its own full login flow suitable for identity brokering, those existing options may be simpler than building a custom provider from scratch.

Yes — a realm can have multiple User Storage Providers active simultaneously, each handling a different population of users or a different external system, evaluated in a configured priority order.

An already-issued token and active session generally remain valid on their own terms; the impact is mainly felt on new logins or fresh lookups that need to reach the external system, not on sessions already established before the outage began.

A Custom User Storage Provider is Keycloak’s answer to the very common, very real problem of user data that already exists somewhere else — a legacy database, a proprietary internal system, a directory too risky or too regulated to migrate. Rather than forcing a disruptive, one-time data migration, it lets Keycloak reach out to that external system live, on demand, and present the result as if it were a native user — all while giving every application a single, consistent login experience through Keycloak itself.

Building one well means treating it as genuine authentication-critical infrastructure: implement only the capabilities actually needed, cache thoughtfully rather than not at all, handle the external system’s failures gracefully, and monitor the integration as closely as any other production dependency. Done right, a Custom User Storage Provider becomes the quiet, reliable bridge that lets an organization modernize its authentication layer without ever disturbing the data underneath it.