Before discussing caching strategies, we need to understand what federated user storage actually is, and why it introduces a performance concern that Keycloak’s own natively stored users simply do not face.

What is federated user storage?

Most identity platforms assume they own the complete, authoritative record for every user. Keycloak instead supports federated user storage, meaning it can be configured to treat an entirely external system — most commonly a corporate LDAP or Active Directory server — as the real source of truth for some or all of its users, rather than storing every detail about them directly inside its own database. This lets an organization keep using its existing, established directory as the single place employee records genuinely live, while still gaining Keycloak’s modern login and token capabilities layered on top.

Why this creates a performance problem

Every time Keycloak needs information about a federated user — to complete a login, to check group membership, to look up an attribute — it must, in principle, reach out to that external system over the network to retrieve it. Compared to reading from Keycloak’s own local database, this round trip to an external directory is typically far slower, and, at any meaningful scale of concurrent logins, could place significant repeated load on that external system for information that often has not actually changed since the last time it was requested.

What caching actually buys Keycloak

Keycloak’s caching strategies for federated user storage exist specifically to avoid repeatedly hitting that external system for information that was already retrieved recently and has likely not changed. By temporarily holding a local copy of federated user data, Keycloak can serve most subsequent requests for that same user directly from its own fast, local cache, only reaching back out to the external directory when the cached copy is considered stale, or when specifically instructed to refresh.

Keycloak’s federation and caching system is built from several distinct pieces working together, each with its own clearly defined responsibility.

The User Storage SPI

Federation is implemented through Keycloak’s User Storage Service Provider Interface, a formal extension contract that lets an external system be plugged into Keycloak as a source of user data. Keycloak ships with a built-in LDAP provider implementing this interface, and organizations can build entirely custom providers against the same interface to federate from other kinds of external systems as well.

The underlying cache engine: Infinispan

Keycloak’s caching layer, including the cache used for federated user data, is built on Infinispan, a distributed, in-memory data grid technology. This gives Keycloak’s cache the ability to be held consistently in memory for fast access, and, in a clustered deployment, to be shared or replicated appropriately across multiple Keycloak instances rather than each instance maintaining a completely isolated, disconnected cache of its own.

Per-provider cache policy configuration

Each individual federated storage provider — for example, a specific configured LDAP connection — carries its own cache policy setting, deciding exactly how long, and under what conditions, data retrieved from that particular external source should be kept in the local cache before being considered stale and refreshed. This is configured per provider precisely because different external systems, and different organizational needs, can call for genuinely different caching behavior.

Import versus no-import federation modes

Keycloak’s federation can operate in different modes regarding how retrieved data relates to its own local storage. In an import-oriented mode, retrieved federated user data is copied into Keycloak’s own local user representation, which then itself benefits from Keycloak’s standard internal caching behavior. In a non-importing mode, Keycloak instead relies more directly and continuously on its dedicated federated-storage cache layer, without creating a fully separate, locally imported user record.

flowchart TD
    A["Login or User Lookup Request"] --> B["Keycloak checks its local Federated User Cache (Infinispan)"]
    B -->|"Cache Hit and Fresh"| C["Return cached user data immediately"]
    B -->|"Cache Miss or Stale"| D["Keycloak calls out to External Directory (LDAP/AD) via User Storage SPI"]
    D --> E["External directory returns current user data"]
    E --> F["Keycloak updates the local cache with fresh data"]
    F --> C
    

This layered structure — the User Storage SPI connecting to the external system, Infinispan providing the actual cache storage, and per-provider policies deciding exactly how that cache should behave — is what gives Keycloak’s federated caching both real flexibility and real performance benefit at the same time.

This chapter looks closely at exactly how Keycloak decides, for a given request, whether to trust the cache or reach out to the external directory instead.

The four core cache policy modes

Keycloak’s built-in cache policies for federated storage providers offer a small number of distinct strategies. A Default policy relies on Keycloak’s general, evict-based caching behavior. An Evict Daily or Evict Weekly policy clears the entire cache for that provider on a fixed, scheduled basis, regardless of how recently any individual entry was actually used. A Max Lifespan policy instead gives every individual cached entry its own expiry countdown, refreshing it independently once that specific entry’s own lifespan has elapsed. And a No Cache policy disables caching for that provider entirely, always reaching out to the external system fresh, for every single request.

How a lookup actually resolves under Max Lifespan

Under a Max Lifespan policy, when Keycloak needs data for a specific federated user, it first checks whether a cached entry for that user already exists, and, if so, whether it has exceeded its configured maximum lifespan. If the entry is still within its allowed lifespan, Keycloak trusts and returns the cached data directly. If the entry has expired, Keycloak discards it, performs a fresh lookup against the external directory, and stores the newly retrieved data back into the cache with a fresh lifespan countdown of its own.

How Evict Daily and Evict Weekly differ

Rather than tracking each individual cached entry’s own age separately, Evict Daily and Evict Weekly policies instead clear the entire federated user cache for that provider all at once, at a fixed, scheduled time — for example, every night at a configured hour. This means an entry cached just moments before the scheduled eviction time might be discarded almost immediately, while one cached just after a previous eviction could remain in the cache for nearly the entire following day, a genuinely different behavior pattern from the per-entry countdown used by Max Lifespan.

Explicit, manual cache invalidation

Beyond these automatic, time-based policies, Keycloak also supports explicit, administrator-triggered cache clearing — for example, manually clearing the cache for a specific federated provider through the admin console, immediately forcing every subsequent lookup for that provider’s users back out to the external directory, which is particularly useful immediately after a known, significant change has occurred on the external directory side that should not wait for the next scheduled or lifespan-based refresh.

Following a single federated user’s data through a realistic day-in-the-life scenario shows exactly how caching decisions play out in sequence.

Once the core caching modes are understood, a set of more sophisticated behaviors becomes relevant for larger or more demanding federated deployments.

LDAP synchronization strategies alongside caching

Beyond per-lookup caching, Keycloak’s LDAP federation also supports periodic, scheduled synchronization, proactively pulling a broader batch of user data from the directory on a defined schedule, rather than relying purely on individual, on-demand lookups and their cache lifespans. Full synchronization retrieves the complete user population, while changed-user synchronization retrieves only records modified since the last sync, and both interact meaningfully with the caching layer by proactively refreshing data ahead of when a cache entry might otherwise have naturally expired.

Interaction between caching and Keycloak’s own local user storage

In import-oriented federation modes, a federated user’s data, once retrieved, is copied into Keycloak’s own local user table, which itself is then subject to Keycloak’s standard user caching behavior, layered on top of the federated-storage-specific cache discussed so far. Understanding which of these two related but distinct caching layers is actually responsible for a given piece of observed staleness is an important, genuinely advanced diagnostic skill in more complex deployments.

Cache policy tuning for high-change-frequency attributes

Organizations whose federated directory includes attributes that change very frequently — for instance, a real-time “currently on shift” status — often find that a single, uniform cache policy applied broadly across an entire provider is poorly suited to that one specific, fast-changing attribute, leading to more advanced deployments considering custom provider logic or deliberately shorter lifespans specifically to accommodate this kind of unusually volatile data.

Selective cache bypass for specific operations

Some advanced deployments implement logic that deliberately bypasses the cache for specific, particularly sensitive operations — for example, always performing a fresh, uncached lookup immediately before a highly sensitive administrative action — trading away some performance in that narrow, specific case in exchange for a stronger guarantee of working with genuinely current data at that critical moment.

At the deepest level of sophistication, federated caching intersects with clustering, custom provider development, and genuinely complex distributed-systems considerations.

Distributed caching behavior in a clustered deployment

When Keycloak runs as a cluster of multiple instances, the underlying Infinispan cache can be configured to replicate or distribute cached federated user data across those instances, meaning a lookup satisfied by the cache on one instance does not necessarily need to be independently re-fetched from the external directory by every other instance in the cluster as well. Precisely how this distribution is configured has meaningful implications for both performance and the consistency of cached data across the cluster.

Cache invalidation propagation across a cluster

A genuinely advanced consideration is ensuring that a manual cache-clearing action, or an automatic eviction, taken on one instance in a cluster is correctly and promptly propagated to every other instance sharing that same distributed cache, so that stale data is not inadvertently left being served from a different instance that did not receive the same invalidation signal.

Custom User Storage SPI providers with their own caching logic

Organizations federating from an external system that does not fit neatly into the built-in LDAP provider’s assumptions — a proprietary internal system, or an unusual external API — can build an entirely custom provider against the User Storage SPI, and, at this level, can implement genuinely custom caching logic of their own, tailored specifically to that external system’s own particular performance characteristics and consistency guarantees, rather than relying solely on Keycloak’s built-in, general-purpose cache policy options.

Balancing eventual consistency against directory load

At the deepest level, federated caching strategy design becomes an explicit exercise in balancing eventual consistency — accepting that cached data may briefly lag behind the true external source — against protecting the external directory from being overwhelmed by request volume, a genuinely nuanced trade-off that has no single universally correct answer, and instead depends entirely on the specific external system’s own capacity, and the organization’s own tolerance for briefly stale data in specific contexts.

A handful of genuinely subtle, easy-to-misunderstand situations arise specifically at the intersection of caching, federation, and Keycloak’s broader authentication behavior.

Stale role and group membership affecting authorization decisions

Because group and role membership for federated users is itself subject to caching, a user who has just been removed from a sensitive group in the external directory may, for a brief window governed by the cache policy, continue to be treated by Keycloak as still holding that group’s associated permissions, until the relevant cache entry expires or is explicitly cleared — a subtlety with genuine security implications that deserves deliberate consideration, not just a performance-tuning afterthought.

Password and credential verification versus cached attribute data

It is important to distinguish between caching a user’s descriptive attributes — their department, their display name — and the actual credential verification step itself. Password checks against a federated LDAP directory are typically performed as a live, uncached operation at the moment of login, even when other, less security-critical attribute data for that same user is being served from cache, reflecting the different consistency requirements these two categories of data genuinely carry.

Read-only versus writable federation and their differing cache implications

Some federated storage configurations allow Keycloak to write changes back to the external directory, while others are strictly read-only. In a writable configuration, a change made through Keycloak itself needs to be reflected both in the external directory and correctly propagated through the caching layer, introducing an additional layer of consistency consideration beyond the read-only case, where the external directory is always assumed to be the sole, one-directional source of truth.

Interaction between federated caching and account console self-service changes

When a federated user updates their own profile information through Keycloak’s account console, in a writable federation configuration, careful attention is needed to ensure the change is correctly reflected back to the external directory and the local cache is appropriately refreshed or invalidated, rather than the user seeing their own just-made change appear to silently revert the next time their data happens to be served from a still-stale cached entry.

Every caching strategy for federated user storage is fundamentally a trade-off between login performance and data freshness, and different strategies land at meaningfully different points along that spectrum.

Finding the right point on the trade-off spectrum

For most attributes, in most organizations, a moderate cache lifespan strikes a reasonable, practical balance — meaningfully reducing directory load without introducing staleness severe enough to cause real problems. For specific, security-critical data, such as group memberships governing sensitive access, organizations often deliberately choose shorter lifespans, or even selective cache bypass, accepting the additional directory load in exchange for tighter consistency exactly where it matters most.

The entire purpose of federated caching is performance, which makes understanding its scalability characteristics especially important.

Cache hit rate as the central performance metric

The overall performance benefit federated caching delivers is directly driven by its hit rate — the proportion of lookups successfully satisfied from the local cache rather than requiring a fresh external directory call. A high hit rate, achieved through an appropriately tuned cache policy relative to actual usage patterns, is what ultimately determines whether federated caching meaningfully improves real-world login performance at scale.

Memory consumption at large user populations

Because cached federated user data is held in memory, organizations federating a very large number of users need to account for the memory footprint this caching layer introduces, particularly in a clustered deployment where cache replication settings can further influence exactly how much memory is consumed across the cluster as a whole.

The thundering-herd risk around synchronized cache expiry

Evict Daily and Evict Weekly policies, which clear an entire provider’s cache all at once at a fixed time, carry a specific scalability risk: immediately following that scheduled eviction, every subsequent lookup for any user of that provider will simultaneously require a fresh external directory call, potentially producing a sudden, concentrated spike of load against the external directory precisely at the scheduled eviction moment, a pattern sometimes called a thundering herd.

Scaling considerations for synchronization versus on-demand caching

Organizations with very large federated user populations often find that combining scheduled, proactive synchronization with on-demand caching provides better overall scalability than relying purely on reactive, per-lookup caching alone, since synchronization can spread the load of refreshing a large user population out over a controlled schedule, rather than concentrating it around specific, high-traffic login moments.

Federated caching plays a genuinely important, sometimes underappreciated role in how gracefully a Keycloak deployment handles problems with its external directory dependency.

Caching as a partial buffer against directory outages

Because recently cached federated user data can, depending on configuration, continue to be served even if the external directory temporarily becomes unreachable, caching provides a limited but genuinely valuable degree of resilience — allowing already-cached users to continue authenticating for a short window even during a brief external outage, rather than every single login attempt failing immediately the moment the directory becomes unavailable.

The limits of this resilience

This protective effect is inherently limited: a user who has never been looked up before, and therefore has no cached entry, will still fail to authenticate during a genuine external directory outage, since there is no prior cached data to fall back on for them. Caching softens, but does not eliminate, the underlying dependency federated storage creates on that external system’s own availability.

Cache consistency during failover in clustered deployments

In a highly available, clustered Keycloak deployment, ensuring the distributed cache behaves consistently during a failover event — an instance going down and traffic shifting to remaining instances — is an important reliability consideration, since inconsistent or lost cache state during failover could otherwise translate into a sudden, temporary spike of fresh external directory lookups right at the moment the deployment is already under the added stress of handling a failover.

Planning around scheduled synchronization and maintenance windows

Organizations relying on scheduled full or incremental synchronization with their external directory should coordinate this scheduling thoughtfully against any known maintenance windows for that external system, since a synchronization attempt colliding with directory-side maintenance could produce partial, inconsistent results that then persist in Keycloak’s cache until the next successful synchronization or natural cache expiry corrects them.

Because federated caching directly affects how quickly changes in the source of truth actually take effect within Keycloak, it carries genuine, specific security implications worth deliberate attention.

The specific risk of stale, revoked access

The single most important security consideration in federated caching is the window between a genuine change on the external directory side — an employee’s account being disabled, their group membership being revoked following a role change — and that change actually being reflected through Keycloak’s cache. During this window, a cached entry may continue to represent the user’s previous, now-outdated state, potentially allowing continued access that should have already been revoked.

Coordinating offboarding processes with cache invalidation

Organizations with a formal employee offboarding process should specifically include, as an explicit step, either clearing the relevant cache entry in Keycloak or otherwise ensuring the disabled state is promptly reflected, rather than assuming the external directory change alone is sufficient on its own to immediately and completely revoke access through Keycloak.

Choosing shorter lifespans for security-critical attributes

Given the specific risk around stale authorization-relevant data, security-conscious deployments often deliberately configure shorter cache lifespans specifically for the attributes and group memberships that directly influence access decisions, even if this means accepting somewhat more frequent external directory lookups than would otherwise be strictly necessary for pure performance optimization.

Auditing cache policy configuration as part of security review

Federated storage cache policy settings are a legitimate, worthwhile item to include in periodic security reviews, since an overly generous cache lifespan, chosen purely for performance reasons without full consideration of its security implications, can quietly become a meaningful gap between an organization’s actual, intended access policy and what Keycloak is genuinely, currently enforcing.

Understanding whether a federated caching configuration is genuinely working well in practice requires deliberate visibility into both cache behavior and the underlying external directory’s own load.

Cache hit and miss tracking

Monitoring the ratio of cache hits to cache misses for federated user lookups provides the most direct signal of how effectively a given cache policy is performing in real-world conditions, and can reveal whether a configured lifespan is well matched to actual usage patterns, or whether it is either too short, producing excessive external directory traffic, or unnecessarily long relative to how frequently data genuinely changes.

External directory load correlation

Correlating Keycloak’s own cache behavior with monitoring data from the external directory itself — its own observed query volume and response latency — helps confirm whether the caching layer is genuinely delivering its intended protective effect, or whether the external directory is still experiencing more load than the caching strategy was expected to prevent.

Synchronization job monitoring

For deployments relying on scheduled full or incremental synchronization, monitoring the success, failure, and record-count results of each synchronization run is essential, since a silently failing or incomplete synchronization job can leave the cache populated with data that is far more stale than the configured policy would otherwise suggest, without any obvious, immediate symptom pointing directly to the underlying cause.

Alerting on external directory unavailability

Because federated caching provides only limited, temporary resilience against an external directory outage, dedicated monitoring and alerting specifically on the external directory’s own availability remains essential, ensuring operators are promptly aware of an outage well before the protective effect of already-cached data eventually runs out for the affected user population.

How federated caching is actually deployed and operated varies meaningfully depending on the surrounding infrastructure and how Keycloak itself is run.

Cache configuration in containerized, clustered deployments

In modern, containerized Keycloak deployments running multiple replicas, the underlying Infinispan cache configuration needs to be deliberately set up to support appropriate distribution or replication across those replicas, since a default, purely local, per-instance cache configuration could otherwise result in inconsistent cache states between different replicas serving the same federated users.

Network topology between Keycloak and the external directory

The network path and latency between Keycloak’s deployment environment and the external federated directory has a direct, meaningful influence on how much value caching actually delivers — a directory reachable with very low latency benefits less dramatically from aggressive caching than one reached across a slower, higher-latency connection, such as a directory hosted in a genuinely separate cloud region or on-premises data center.

Infrastructure-as-code for cache policy configuration

Organizations managing Keycloak configuration declaratively, through version-controlled infrastructure-as-code practices, typically include federated storage provider settings, including their cache policies, as part of that same managed configuration, ensuring caching behavior is deployed consistently across environments rather than configured manually and potentially inconsistently, instance by instance.

Multi-region deployments and federated directory proximity

Organizations running Keycloak across multiple geographic regions, federating from a directory that itself may only exist in one specific region, need to consider how cache policy tuning interacts with the resulting cross-region latency for users being authenticated from a region distant from that directory, often finding that more generous caching becomes especially valuable specifically for those geographically distant users.

Organizations running federated storage at real scale over time tend to converge on a handful of proven, sound caching patterns.

Pattern: Differentiated lifespans by data sensitivity

Mature deployments apply longer, more generous cache lifespans to relatively stable, low-sensitivity attributes, while applying noticeably shorter lifespans, or dedicated cache-bypass logic, specifically to security-relevant data like group memberships and account-enabled status, rather than applying one single, uniform policy across every kind of federated data indiscriminately.

Pattern: Scheduled synchronization paired with on-demand caching

Well-run deployments often combine both mechanisms deliberately — scheduled synchronization proactively keeping the broader user population reasonably current, while on-demand caching handles individual, real-time lookups efficiently in between synchronization runs — rather than relying on only one of the two mechanisms in isolation.

Anti-pattern: One uniform, “set and forget” cache policy for everything

A common and risky shortcut is applying a single default cache policy, chosen once during initial setup, uniformly across every federated provider and every kind of attribute, without ever revisiting whether that one policy remains appropriate as the organization’s own usage patterns, security requirements, and directory scale evolve over time.

A disciplined set of habits consistently separates federated caching that genuinely balances performance and freshness from configuration that quietly creates either performance problems or security gaps.

Federated user storage caching becomes especially important wherever an organization’s real user records live in an established, external system that Keycloak must respectfully and efficiently work alongside.

Large enterprises with established Active Directory deployments

Organizations with a long-standing, deeply embedded Active Directory deployment governing tens of thousands of employee accounts frequently adopt Keycloak as a federated front end, relying heavily on well-tuned caching to keep login performance acceptable across a large, geographically distributed workforce, without placing excessive, repeated load on their existing, already heavily relied-upon directory infrastructure.

Higher education institutions federating from campus directories

Universities and colleges, often needing to authenticate large numbers of students and staff against a pre-existing campus directory system, commonly rely on federated caching to handle the significant login volume that occurs at predictable, concentrated moments — the start of a semester, the opening of an exam registration window — without those spikes translating directly into equivalent spikes of load against the underlying campus directory.

Mergers and acquisitions bridging separate directories

Organizations going through a merger or acquisition frequently use federated storage, and its associated caching strategies, as a practical, gradual bridge — allowing employees from an acquired company’s own separate directory to authenticate through a shared Keycloak deployment during a transitional period, without requiring an immediate, disruptive, wholesale migration of that directory’s entire user population.

Regulated industries requiring directory data to remain in place

Organizations in regulated industries, where compliance requirements dictate that certain user data must remain stored specifically within an established, audited internal directory system rather than being duplicated elsewhere, rely on federated storage precisely to satisfy this data-residency requirement, while still relying heavily on caching to ensure that this architectural constraint does not come at the cost of unacceptably slow login performance.

Federated User Storage Caching Strategies exist to solve a problem that becomes unavoidable the moment Keycloak stops being the sole owner of its own user data: the external system holding the real, authoritative record is almost always slower to reach than Keycloak’s own local storage, and repeatedly asking it the same questions is both wasteful and, at scale, genuinely risky to that external system’s own stability. Keycloak’s answer — a flexible, per-provider set of cache policies, built on a genuine distributed caching engine, with explicit tools for manual invalidation when automatic timing is not good enough — gives organizations real, deliberate control over exactly where on the spectrum between raw performance and perfect freshness they want to sit, for each specific piece of data they care about. Getting this right is not a one-time technical decision; it is an ongoing balance, revisited as an organization’s own directory, security requirements, and scale continue to evolve.