What “SPI” Means, Restated Precisely

A Service Provider Interface (SPI) is a defined extension point — a Java interface Keycloak itself declares — that custom code can implement to plug new behavior into Keycloak without modifying Keycloak’s own core codebase. Examples covered elsewhere in this series include the Event Listener SPI; Keycloak exposes dozens of others, covering Authenticators, User Storage integrations, Protocol Mappers, and more.

Provider vs. Provider Factory

Two related but distinct concepts underpin every SPI implementation: a Provider is the actual object doing the real work for a single request or operation, while a Provider Factory is a longer-lived object responsible for creating Provider instances and holding any shared, expensive-to-initialize configuration. Understanding this split matters directly for the lifecycle and performance discussions later in this guide.

Why Packaging and Deployment Deserve Their Own Dedicated Discipline

A custom SPI implementation that works perfectly in a developer’s own local testing can still fail in production for reasons entirely unrelated to its own logic — a classloading conflict, a missing service-registration file, an incompatibility introduced by a routine Keycloak version upgrade. This guide exists because these packaging and deployment concerns are genuinely their own advanced discipline, distinct from and just as important as writing the extension’s actual functional code.

Why Keycloak Splits Responsibility This Way

Separating a Provider Factory’s longer-lived responsibilities from a Provider’s per-use work lets Keycloak reuse expensive setup — reading configuration, establishing a connection pool — once per Factory, while still creating a fresh, isolated Provider instance for each individual operation, avoiding both the cost of repeated expensive setup and the risk of unintended state leaking between unrelated requests.

The Factory’s Lifecycle Hooks

A Provider Factory implements specific lifecycle methods Keycloak calls at defined moments — once when the Factory is first initialized, again after every Provider Factory across the whole system has been initialized (letting one Factory safely reference another), and finally when the server shuts down, giving the Factory a chance to release any held resources cleanly.

The Java ServiceLoader Standard

Keycloak’s provider discovery builds on Java’s own standard ServiceLoader mechanism: a text file, placed at a specific, predictable path inside the packaged JAR (under META-INF/services/, named exactly after the SPI’s own fully qualified interface name), listing the fully qualified class name of every Provider Factory implementation that JAR contains for that specific SPI.

Why a Missing or Misconfigured Registration File Is a Common, Silent Failure

If this registration file is missing, misnamed, or lists an incorrect class name, Keycloak simply never discovers the custom provider at all — with no obvious error pointing directly at the actual cause, since from Keycloak’s own perspective, the provider genuinely doesn’t exist as far as its own discovery mechanism is concerned. This is one of the most common, and most confusing to a newcomer, packaging mistakes covered further in Chapter 15.

The Case for Bundling Related Providers Together

Several closely related providers — a custom Authenticator and a companion Required Action it depends on, for instance — are often packaged into a single JAR, since they’re conceptually one feature, tend to be versioned and deployed together, and sharing a single JAR avoids the overhead of managing several nearly-identical deployment artifacts for what is, in practice, one cohesive unit of functionality.

The Case for Separating Genuinely Independent Providers

Conversely, providers serving entirely unrelated purposes — a custom Event Listener feeding a SIEM pipeline, as covered in this series’ audit-trail guide, and an entirely unrelated custom Authenticator — are often better packaged separately, so each can be versioned, tested, and deployed on its own independent schedule without one’s changes forcing an unrelated redeployment of the other.

Why Isolation Matters at All

A custom provider frequently depends on its own third-party libraries — a specific HTTP client version, a specific JSON-parsing library — and without deliberate isolation, a version of a library bundled with one provider could silently conflict with a different version of that same library already used internally by Keycloak itself, or by an entirely unrelated, independently developed provider deployed alongside it.

How Keycloak’s Own Classloading Model Addresses This

Keycloak’s Quarkus-based runtime applies a defined classloading strategy specifically designed to isolate provider-supplied classes from Keycloak’s own internal implementation classes, reducing (though not entirely eliminating) the risk of this kind of conflict. Understanding exactly which classes are shared versus isolated, and which specific packages a provider is expected to avoid bundling its own conflicting version of, is essential advanced knowledge for any team building nontrivial custom providers with their own real external dependencies.

Shading and Relocation as a Mitigation Technique

One common technique for reducing this risk is shading — repackaging a bundled dependency’s own classes under a renamed, provider-specific package path at build time, so it can never collide with a same-named class Keycloak or another provider happens to load from the shared classpath. This trades a small amount of build complexity for a meaningfully reduced risk of exactly the kind of silent, runtime-only conflict described above, and is worth adopting deliberately for any dependency known to be widely used and therefore prone to version clashes.

Preferring Keycloak’s Own Already-Provided Libraries Where Possible

Before bundling a provider’s own copy of a common library, it’s worth checking whether Keycloak’s own runtime already provides a compatible version on the shared classpath — depending on that already-provided version, rather than bundling a separate, potentially conflicting copy, sidesteps the entire class of problem this chapter describes for that specific dependency, at the cost of a tighter coupling to whichever version Keycloak itself happens to ship in a given release.

What Augmentation Actually Does

Keycloak’s modern, Quarkus-based distribution performs a dedicated build step (commonly invoked through its own build command) that inspects the current set of providers present in the installation and pre-computes significant parts of the server’s own startup configuration ahead of time, trading a small amount of upfront build time for meaningfully faster actual server startup afterward.

Why a New or Changed Provider Requires Re-Running This Step

Because this build step bakes the current provider set into its precomputed configuration, simply dropping a new JAR into the providers directory isn’t, on its own, sufficient — the build step needs to be explicitly re-run afterward for the newly added (or changed, or removed) provider to actually take effect, a detail that surprises teams accustomed to older, purely dynamic deployment models where a dropped-in file might have taken effect immediately.

Optimized vs. Non-Optimized Startup Modes

Keycloak’s Quarkus-based distribution offers both a fully pre-built, optimized startup mode (where the build step has already run ahead of time, as this guide generally assumes) and a non-optimized mode that performs an equivalent of the build step automatically at every single startup instead. The non-optimized mode is genuinely convenient during early, local development, where providers change frequently and re-running a separate build command each time would be tedious — but it comes at the cost of meaningfully slower startup, making it generally unsuitable for a production deployment where fast, predictable startup time actually matters.

Verifying the Build Actually Picked Up the Intended Providers

Beyond simply remembering to run the build step, it’s worth explicitly confirming afterward that it genuinely detected and incorporated the intended provider set — Keycloak’s own build output typically lists the providers it discovered, and reviewing this output as a deliberate, explicit verification step, rather than simply assuming success from the absence of an error, closes the loop on exactly the kind of silent failure this chapter has been focused on throughout its discussion.

Development. A developer writes and locally tests the provider’s own implementation, typically against a local Keycloak instance.

Build and Package. The provider is compiled and packaged into a JAR, including its own service-registration file and any bundled dependencies, as covered in Chapters 4 through 6.

Staged Deployment. The packaged JAR moves through the organization’s own deployment pipeline (covered further in Chapter 11), typically reaching a staging environment before production.

Production Activation. The JAR is placed into production’s providers directory, the build (augmentation) step is re-run, and the server is restarted or rolled, activating the new or updated provider.

Ongoing Operation. The provider runs in production, ideally monitored using the practices covered in Chapter 14.

Version Compatibility Review. Whenever the underlying Keycloak version itself is upgraded, the provider needs explicit review against that new version, as covered in Chapter 13, before the upgrade proceeds to production.

graph LR
    A["Development"] --> B["Build & Package"]
    B --> C["Staged Deployment"]
    C --> D["Production Activation"]
    D --> E["Ongoing Operation"]
    E --> F["Keycloak Upgrade
Compatibility Review"]
    F --> B
    

Provider-Specific Configuration via the SPI Framework

Keycloak’s own SPI framework supports defining configuration properties directly for a custom provider, exposed through the Admin Console alongside Keycloak’s own built-in provider configuration, letting an administrator adjust a custom provider’s behavior without needing to touch its underlying code or redeploy anything.

Externalizing Genuinely Sensitive or Environment-Specific Settings

For values that shouldn’t be hard-coded or stored directly inside Keycloak’s own configuration store — a third-party API key, an environment-specific connection string — a well-designed provider generally reads these from an external source, such as an environment variable or a dedicated secrets-management system, following the same principle covered in this series’ Realm Export/Import guide regarding never embedding real secrets directly where they’d be broadly visible.

Automated Build and Test

A sound pipeline compiles the provider, runs its own unit tests, and ideally runs an integration test against a genuinely running Keycloak instance (covered further in Chapter 12) automatically on every change, catching a broken build or a regression well before it ever reaches a shared environment.

Versioned, Immutable Artifacts

Each successful build produces a versioned, immutable JAR artifact, stored in an artifact repository, so any specific version can be reliably retrieved again later — for a rollback, for an audit, or simply to confirm exactly which version is currently running in a given environment.

Staged Promotion Through Environments

The same, unchanged artifact is promoted through successive environments — development, staging, production — rather than being rebuilt separately for each one, ensuring the exact code that was tested in staging is genuinely, bit-for-bit the same code that eventually reaches production.

Unit Testing the Provider’s Own Logic

Ordinary unit tests, exercising a provider’s own business logic in isolation, remain valuable and fast to run, but they generally cannot catch packaging-level issues — a missing service-registration file, a classloading conflict — since they never actually exercise Keycloak’s own real provider-discovery and startup machinery.

Integration Testing Against a Real, Running Keycloak Instance

A genuinely thorough testing strategy includes spinning up an actual, real Keycloak instance (often in a disposable container) with the packaged provider JAR actually installed, and exercising it exactly as a real user or administrator would — the only way to reliably catch the packaging-specific failure modes covered throughout this guide before they reach a shared environment.

SPIs Can Change Between Keycloak Versions

Because SPIs are part of Keycloak’s own internal extension surface rather than a permanently frozen public contract, a given SPI’s interface can change — a new method added, a signature altered — between Keycloak versions, meaning a custom provider built against one version isn’t automatically guaranteed to compile, or behave correctly, against a later one.

Why This Demands a Deliberate, Tested Upgrade Process

Upgrading the underlying Keycloak version without also reviewing and, where necessary, updating every custom provider against that new version risks a provider silently failing to build, failing to load, or — more subtly and dangerously — building and loading successfully while behaving incorrectly against a changed underlying contract. A sound upgrade process treats every custom provider as something that must be explicitly re-verified against a new Keycloak version, never assumed to simply continue working unchanged.

Reading Keycloak’s Own Release Notes for SPI-Level Changes

Before upgrading, a deliberate review of Keycloak’s own release notes specifically for changes to the SPIs a custom provider actually implements is well worth the modest time it takes — these notes generally call out breaking changes to extension points explicitly, and catching a relevant change here, ahead of time, is considerably cheaper than discovering it only after an upgrade has already reached a shared or production environment where far more people are affected by any resulting disruption.

Maintaining a Dedicated Upgrade-Testing Environment

A particularly disciplined approach maintains a separate environment specifically for trialing an upcoming Keycloak version against the full, current set of custom providers before that version is approved for wider promotion — catching any compatibility issue in a low-stakes setting deliberately built for exactly this purpose, rather than discovering it for the first time during a genuine staging or production upgrade, when the cost of an unexpected surprise is considerably higher.

Pinning Dependency Versions Explicitly Rather Than Floating

A custom provider’s own build configuration should generally pin its dependency versions — including its dependency on Keycloak’s own SPI interfaces themselves — to specific, known values rather than allowing them to float to whatever the latest available version happens to be at build time. A floating dependency can silently introduce an incompatibility on a routine rebuild, entirely independent of any deliberate Keycloak upgrade decision, making the provider’s own behavior effectively nondeterministic across builds taken at different points in time, and considerably harder to reason about during any later troubleshooting effort.

A Provider Should Fail Loudly, Not Silently

Given how many of this guide’s failure modes are inherently silent — a missing registration file, a forgotten build step — a well-built custom provider deliberately logs a clear, unambiguous statement of its own successful initialization at startup, giving operators a concrete, positive signal to check for and a fast, direct way to confirm the provider actually came up correctly, rather than needing to infer its presence indirectly.

Exposing a Provider’s Own Version Through a Health or Diagnostics Endpoint

Beyond a simple startup log line, a genuinely mature provider can expose its own version and basic health status through a diagnostics endpoint or Keycloak’s own health-check integration, letting an automated deployment pipeline (or a human operator) programmatically confirm exactly which provider version is currently active in a given environment, rather than relying purely on manual log inspection or, worse, an unverified assumption based on what was supposed to have been deployed.

Correlating Provider Behavior With the Audit Trail

Where a custom provider performs a security-relevant action — a custom Authenticator making an access decision, for instance — its own internal logging benefits from using the same correlation-ID approach covered in this series’ audit-trail guide, letting a provider’s own detailed internal behavior be traced alongside the broader Login and Admin Event stream during an investigation, rather than existing as an isolated, hard-to-correlate log source of its own.

Good Patterns

• Automate the entire deployment pipeline, including the build (augmentation) step, rather than relying on a manually performed, easily forgotten sequence
• Test against a genuinely running Keycloak instance, not just in isolated unit tests, to catch packaging and classloading issues before they reach production
• Externalize environment-specific and sensitive configuration, keeping one identical, versioned artifact usable unchanged across every environment
• Maintain an explicit provider-to-Keycloak-version compatibility record, reviewed deliberately before every Keycloak upgrade

Anti-patterns to Avoid

The Single Most Common Mistake: Treating Deployment as an Afterthought

Teams frequently invest significant, careful engineering effort into a custom provider’s own business logic while treating its packaging and deployment as a quick, informal afterthought — exactly backwards from the genuine risk profile this guide has covered throughout, where packaging and deployment failure modes are disproportionately silent, confusing, and costly relative to the comparatively visible, easily-tested failures in the provider’s own core logic.

Baking Providers Into a Custom Container Image

Rather than mounting the providers directory as an external volume and copying JARs in at deploy time, many containerized deployments instead bake the provider JARs, and the results of the build (augmentation) step, directly into a custom Keycloak container image itself — producing one immutable, fully self-contained artifact that starts up quickly and consistently, without any separate, additional deployment step needed once the container is running.

Rolling Deployments and Provider Version Consistency

In a clustered deployment, as covered in this series’ clustering guide, a rolling deployment strategy needs to ensure every Node runs the exact same provider version at the same time — a cluster with some Nodes running an old provider version and others running a new one simultaneously can produce genuinely inconsistent behavior depending on which specific Node happens to handle a given request, a scenario worth explicitly avoiding through a deliberate, coordinated rollout strategy.

Coordinating Provider Rollouts With Stateless Clustering’s Own Rolling-Update Behavior

As covered in this series’ Stateless Clustering guide, a well-configured cluster can tolerate individual Nodes being cycled without disrupting active user sessions. That same rolling-update mechanism is exactly what carries a new provider image out across the cluster during a deployment, but it does mean there is necessarily a brief transition window during which old and new Nodes coexist unless the rollout strategy is deliberately configured otherwise — worth explicitly accepting as a bounded, brief, and monitored transition rather than assuming provider version consistency is instantaneous across every Node at every single moment.

Rollback Readiness as Part of the Same Strategy

Because a new provider version can occasionally introduce an unexpected regression only visible under real production traffic, the same immutable, versioned image approach that enables a clean forward rollout also enables a clean, fast rollback — simply redeploying the previous known-good image — provided the pipeline retains and can quickly retrieve prior versions rather than only ever keeping the single, most recent build readily available, and provided that rollback path has itself been rehearsed at least once before it’s actually needed during a genuine incident.

Taken together, the discipline covered in this guide reflects a simple underlying idea: a custom provider’s own business logic is only as reliable as the packaging, discovery, and deployment machinery that gets it safely into a running server in the first place. Treating that machinery with the same seriousness as the logic itself — automated, tested, versioned, and reviewed deliberately across every Keycloak upgrade — is what turns a custom Keycloak extension from a fragile, occasionally working add-on into genuinely dependable production infrastructure.