Keycloak adapter migration: what the move involves and how much effort it takes
Each application still bound to a deprecated Keycloak WildFly, servlet or Spring adapter needs its client-side sign-in code replaced with a standard OpenID Connect library before the Keycloak server moves forward. The work is per application, so effort depends on how many applications exist and how much custom token handling each one contains. The adapter is a library loaded into each application and runs there, separate from the Keycloak server, so every change lands in that application's build, configuration and deployment pipeline. Teams often underestimate this because the server upgrade looks like one project while the application changes look like many small ones. Treat each application as its own change with its own owner, test plan and cutover date.
In short, the library swap is usually the smaller part of the work. Most of the time goes to building an accurate inventory, testing how each application handles tokens and logout, and coordinating those changes with the server upgrade. The inventory has to record the adapter type and version, the client configuration each application depends on, how roles and groups are read from token claims, and whether the application runs as a confidential or public client. Token and logout testing then checks sign-in, token refresh, session expiry, role-based access and single logout across the applications that share a realm. Those tests often expose behavior that the library change alone would not reveal.
Several decisions shape the effort. Choose one OpenID Connect library per language or framework so that teams do not maintain several sign-in patterns, and confirm with the library's maintainers that it supports the flows your applications need, including the authorization code flow with PKCE for public clients. Decide where tokens are held, in the server-side session or in the browser, because that choice changes how logout and token refresh are implemented. Map every custom filter, interceptor or authorization check that reads an adapter-specific object, since those are the places where a library swap breaks quietly. Ask each application owner which claims their code depends on and keep that list as a test input.
Sequence the adapter work with the server upgrade in the same program, and run both through the Keycloak upgrades group so that version changes, database migration and client configuration move together. Stage each migrated application against the target server version in a lower environment before cutover, and keep the old and new client settings available for the window in which both paths may be live. Read the release notes for your target Keycloak version before testing logout, because logout token handling has changed in recent releases. For example, the 26.8 upgrade notes make signature validation of backchannel logout tokens from external providers mandatory, so confirm which of your identity brokers send such tokens.
Ask for a written scope that lists each application, its adapter, the token and logout tests it needs and the cutover order, with effort shown per application. Ask which items are one-time, such as the migration itself, and which recur, such as keeping the library current and rerunning token tests after each Keycloak upgrade. Applications that cannot change on schedule are the main schedule risk, so name an owner for each one and decide early whether a temporary path is acceptable. A quote should follow from that scope, not from an estimate of the server upgrade alone.
Which adapter features map to standard OpenID Connect libraries and which need redesign
This table compares each deprecated Keycloak adapter feature with its closest standard OpenID Connect equivalent and notes where application code must change. Read the code change notes first, since they show where the library swap alone will not be enough. Treat every mapping as a starting point to confirm, because exact claim names and library support must be checked against the Keycloak server administration guide and your chosen library's documentation.
| Source capability | Standard OIDC equivalent | Migration notes |
|---|---|---|
| Login redirect and authorization code flow | Authorization code flow with PKCE through a standard OIDC client library | Adapter handled redirects and callbacks. Code change: yes, login entry points and callback routes move to the library. Confirm redirect URI registration in the client settings. |
| Token validation and signature checks | Signature verification against the realm keys endpoint, with issuer, audience and expiry checks | Confirm the library loads keys from the realm metadata and validates the issuer exactly. Code change: usually no if configured, yes for custom checks. |
| Role and group claim mapping | Roles and groups read from token claims and mapped into application authorization | Claim names depend on the client scope and mapper setup. Code change: yes, adapter role checks must be rewritten against the mapped claims. |
| Session handling | Application session managed by the library's middleware, with refresh tokens for renewal | Adapter session behavior does not carry over automatically. Code change: yes, session storage, timeouts and refresh logic need explicit design. |
| Back-channel logout | Back-channel logout endpoint that receives and validates signed logout tokens | Library support varies, so confirm it. Keycloak 26.8 requires signature validation of backchannel logout tokens from external providers. Code change: yes. |
| Front-channel logout | Front-channel logout through browser requests from the relying party's logout page | Depends on browser behavior and cookie settings, so test across target browsers. Code change: yes, if the application hosts the logout endpoint. |
| keycloak.json adapter configuration | No direct equivalent; replaced by issuer URL, client ID and client secret in application configuration | Map each keycloak.json field to a library setting. Code change: yes, the file loader is removed, but values move to environment or secret stores. |
| Spring adapter properties (keycloak.* keys) | Spring Security OAuth 2.0 client and resource server properties | Adapter properties do not map one-to-one. Check each key against Spring Security documentation. Code change: yes. |
| Adapter-specific principal and user types | Custom principal built from ID token and user info claims | Application code that depends on adapter classes needs redesign. Code change: yes, plan this as a separate work item. |
Why token handling and logout break first when applications move off adapters
The first failures after moving off the deprecated adapters usually appear where the adapter made decisions silently. The WildFly, servlet and Spring adapters validated tokens, mapped roles and managed logout on the application's behalf. A standard OpenID Connect library makes each of those decisions explicit, so the application team must confirm every one. Start with token validation. Check that the library verifies the issuer, the audience, the signing keys and the expiry against the realm your server actually issues tokens from. Then confirm that a token failing any of these checks is rejected by the application, and test that with deliberately altered or expired tokens rather than assuming the library's defaults match the old adapter.
Role handling is the next place where behavior changes without an obvious error. Adapters read roles from specific claims in the token, and a library reads whatever claim your code points it to. Identify every place the application reads roles: realm roles, client roles, or group values exposed through protocol mappers. Then confirm which claims those values appear in, and which client scopes must be requested for the mapper output to reach the token. Test with at least one user who holds realm roles and another who holds client roles only. Compare the authorization decisions the application makes for each user before and after the switch, because a missing claim often produces a denied request instead of an error message.
Refresh and session expiry depend on three separate clocks: the access token lifetime, the refresh token behavior and the server-side SSO session. Adapters often refreshed tokens in the background, so the application rarely had to decide what happens when a token expires. A standard library leaves that decision to your code. For each application, decide whether it refreshes silently, redirects the user to sign in again, or returns an error to an API client. Then confirm the realm and client session settings with your Keycloak administrators, and test an idle session, a long-running session and a session that ends while the user is working in another browser tab. Record the observed behavior and compare it with what your users are told to expect.
Single logout depends on the client registration as much as on the application code. Confirm the front-channel and back-channel logout URLs configured for each client, and confirm the application's logout endpoint is reachable from the Keycloak server on the network path your deployment uses. Back-channel logout sends a logout token from Keycloak to the application, and the receiving library must validate that token before it ends the local session. The Keycloak 26.8 upgrade notes make signature validation of backchannel logout tokens from external providers mandatory, so logout paths that worked before may fail in testing. Identify which of your applications receive logout signals that originate from external identity providers, and test those flows on a staging server running the version you plan to adopt, currently 26.8.1 at the time of writing.
Plan the verification as a test matrix rather than a single sign-in test. For each application, list the token checks, role claims, expiry scenarios and logout paths, then record the expected result and the observed result from staging. Ask your partner or internal team to show logs for rejected tokens and failed logout requests, because these are the first signals that a validation step is working or failing. Treat any logout path that cannot be tested in staging as an open risk, and agree with the business owner how that risk will be handled before the server upgrade proceeds.
Documented paths for adapter replacement, client configuration and verification
The migration relies on a small set of documented Keycloak materials, not on an adapter conversion tool. Each path below covers one part of the work: version changes, client and token settings, client and realm configuration as code, and verification during a parallel run. Confirm the exact export and import method for your current version in the upgrading guide before you plan the cutover.
Upgrading guide for version changes
The Keycloak upgrading guide lists changes that affect the release you are moving to, including changes to token handling, logout and client configuration. Read the notes for every version between your current server and the target. Your team still has to map each listed change against the adapters, libraries and clients it runs, and decide which flows to retest. Confirm the export and import method for your version in this guide.
Server administration guide for clients
The server administration guide documents client scopes, protocol mappers, logout behavior and token settings. These settings take over responsibilities an adapter previously handled, so each one needs a deliberate value. Your team still decides which claims each application needs, how long tokens live, and which redirect and logout URIs are allowed. Check each decision against the application's test cases, since the old adapter defaults may not carry over.
KeycloakOIDCClient for clients as code
The Keycloak Operator provides a KeycloakOIDCClient custom resource for teams that manage clients declaratively in version control. It suits clients that must be created consistently across development, staging and production. Your team still writes the manifests, keeps client secrets out of the repository, and reviews changes through the same process used for application code. Confirm which fields your Operator version supports before you build shared templates.
KeycloakRealmImport for realm configuration
The KeycloakRealmImport resource imports realm configuration into a Keycloak instance managed by the Operator. Teams use it to reproduce a tested realm in a staging environment before changing production. Your team still decides what is exported from the source realm, which values are environment specific, and how secrets are supplied. Confirm how imports behave when the target realm already exists, because that behavior shapes your rollback plan.
Prometheus metrics for parallel run
Keycloak exposes Prometheus-format metrics at /metrics on its management interface when started with --metrics-enabled=true. During a parallel run, these metrics show login activity and cache behavior while the old and new integrations serve the same users. Your team still has to scrape the endpoint, restrict access to the management interface, and set alert thresholds from its own baseline. Confirm which optional HTTP request and cache histograms your version exposes in the observability guide.
The sequence: inventory, pilot, parallel run, cutover and decommission
This sequence moves each application from a deprecated adapter to a standard OpenID Connect library while the current Keycloak server keeps running. It produces a verified inventory, one proven pilot, a period where both authentication paths work, documented cutovers and a clean removal of old dependencies. Each step closes with a written exit check that the next step depends on.
Inventory every application, adapter and client
The client's application owners and identity team complete the inventory, with DeployOpen supporting the review of configuration and code. For each application, record the adapter type and version, the Keycloak client and its settings, any custom token mappers or claim logic, and the logout path, including front-channel and back-channel behavior. Identify applications that share a client, because changing one may affect the others. The step is done when every application has a row in the inventory, every shared client is flagged, and the application owners have signed off on the list. The number of applications and the number of shared clients determine how long the later steps take.
Pilot one low-risk application
The identity team, with DeployOpen's platform engineers, selects one application with low business impact and few custom token rules, then moves it to the chosen OpenID Connect library. The pilot runs against a non-production realm that mirrors the production client settings. Testing covers login, the claims the application reads from the ID and access tokens, token refresh, and single logout. Any gap in the inventory found here goes back to Step 1 before more applications move. The step is done when the pilot passes every test case in a written test plan and the application owner accepts the result.
Run adapter and library paths in parallel
For each application in the next group, the platform team keeps the old adapter path and the new library path working against the same realm. Users are split between the two paths, or test traffic runs through the new path while production users stay on the old one. The team watches Keycloak metrics, which are exposed in Prometheus format on the management interface when metrics are enabled, along with application logs for token validation errors, refresh failures and logout mismatches. The step is done when the error rates on the new path match the old path over the agreed observation period and no open defect blocks cutover. Duration depends on how many applications the inventory placed in each group.
Cut over each application in a planned window
The change owner schedules a window for each application and confirms the rollback steps in a runbook before the window opens. The runbook names who decides to roll back, the configuration to restore, and how to confirm the rollback worked. During the window, the team switches the application to the new library, runs the pilot test cases again against production, and monitors logins and logouts. The step is done when the application passes the post-change checks, the rollback runbook has been tested or reviewed, and the change record is closed. Cutovers should not start for shared-client applications until the group has been reviewed together.
Decommission adapters after server upgrade
Once every application runs on the library path and the Keycloak server upgrade has been completed and verified, the identity team removes the old adapter dependencies, configuration files and redundant client settings. Removal waits for the server upgrade because the old adapter path may still be needed as a fallback until then. The team confirms that no application still sends requests through the removed client settings by checking logs and metrics for a period agreed in advance. The step is done when the build artifacts no longer include the deprecated adapters, the removed client settings are documented in the change record, and the identity team signs off on the final state.
How to test token handling and logout before the Keycloak server upgrade
Build a written test matrix before the Keycloak server upgrade starts, and run it against every application that will move off its deprecated adapter. The matrix is the only reliable way to show that sign-in, token contents and logout behave the same after the server changes version. Each row is one scenario, each column is one application or client, and each cell records the expected result, the observed result and the date of the run. Without this structure, teams tend to check whether users can sign in and stop there, which misses the failures that matter most in a regulated environment: wrong roles, sessions that outlive a logout, and tokens that expire at the wrong time. Rows to include. Cover sign-in for each user type the realm serves: local users, users from LDAP or Active Directory federation, and users arriving through an identity broker such as an external OIDC, OAuth or SAML provider. Brokered and federated users often carry different attributes, so test them separately rather than assuming one successful login proves the others. Add claim checks for roles and groups in the access and ID tokens, and confirm that the application reads them from the claims it expects. Mapper changes made during the migration are a common source of silent authorization drift.
Next, test token expiry and refresh. Confirm the access token lifetime, refresh token behavior and session idle and maximum settings that apply to each client, and check that the application refreshes tokens without forcing an interactive login or dropping the user mid-task. Then test logout in three forms. First, log out from one application while another application remains open in the same browser, and confirm what the second application does on its next request. Second, confirm back-channel logout delivery: the server should notify each registered client endpoint, and you should verify that each application receives the message, validates it and ends its local session. Third, repeat the logout tests after the server is upgraded in staging, because the logout path is one of the behaviors most likely to change. Environment. Run the matrix in a staging environment built on a copy of the production realm configuration, with the same clients, mappers, identity providers and user federation settings. The staging server should run the target version that you plan to move to, so that the baseline reflects the upgrade path and not only the current release. Keep test accounts separate from production users and make sure the staging copy cannot send real notifications or reach production identity sources. Confirm the exact logout, back-channel and token settings against the Keycloak server administration guide for your target version before you rely on the expected results, since defaults and option names can differ between releases.
Record every run so the upgrade has a baseline to compare against. For each cell, capture the server version, the client version, the configuration export or revision reference, the test account used, the observed token claims (with sensitive values redacted), the logout result per application, and any error or log entry. Store these records with your change ticket so reviewers can see what was tested and when. Run the same matrix on the current server version first, then again on the staging target after the upgrade. Any difference between the two runs is either an intended change you can document or a defect to fix before production. Decisions to make early. Agree who signs off each row, which failures block the cutover, and how long a deprecated adapter may remain in service if a single application cannot pass. Ask your application owners to confirm their session timeout and logout requirements in writing, because the matrix can only check behavior you have defined. Ask the team delivering the work to state how the matrix will be executed, what evidence will be provided, and what happens to rows that fail. Keep the baseline records after the upgrade so that a later incident can be traced to a specific configuration change.
What drives the cost and duration of an adapter migration
This table lists the factors that change how much work an adapter migration takes and how long it runs, along with what to request when comparing proposals. Read each row against your own application inventory, because the same driver can add little work in one estate and a great deal in another. Effort is set from the written scope, which should list applications, libraries, environments and acceptance tests, so no published price applies.
| Driver | Effect on effort | What to ask for in a quote |
|---|---|---|
| Number and type of applications | Each application needs its own code change, configuration, testing and rollback path, so effort grows with the count and with how different the stacks are. | A per-application list with framework, language version, owner and current adapter type. |
| Adapter variants (WildFly, servlet, Spring) | Each variant replaces a different integration point, such as container security config, filters or Spring Security settings, so mixed estates take more design and testing. | Confirmation of which adapter each application uses and the chosen OIDC library for each variant. |
| Custom token or role logic | Mappers, claim parsing and role-to-permission code that read adapter-specific objects must be rewritten against standard token claims and retested. | Inventory of custom claim, role and group handling, plus which claims each application relies on. |
| Clients per application | Applications that use several Keycloak clients, such as a front end and an API, need coordinated redirect, scope and secret changes and more test cases. | The client list per application, including public and confidential clients and any service accounts. |
| Federated and brokered identity sources | Logins through LDAP, Active Directory or external identity providers add claim mapping differences and more login paths to verify before cutover. | The identity sources in use, the attributes each application expects and any known claim differences. |
| Logout requirements across applications | Single logout across several applications with different session handling requires design decisions and cross-application testing that single-app logout does not. | The required logout behavior per application and whether back-channel or front-channel logout is expected. |
| Availability constraints for cutover | Strict change windows, staged rollouts or no-downtime requirements add rollback planning, parallel running and extra coordination with application owners. | The allowed change windows, rollout order, rollback approach and who approves each cutover step. |
| Test environment readiness | A production-like environment with realistic user data and identity sources shortens verification, while missing environments push testing into later, costlier stages. | Which environments exist, how they are refreshed, and who provides test accounts and test data. |
| In-house experience with the chosen OIDC library | Teams new to the library need time for design review, learning and debugging, which lengthens the build and the handover work. | Whether the work includes training, pairing or handover documentation, and the skills the partner will bring. |
What usually goes wrong in adapter migrations and how to prevent it
Most adapter migrations stall for reasons that have little to do with the new library code. The risks below tend to surface in the same places: application inventory, client configuration, token contents, logout and upgrade timing. Each card names the failure and the check that prevents it.
Undocumented applications found late
Applications that use the WildFly, servlet or Spring adapters are often owned by teams outside the identity project, so they appear only when a sign-in breaks. Build the inventory from the Keycloak client list, the application servers and the load balancer routes, then compare the three. Ask each owner to confirm the adapter version, the grant types in use and the logout URL before any migration work is scheduled.
Shared clients that break together
One Keycloak client is sometimes reused by several applications, so a change made for one application changes sign-in for the others. Before any redirect URI, scope, mapper or secret changes, list every application that authenticates with that client ID. Where possible, give each migrated application its own client, switch them one at a time, and keep the old client active until every dependent application is confirmed working.
Role claims read differently after the switch
Adapters read roles from fixed token locations, while a standard OpenID Connect library reads whatever claim the application is configured to parse. A role that appears in one claim may be missing from the claim the new library expects, so users are denied access or receive the wrong access. Capture decoded tokens for test users from the old and new flows and compare the role claims before go-live.
Logout that stops reaching other applications
Single logout depends on each application exposing a logout endpoint and ending its local session correctly. When an application moves to a new library, its logout URL, post-logout redirect URIs or front-channel handling can be left out, so signing out of one application leaves the others active. Test a full sign-out from each migrated application and confirm that every other application in the same session also ends.
Backchannel logout token validation failures
Keycloak 26.8 makes signature validation mandatory for backchannel logout tokens from external providers, so applications that receive those tokens must validate them. An application that cannot reach the realm keys, expects a different issuer or audience, or rejects the token format will fail to log out. Compare the 26.8 upgrade notes with each library's validation settings, confirm each application can reach the JWKS endpoint, and send a test logout token before the server upgrade.
Upgrades that outrun the migration
A server upgrade started before the applications leave the deprecated adapters can break every application still on them. Automatic operator upgrades can introduce the same change without a planned window, and the Keycloak Operator documentation strongly recommends manual approval mode for operator updates to avoid unintended automatic upgrades. Set the operator to manual approval, make the server upgrade a gated step that requires an agreed list of migrated applications, and rehearse it in a test environment first.
Questions teams ask before moving applications off Keycloak adapters
How much effort does replacing a Keycloak adapter with an OpenID Connect library take?
Effort is set per application by how much sign-in logic the application already carries. No effort figure was supplied for this topic, so confirm estimates against the documentation for your chosen library and the Keycloak documentation for your target version.
Effort rises with:
- Custom session handling or hand-written token checks
- Several frameworks across one estate
- Adapter-specific configuration that must be re-expressed as standard OIDC client settings
Effort falls with: a common framework that has a documented OIDC library, and client configuration kept in version control. Ask for the split between code changes, test coverage and client configuration.
What drives the time needed to migrate applications off Keycloak adapters?
The duration depends mostly on the inventory: how many applications use deprecated adapters, which frameworks they run, and who owns each one. No duration was supplied for this topic, so treat any timeline as provisional until the inventory is complete.
For each application, record the adapter and its version, the framework, the owner, the test accounts, the environments and the release calendar. Applications that share a pattern can move in one batch, while unusual ones need individual work. Ask any provider to base the timeline on this inventory and to list its assumptions in the written scope.
What must our team provide before an adapter migration starts?
The team must provide decisions, access and time windows. Work stalls quickly when any of these is missing.
- Application owners who can approve changes to login, session and logout behavior
- Test accounts that cover each role the application uses
- Non-production environments that match the Keycloak client configuration in production
- Source access and CI pipelines for each application
- Change windows agreed with operations for each environment
- Log access and a named contact for sign-in incidents
The owners should also agree on the test cases for sign-in, token refresh, logout and session expiry before code changes begin.
Can our internal team migrate off Keycloak adapters without outside help?
Yes, many internal teams can do this if they have OIDC experience, automated tests for sign-in, and enough capacity for the change windows. The deciding factors are skills and test coverage, not the adapter itself.
Outside help is most useful for the inventory, for frameworks the team has not used before, and for security testing of the new sign-in flows. DeployOpen plans, implements, tests and documents this work in infrastructure you control. Engagements are usually fixed-scope, with scope, deliverables and timelines agreed in writing before work starts. Ongoing support is available as a retainer. Compare the written scope from a provider with the same inventory your team has built.
Must we upgrade the Keycloak server before changing application adapters?
Not always, but you should confirm the order against the upgrading guide for your target version. The safest approach is to test each migrated application against the Keycloak version you will run in production, so the adapter change and the server change do not fail together.
The Keycloak 26.8 upgrade notes include changes that can affect applications, such as mandatory signature validation of backchannel logout tokens from external providers. Check these notes against your inventory before scheduling the server upgrade. If the server upgrade must come first, test sign-in and logout in a non-production environment that runs the new version.
How do we know a library change off a Keycloak adapter is complete?
The change is complete when no application depends on a deprecated adapter and every sign-in path passes tests in each environment. Confirm the exact checks against the library documentation and the Keycloak documentation for your version.
- Build: no deprecated adapter dependency or adapter configuration file remains
- Tokens: signature, issuer, audience and expiry are validated by the library
- Flows: sign-in, refresh, session expiry and logout pass for each test role
- Logout: back-channel and front-channel logout behave as the owner specified
- Operations: logs show no adapter errors after the change window
Record the results per application so the owner can sign off.
Does moving to standard OIDC libraries change how logout and token handling work?
Yes. Logout and token handling are where most application behavior changes, because the library now controls token validation and session state. Test both paths before the change window.
Test single logout across applications, token refresh near expiry, session behavior after a Keycloak restart, and the response to a revoked session. The upgrade notes for Keycloak 26.8 require signature validation of backchannel logout tokens from external providers, so confirm that your logout endpoints accept validated tokens. Ask the library documentation how it handles clock skew and key rotation, and confirm those settings in your environment.
How DeployOpen scopes, delivers and supports an adapter migration
DeployOpen plans, implements, tests and documents adapter migrations inside your own infrastructure, with the written scope agreed before work starts. Each application moves to a standard OpenID Connect library, and token handling and logout are tested before the Keycloak server upgrade proceeds. Engagements are fixed-scope, so the scope, deliverables and timeline are agreed in writing first.
How we scope
- Inventory every application using the WildFly, servlet or Spring adapter, with its Keycloak client, grant types and session behavior.
- Record login, token refresh, role mapping and logout flows so the scope names what must keep working.
- The fixed-scope agreement lists deliverables, test cases and cutover conditions; quotes follow from that written scope.
How we build
- Replace each deprecated adapter with a standard OpenID Connect library for its framework, configured against your realm and clients.
- Build token validation, including issuer, audience, expiry and signature checks, into each application's security configuration.
- Test logout in each application, including front-channel and back-channel paths, and confirm logout token signature validation before the upgrade.
How we hand over
- Deliver updated application code, configuration, and a test report covering login, refresh, role mapping and logout per application.
- Document the library versions, claim mappings, redirect URIs and the remaining adapter-dependent items your team must confirm.
- Run a knowledge transfer with your engineers so they can maintain library upgrades and future client changes without us.
How we support
- Sequence the server upgrade after application cutover, reviewing the Keycloak upgrade notes for the target release against your findings.
- Ongoing support, library upgrades and continuous testing are available as a retainer after handover.
- Confirm the planned Keycloak release cadence with your team, since minor releases can carry opt-in breaking changes.
