What Keycloak customization covers
Keycloak customization changes how sign-in looks and behaves for your users without altering Keycloak's core code. The work falls into three change types: themes for login and account pages, custom authentication flows and authenticators for non-standard sign-in steps, and service provider interface (SPI) extensions such as custom user storage providers or event listeners. Each type sits at a different layer of the product, so each carries a different cost to keep working after a Keycloak upgrade.
Teams usually start this work for one of four reasons: branding the sign-in and account pages to match the organization, adding a sign-in step that the standard flows do not cover, connecting a user store that is neither LDAP nor Active Directory, or exporting login and admin events to an audit or SIEM system. Each trigger points to a different change type, so the first decision is to map your requirement to one of the three types before estimating anything.
The short answer: teams with strong Java and Keycloak internals experience often keep theme edits in-house, since themes are mostly FreeMarker templates, CSS and message bundles. SPI work and the upgrade testing around it are more commonly outsourced, because custom Java providers depend on internal interfaces that can change between releases and need regression tests against each new version. Confirm the current theme and SPI guidance against the Keycloak server developer documentation for your target release before you assign the work.
What the work includes
Keycloak customization is delivered as a set of work packages, each with a named deliverable. The written scope fixes which packages are in and out before any build starts.
Login and account theme development
Custom FreeMarker templates, CSS and static assets for login, registration, password reset and account pages, plus template overrides and message bundles for each supported language. Check which Keycloak theme types your version exposes, and confirm that every custom page still renders after a theme-layer change in a new release.
Custom authenticator and flow design
Authentication flow design with custom authenticators where the built-in executions cannot express the sign-in policy, such as step-up conditions or device checks. The deliverable is a documented flow diagram per client or realm, with each execution's requirement level and fallback behavior. Confirm which flows are bound to which clients before cutover.
User storage and event listener SPIs
Service provider interface implementations for custom user storage, which connects Keycloak to an external user store, and for event listeners that push login and admin events to your SIEM or audit pipeline. Each SPI is tied to the Keycloak version it was built against, so the handover records the interface versions used and the code paths that depend on them.
Provider packaging and build pipeline
A repeatable build that compiles providers and themes into deployable artifacts, versions them and deploys them to each environment. The pipeline should run the same artifact from development through production, so the team can confirm which build is live and roll back to a known previous artifact.
Automated tests against a target version
Automated tests that run custom providers, themes and flows against the specific Keycloak version you have chosen as the target, with the version pinned in the test configuration. Tests should cover login success and failure paths, token claims and the custom SPI behavior. Ask which test environment will be used and who owns it after handover.
Handover pack with upgrade runbook
A handover pack containing the source repository, a change log that maps each customization to its business reason, and an upgrade runbook that lists which items must be retested or rewritten for a new Keycloak release. Upgrade cost depends on how many SPIs and theme overrides you carry, so the runbook is the artifact that lets your team estimate it.
What drives cost and duration
Each row names a factor that changes the build and upgrade effort for Keycloak customization, why it matters, and how to keep it contained.
| Driver | Why it changes cost or effort | How to keep it down |
|---|---|---|
| Login and account screens, brands and realms | Each distinct login, registration, consent or account page is a separate template set to build, translate, test on each browser and re-check after every Keycloak upgrade. Each brand or realm multiplies that work. | Limit template overrides to the pages you truly need, share one theme across brands with variable styling, and confirm the minimum set of screens your sign-in journey requires before design starts. |
| Custom authenticators and flow branches | Each custom authenticator is Java code that must be built, tested against each flow branch and kept compatible with the SPI contracts. Branching conditions multiply the paths a tester must cover. | Reuse standard flows and built-in conditional steps where they fit, keep to one custom authenticator per decision, and write down the expected path for each branch so testing is bounded. |
| Custom user store: writes, transactions or read-only lookup | A read-only lookup provider is the smaller build. Write support, transactional behavior, and conflict handling for password changes or profile updates add design, failure-mode testing and data-protection review. | Start with read-only lookup if the business allows it, agree a stable data contract with the system that owns users, and define how failed writes are retried and reported before coding. |
| Event listeners and destinations | Each listener is custom code that runs on sign-in and admin events. Every destination (SIEM, message queue, data warehouse) adds connectivity, retry logic, volume planning and an owner. | Limit listeners to events you must keep, send them to one approved destination where possible, and confirm the event types needed for your audit or detection use cases up front. |
| Languages and accessibility requirements | Each supported language needs translated messages and layout checks. Accessibility testing of custom pages with assistive technology adds review cycles that standard pages may not need. | Confirm the list of languages and the accessibility standard your organization must meet, keep custom copy in message bundles rather than hard-coded text, and test the highest-risk pages first. |
| Number of environments and realms | Customizations must be promoted through development, test and production, and each realm may carry its own flows and themes. Configuration drift between environments is a common source of rework. | Keep realm configuration as code or exported files, promote through the same pipeline each time, and limit the number of realms to those that hold distinct security boundaries. |
| Integration with external systems and their test availability | A user store, event destination or identity check that depends on a system without a test instance slows delivery and forces mocks that may not match production behavior. | Ask the owning team for a test endpoint and sample data early, agree the API or data contract in writing, and confirm the test availability and change notice period before build begins. |
| Compliance evidence for changed sign-in behavior | Changes to authentication flows, password handling, MFA steps or audit events may need documented design decisions, test records and change approvals that an assessor can review. The evidence work often takes longer than the code. | Record the sign-in behavior before and after each change, keep test results and approvals in the change record, and ask your assessor which evidence they expect for authentication changes. |
Project phases and outputs
The sequence takes a customization from agreed requirements to a tested, packaged and documented change your team can upgrade, and the schedule follows the agreed scope.
Confirm flows, identity sources and target version
DeployOpen and your identity team map current sign-in flows, client applications, identity sources such as LDAP or Active Directory, and the Keycloak release you will target. Output: a written requirements document and an inventory of the themes, flows and SPIs the customization must support. Done when the named owners sign off on scope.
Design themes, flows and SPI interfaces
The design phase sets the theme structure, draws the authentication flow diagrams, and specifies each SPI interface with the data it reads and writes, including any user storage or event listener mapping. Output: a design document reviewed by your security and identity owners. It is complete when every custom flow step has a named owner and a planned test case.
Build themes, providers and tests
Engineers write login and account themes, custom authenticators and SPI providers, then add unit tests for provider logic and integration tests against a Keycloak instance running the same release as production. Output: a versioned source repository, packaged artifacts and a test report. Done when the suite passes in the build pipeline.
Validate in staging on the target release
The packaged customizations are deployed to a staging environment that matches production: the target Keycloak release, the same database engine, TLS, reverse proxy rules and realm configuration. Testers run sign-in, MFA, account and admin scenarios end to end. Output: a signed test record and a list of accepted defects. Done when no blocking defects remain open.
Package and roll out to production
DeployOpen packages the artifacts into your deployment method, either a plain Keycloak server or the Keycloak Operator with its custom resources, and applies the change through your change process. Output: a deployment record listing the versions and checksums deployed, plus a tested rollback procedure. Done when production sign-in checks pass.
Hand over the upgrade runbook
Your team receives the source, build instructions, configuration, an upgrade runbook and a list of customizations that need retesting for each new Keycloak release. Training covers the staging workflow and the test realm. Output: an accepted handover pack. Done when your engineers have rehearsed one staging run themselves.
What usually goes wrong
Most Keycloak customization failures appear after an upgrade or a deployment change, not during the first build. Each pattern below has a prevention step to plan into the build and the release process.
Theme overrides break after upgrade
Login and account themes override Keycloak's FreeMarker templates and message keys, so a release that changes a template's fields or a message key can break a sign-in page without any code error. Diff each overridden template against the new base theme before upgrading, keep overrides minimal, pin the Keycloak version, and run automated sign-in page checks in staging.
Providers tied to internal APIs
Custom SPI providers that depend on internal classes instead of the published SPI interfaces can fail to compile or load when a minor release changes those classes. Build only against documented SPI interfaces, pin the Keycloak version in the build file, and run a compile and contract test suite on each candidate version before it reaches production.
Untested behavior changes in upgrades
Minor releases can include breaking changes that are opt-in, and upgrade notes list new defaults that take effect without a configuration change. The 26.8 notes, for example, enforce SMTP StartTLS without plaintext fallback, require signature validation of backchannel logout tokens from external providers, and persist login failures to the database by default. Test mail delivery, logout and database growth in staging before upgrading.
Slow or non-idempotent user storage
A user storage provider that calls an external directory on every lookup can slow sign-in, and one that creates or updates local records without idempotent logic can produce duplicate or inconsistent users when Keycloak repeats a lookup or import. Load test lookup and import paths at production-sized user counts, and confirm that repeated calls return the same result.
Event listeners blocking or losing events
Event listeners are invoked during login and admin operations, so a slow or failing call to an audit store or message broker can delay or fail sign-in, and events can be lost if the listener errors without retry. Set timeouts and retries, decide which failures are acceptable, and check in staging that events reach the audit store under load and during a target outage.
Providers missing from deployment
A provider JAR that works on a developer's local server may never reach the container image or the Operator configuration, so production starts without it. Make the provider build part of the image pipeline, confirm the deployed image contains each provider, and check that the Keycloak Operator resource references that exact image tag in staging before promotion.
What teams keep in-house and what they outsource
This table compares, for each Keycloak customization task, the skills it needs and whether teams usually keep it in-house or hand it to a partner, so you can see where your own staff are needed on an ongoing basis.
| Customization task | Skills needed | Usually in-house or outsourced |
|---|---|---|
| Theme markup and styling | Front-end and FreeMarker template work, CSS, accessibility checks on login pages | Often in-house for branding that changes with the product; outsourced for the first build when the team lacks template skills |
| Message translations | Localization practice, Keycloak message bundle structure, review by native speakers for security-sensitive wording | Usually in-house for ongoing content; the initial locale set is often outsourced with the theme |
| Authenticator logic | Java and Keycloak SPI knowledge, authentication flow design, identity protocol knowledge, security testing of sign-in paths | Often outsourced for the first build and reviewed in-house, because a mistake here can lock users out or weaken MFA |
| User store adapters | Java and Keycloak SPI knowledge, directory and database protocols, SRE for connection and failure handling | Usually outsourced for the initial build, with in-house ownership of the source system and its data rules |
| Event listener destinations | Java and Keycloak SPI knowledge, log and SIEM integration, SRE for delivery reliability | Often in-house when the destination already exists in your operations tooling; outsourced when it is a new pipeline |
| Build and CI for providers | Java build tooling, container packaging, CI pipeline design, identity protocol knowledge for regression tests | Mixed: partners often set up the pipeline, and in-house engineers take over the release steps |
| Upgrade testing against each new release | Keycloak upgrade notes reading, realm and provider regression testing, SRE for database migration rehearsal, security testing | Usually a recurring cost that is kept in-house with partner support; the partner's value is most visible in the first upgrade cycle, when custom providers and themes are checked against changed behavior for the first time |
| Security review of sign-in changes | Security testing, identity protocol knowledge, threat modeling of authentication flows | Often outsourced for an independent review, with in-house approval before release |
| On-call support for failed sign-ins | SRE, Keycloak log and metrics analysis, identity protocol knowledge to trace token and flow failures | Usually in-house, because only your own team can act on user, directory and application issues around the clock |
How the work changes by starting point
A new deployment with one brand is the simplest starting point. The work centers on one realm, one set of login and account themes, and a defined set of flows and providers built from a clean baseline.
- Scope: one brand theme (login, account and email templates), a standard browser flow with any required custom steps, and the SPIs your applications actually need.
- Effort drivers: the number of screens and languages in the themes, how many custom authenticators or event listeners are needed, and whether a custom user storage provider is required at all.
- Testing: sign-in, registration, password reset and MFA enrollment across the browsers and devices your users use, plus a check that each custom provider loads on a fresh start.
- Confirm first: which login journeys are truly custom, whether a directory already holds the users, and the database and hostnames you will run on.
- Upgrade cost: build custom providers against the release you will run, so the first upgrade does not start from unplanned rework.
An estate with several realms or brands repeats the same customization work across each one. The main decisions are which assets are shared and which vary, and how changes reach every realm consistently.
- Scope: a shared theme base with per-brand overrides, separate authentication flows where realms differ, and a single provider build used by all realms.
- Effort drivers: the number of brands, how far their login journeys diverge, and whether realm configuration is managed as code or by hand.
- Testing: a matrix of realm and brand combinations for the critical journeys, with particular attention to redirect URIs, email branding and locale settings.
- Confirm first: which realms must stay separate for policy reasons, who owns each brand's assets, and whether any realm needs a different provider version.
- Upgrade cost: every realm must be retested on each upgrade, so the number of realms multiplies test effort even when the code change is small.
An upgrade starts from working themes and providers written for an older release. The work is to port them to the target version, verify behavior, and migrate the database.
- Scope: port each theme template and SPI, review the upgrade notes for the versions you cross, and plan the database schema migration.
- Effort drivers: how many custom providers depend on internal APIs, how much the templates diverge from the defaults, and how many minor releases lie between your version and the target.
- Testing: run the ported assets against a copy of production configuration and data, and compare sign-in outcomes with the current system.
- Confirm first: whether the target release changes defaults your flows rely on, whether schema migration will run at startup or manually, and who holds the source code for each provider.
- Upgrade cost: the largest unplanned cost is usually provider code that no longer compiles, so inventory every custom artifact before estimating.
On Kubernetes with the Keycloak Operator, custom providers must be built into the container image rather than copied onto a running server, and updates follow a controlled approval process.
- Scope: a build pipeline that compiles providers and themes into the image, realm and client definitions as custom resources, and an operator update process.
- Effort drivers: how many providers need image builds, how the image pipeline is tested, and how realm imports are managed across environments.
- Testing: deploy each image to a staging cluster, confirm providers and themes load, and verify the operator and Keycloak versions together before promotion.
- Confirm first: whether your change process accepts manual operator update approval, which registry and build tooling you use, and how database connectivity is secured.
- Upgrade cost: each Keycloak version change requires a rebuilt image, so provider code and pipeline maintenance recur with every release you adopt.
In an air-gapped or restricted network, the build and runtime depend on artifacts that must be brought in ahead of time. Nothing can be fetched during a build or a deployment.
- Scope: a mirrored set of base images, Maven dependencies, theme build tools and the operator bundle, plus an internal artifact repository for providers.
- Effort drivers: the number of transitive dependencies to mirror, how often artifacts must be transferred across the boundary, and how themes are compiled offline.
- Testing: perform a clean build with network access disabled, then verify that every custom provider and theme loads on the target platform.
- Confirm first: the approved transfer process and its lead time, whether a dependency scan is required before import, and which signing or checksum controls apply.
- Upgrade cost: each upgrade repeats the mirroring and transfer cycle, so the artifact list and transfer process should be documented and repeatable from the start.
What you need to provide
Before design starts, several decisions and inputs must be in place. Each one has an owner on your side, and the implementation cannot be scoped or sequenced without them. Name these people in the statement of work and confirm they can give the time the work requires. The product owner for sign-in flows decides which journeys change (login, registration, password reset, MFA enrollment, account recovery) and signs off on the final behavior of each one.
Technical inputs come from the platform and security teams. Confirm the target Keycloak version and whether you will run the community build or the Red Hat build of Keycloak, because the theme and SPI APIs change between releases and the upgrade cost of a customization depends on that choice. Provide source control and CI access for themes, providers and flow exports, and a staging environment that matches production in database engine, reverse proxy headers, hostname settings and TLS termination. A staging system that differs in these settings will hide the behavior that matters most for login redirects and cookies.
Custom user storage needs the most input. Supply the user store schema, the fields Keycloak must read and write, the access account and its permissions, and the rules that decide which system is the source of truth for each attribute. For event listeners, name each destination (SIEM, log platform, data warehouse), the event types it must receive, and its retention rules. Your security reviewer must approve any change to authentication behavior, including new flows and changed token or session handling, before release. Brand assets, copy and content approvals come from marketing or legal and should be scheduled early, since every theme change needs them.
Questions buyers ask before hiring help
What does Keycloak customization cost and what drives it?
Cost depends on the kind of change, how many flows and clients it touches, and how often it must be carried through upgrades. Themes and message text are usually the smallest line item, while custom authentication flows and SPI extensions add design, coding and test effort. Ask for the quote to separate discovery and design, build, testing in a realm that matches production, deployment through your pipeline, and handover. Ask which items are one-time and which recur each time Keycloak ships a new release. DeployOpen works from a written fixed scope, so the quote follows from the list of changes you agree on.
Can a theme change be done without a developer who knows Java?
Yes, for most branding and text changes, though you should confirm the approach against the Keycloak version you run. Login and account themes are built mainly from templates, stylesheets, scripts and message properties, so a web developer comfortable with those files can handle layout, colors and wording. Changes that alter behavior, such as new form fields tied to user attributes, usually need server-side code, which means Java. Plan a short review of each theme after upgrades, because template changes can break when the markup changes between releases.
Why do SPI extensions cost more to keep working than themes?
SPI extensions run as Java code inside the Keycloak server, so an upgrade can change the interfaces they depend on. A theme mostly depends on page templates and styles, which are easier to compare and retest. A custom user storage provider or event listener also touches user data, sign-in decisions or audit records, so each release needs regression testing of those paths before production. Upkeep includes rebuilding against the new version, fixing compile or behavior changes, and keeping build pipelines and library versions current. Ask any partner which SPIs they would maintain and which tests they would repeat each time.
What happens if a custom provider breaks after a minor release?
First, establish whether the break came from the upgrade or from your own change, which is why versions are pinned and tested in a staging realm before production. Keycloak plans four minor releases a year and says breaking changes in a minor release will be opt-in, so a plain version bump should not change behavior silently. Custom code can still fail against new internals, though. The usual response is to roll back to the previous image, reproduce the failure in staging, patch or rebuild the provider, and rerun login tests before promoting it again. Ask whether emergency fixes are covered and how quickly they can be scheduled.
How long does Keycloak customization take, and what makes the timeline move?
No duration can be given until the scope is written, because the timeline follows the number of flows, clients and SPIs and the number of environments that must be updated. The biggest delays usually come from unclear login requirements, identity sources that need test accounts, approvals for changes to production realms, and the number of upgrade cycles the work must survive. Themes usually finish faster than custom flows or providers, since those need design decisions and wider testing. Ask for milestones tied to written deliverables, and check what depends on your side, such as access to a test directory or sign-off from application owners.
Can we run Keycloak customization ourselves and bring in a partner only for upgrades?
Yes, if your team can build and test what it owns and a partner can cover the parts that are hardest to keep current. Themes and simple text changes are often manageable in-house. Custom flows and SPI extensions are where upgrade work accumulates, so a split model should assign those explicitly to one party. Read the upgrade notes for each release, such as the Keycloak 26.8 notes, to see which changes would reach your code. DeployOpen offers ongoing support and upgrades as retainers, so ask what a retainer covers, which tests it includes, and whether the handover lets your team run the work without a partner.
How DeployOpen delivers Keycloak customization
DeployOpen scopes, builds, tests, documents and hands over Keycloak customizations inside infrastructure you control, so themes, authentication flows and SPI extensions are written down, verified in a non-production realm and maintained against the release line you run. Engagements are fixed-scope, with the scope agreed in writing before work starts.
How we scope
- The written scope lists each login or account theme, authentication flow and SPI extension, with the realms and clients each one touches.
- Each custom component is recorded with its upgrade cost, so you can see which changes need rework at every Keycloak minor release.
- Scope names the Keycloak version and database you run, and states whether a Red Hat build of Keycloak subscription is in use.
How we build
- Themes are built on Keycloak's theme mechanism and kept in version control, separate from realm configuration exported from the admin console.
- Custom authentication flows and SPIs are developed against the Keycloak release you run, with unit and integration tests that cover login paths.
- Build output is packaged for your container image or Operator deployment, so the same artifact moves from test to production.
How we hand over
- Handover includes source code, build instructions, realm export files and a record of every customization and its upgrade impact.
- Testing covers sign-in, password reset, brokered logins and token issuance in a realm that mirrors production before any change goes live.
- Operator runbooks describe how to apply an upgrade to each custom component and how to roll back a failed theme or SPI deployment.
How we support
- Ongoing support, upgrade work and continuous testing for custom components are available as a retainer, scoped in writing.
- Each Keycloak minor release is reviewed against your custom components and its upgrade notes before your team applies it.
- Ask any provider how they will test SPIs and themes after a Keycloak upgrade, and what they will deliver if a change breaks sign-in.
