Keycloak WildFly to Quarkus migration: what the move involves
If your organization runs a Keycloak release from before 17 on the WildFly distribution, moving to the Quarkus distribution is a re-platforming of the server, not an in-place upgrade. The move keeps your realm data, users, roles and clients, but it changes how the server is configured, built and deployed. Your current installation likely depends on standalone XML files, custom provider JARs loaded into WildFly modules, and client applications whose redirect URIs and token endpoints still use the /auth path that newer releases no longer serve by default.
Most of the work sits in configuration and packaging. Subsystem settings in standalone.xml or standalone-ha.xml have no one-to-one equivalent in the Quarkus distribution. Its settings come from the configuration file, environment variables and command-line options, and some of them are fixed at build time while others apply at startup. Custom providers must also be compiled against the Quarkus distribution and packaged so the server loads them during the build, so a JAR that worked in WildFly will usually need rebuilding and retesting. Decide early how that build will run, whether in a CI pipeline or a container image, because the same step will repeat with every future upgrade.
The short answer on effort is that it depends on four factors: the number of custom providers and how deeply they rely on internal APIs, the amount of XML-based configuration that must be translated, the database and its migration path, and the number of clients that hard-code URLs, including the /auth path. None of these can be sized from a summary. Scope is set only after an inventory that lists every provider with its source code and tests, every subsystem setting in the XML files, every client redirect URI, token endpoint and logout URL, and every script or deployment value that calls the admin REST API. Ask any partner to base the quote on that inventory.
Confirm the target before scoping. Keycloak's current release is 26.8.1 according to keycloak.org, and that is the version the plan, provider rebuilds and test matrix should be written against unless your team chooses otherwise. Read the upgrade notes for every release between your starting version and the target. The 26.8 notes, for example, enforce StartTLS for SMTP without plaintext fallback, require signature validation of backchannel logout tokens from external providers, and persist login failures to the database by default. These changes can break working integrations even when the migration itself succeeds, so plan regression tests for mail, logout and login flows alongside the migration tests.
What maps cleanly from WildFly Keycloak and what does not
This table compares each part of a pre-17 Keycloak WildFly deployment with its equivalent on the Quarkus distribution and notes what changes during migration. Read it as a checklist: data-level items usually carry over with the database, but configuration, custom code, themes, URLs and deployment must be rebuilt, rewritten or retested. The main takeaway is that your identity data moves largely intact, while everything that points at the old server layout needs deliberate work.
| Source capability | Quarkus distribution equivalent | Migration notes |
|---|---|---|
| Realms, users, clients and roles | Same objects, stored in the migrated database | Usually carries over with the database. Compare client and role lists in a staging copy before cutover. |
| Identity providers and user federation | Same configuration, loaded from the database | Generally carries over. Retest LDAP and Active Directory bind accounts, sync jobs and brokered logins. |
| standalone.xml and jboss-cli configuration | keycloak.conf plus build-time and runtime options | Not carried over file for file. Translate each subsystem setting into keycloak.conf keys or startup options, then run the build step. |
| Custom Java providers | Provider JARs placed in the Quarkus distribution and rebuilt | Must be recompiled against the new distribution's APIs. Test each provider, because old JARs may not load. |
| Custom themes | Theme directories deployed to the new distribution | Copy, then retest login, email and account templates. Check for hardcoded paths that still include /auth. |
| The /auth context path | No longer the default path, set through configuration if kept | Redirect URIs, issuer URLs, client settings and reverse proxy rules change. Confirm the public hostname and path before cutover. |
| WildFly deployment and hosting | Keycloak Operator, OpenShift deployment or the experimental Helm chart | The Operator is installed through Operator Lifecycle Manager, the recommended method. Set operator updates to manual approval. |
| Red Hat Single Sign-On support | Red Hat build of Keycloak, a separate supported distribution | Confirm with Red Hat which distribution and support terms apply to your subscription before choosing the target. |
How the XML configuration moves to the Quarkus distribution
The standalone XML files from a pre-17 Keycloak on WildFly cannot be copied across unchanged. That server defined its datasources, Infinispan caches, logging and SPI provider settings inside the JBoss subsystem model, and the Quarkus distribution replaces that model with its own configuration system. The first task is therefore not editing a file but producing an inventory of what the old standalone XML actually does, so each setting can be given a new home or a deliberate retirement decision.
The Quarkus distribution splits configuration into two groups. Build-time options, such as the database vendor and which features are enabled, are fixed when the server is built with the build command, so changing them later means rebuilding the server image or distribution. Runtime options, such as hostnames, database URLs and credentials, TLS certificates and logging levels, can change between starts. Operators set these through keycloak.conf, environment variables or command-line flags. Teams should decide early which values belong in each group, because a build-time value set incorrectly forces a rebuild in every environment that uses that image.
Build the inventory from the running configuration, not from memory. Record every subsystem setting in standalone.xml or standalone-ha.xml, every datasource and its pool and connection parameters, every Infinispan cache and its owners, eviction and expiration settings, every SPI provider configuration, and every system property passed to the JVM through startup scripts, service units or container definitions. For each item, write down its target: a keycloak.conf key, an environment variable, a build option, a realm or admin console setting, or a retirement decision with an owner. Check each mapping against the upgrading guide and the production configuration guide. Confirm the current option names and defaults in those documents for the exact version you are targeting, since names change between releases.
Custom Infinispan and datasource changes cause the most rework. Teams often tuned cache sizes, added caches for custom providers, or changed pool limits and transaction isolation to fit their traffic. Several of these settings have no direct one-to-one equivalent in the new distribution, and some caches are managed differently in the Quarkus build. Treat each custom cache and each non-default datasource property as its own line item in the inventory, test the behavior under realistic load in a staging environment, and document the reason for every value you keep. Expect the review of these items to take longer than the mechanical edits.
Before cutover, produce a single reviewed configuration set per environment and confirm that secrets are supplied through a controlled mechanism rather than copied into files under version control. Ask the team that owns the old server to sign off on the inventory, and keep the old XML files read-only until the new deployment has passed its acceptance tests. Ask the implementation partner or internal team to state in writing which items were migrated, which were retired and which were changed, so auditors and operators can trace every decision back to the original configuration.
Which documented paths carry data and configuration across
Keycloak documents several ways to move data and configuration from a WildFly deployment to the Quarkus distribution. Some keep your existing database, while others rebuild realms or clients from exported files, declarative resources or API calls. Check each path against what it carries, especially users, credentials and client secrets.
Keep the existing database
Your current supported database can stay in place, and its schema is migrated automatically when the new server starts, which is the default behavior. For large deployments, the upgrading guide suggests running the schema SQL manually so your database team can review and schedule it. Users, credentials and client secrets already live in this database, so this path carries the most data. Confirm your database version against the supported list and rehearse the migration on a copy first.
Export and import realms
Realm export and import moves realm content into a fresh instance as files. It suits teams that want a clean target, but it is a separate data path from the database, so the export options decide what travels. Confirm with a test run whether users, role mappings and client secrets appear in the output, because exports that omit secrets need a separate step to reissue or reset them. Plan who handles those files and where they are stored.
KeycloakRealmImport resources
The Keycloak Operator can load a realm through a KeycloakRealmImport custom resource, which makes realm loading repeatable across clusters and environments. The resource is only as complete as the realm representation it contains, so review the imported content for the users, identity providers and secrets you expect. Keep the realm definition in version control, and confirm with the vendor how the Operator handles a realm that already exists.
Operator client declarations
The Operator manages KeycloakOIDCClient and KeycloakSAMLClient custom resources, so each application client is declared in YAML and reconciled into the realm. This suits platform teams that run Keycloak on Kubernetes and want client settings reviewed like other infrastructure code. Redirect URIs and secrets need deliberate handling, and you should confirm how the Operator sources client secrets before cutover. The documentation strongly recommends manual approval mode for Operator updates.
Administration REST API scripts
The Administration REST API lets scripts create realms, clients, roles and users on a running server, which suits teams that want configuration applied in a repeatable order. Scripts can read and write credential-related resources, so the service account running them needs tightly scoped permissions and its calls should pass through your change process. Test each script against a non-production realm first, and confirm which secret fields the API returns or accepts before you depend on them.
Where the /auth path change and custom providers break clients
The Quarkus distribution no longer serves Keycloak under the /auth path by default, so every client that reaches the server through that path will fail until it is changed. Before any cutover, build an inventory of each application redirect URI, OpenID Connect discovery URL, SAML metadata descriptor, reverse proxy rule, health check, monitoring target and bookmarked admin link that includes /auth. Include the places teams forget: CI pipelines that fetch discovery documents, service accounts that call the Administration REST API, and partner systems that hold a copy of your SAML descriptor. Each entry needs an owner and a dated change plan.
Some teams will want to keep the /auth prefix through configuration so that clients do not change on the same day as the server. That can be a reasonable bridge, but only if your team can confirm that the option is supported for the exact target release you plan to run. Check the Keycloak upgrading guide for the release notes on the context path, and confirm the behavior in a staging environment that mirrors your production hostnames. If the guide does not clearly support it for your target version, plan the client changes now rather than relying on a workaround that may be removed later.
Custom providers and themes are the second break point. Every JAR or theme built for the WildFly distribution has to be rebuilt against the Quarkus distribution, because the packaging, module layout and some provider interfaces differ. Test each artifact against the target release in a non-production environment, including login flows, user federation, event listeners and any custom authenticators. Then repackage the providers for the way you deploy: a container image you build, or the custom resources and images your Keycloak Operator deployment references. Ask the team that owns each provider who will maintain it after the migration, because a provider nobody can rebuild becomes the blocker for the next upgrade.
The production guide expects TLS on all communication, a reverse proxy with path restrictions, and the admin console and Administration REST API exposed on a different hostname or context path from public frontend URLs. Moving off /auth is therefore also a network design change. Your proxy rules need to route public authentication endpoints to the server while blocking or separately publishing administrative paths, and the hostnames in your certificates, redirect URIs and proxy configuration must agree. Review this with your security and network teams before the cutover, and confirm the exact proxy and hostname settings against the production configuration guide for your release.
How a Keycloak WildFly to Quarkus migration runs in sequence
The sequence moves a pre-17 Keycloak from WildFly to the Quarkus distribution in controlled stages, so each realm, client and provider is proven on the new server before users depend on it. It ends with the WildFly server retired after a rollback window defined in advance. Each stage has a written output that gates the next.
Inventory configuration, realms, clients and providers
The platform team, with each realm and client owner, lists everything the WildFly server does: realm settings, clients and their redirect URIs, custom providers and themes, the database connection, and every system that calls Keycloak. Settings stored in the standalone XML configuration must be mapped to the options the Quarkus distribution uses, and each custom provider is checked for compatibility with the target release. The output is a written inventory signed off by the owners, with a list of anything that cannot move unchanged. The step is done when every item has an owner and a planned action.
Build the Quarkus distribution with rebuilt providers
The platform team builds the target Quarkus distribution on the same database vendor the WildFly server uses, which keeps the schema migration on a supported path. Custom providers and themes are rebuilt against the new release and tested, because artifacts built for WildFly will not load unchanged. Where you run on Kubernetes, the Keycloak Operator is the recommended install route, installed through Operator Lifecycle Manager. Set its update approval mode to manual so that upgrades happen only when your team approves them, and plan for both the initial install and later updates. The step is done when the build starts against a copy of the database and reports healthy.
Import and verify a pilot realm
The team exports one representative realm from WildFly and imports it into the Quarkus server on a non-production hostname. On Kubernetes, the import can be declared with a KeycloakRealmImport resource so that it is repeatable. Users, roles, groups, identity providers and federation links are compared with the source realm, and any setting that did not import is logged for a fix. Client secrets that do not export cleanly are reset under change control. The step is done when counts and key settings match the source and the admin console shows no import errors.
Test login, logout and token handling per client
Testers sign in to every client type in the pilot realm, covering browser applications, APIs that validate tokens, service accounts and any SAML clients, and confirm that the expected claims and roles arrive. Logout is tested from each application and through the single logout path, and backchannel logout is checked wherever it is used. Token lifetimes, refresh behavior and signature validation are verified against each application's library. Applications still using deprecated adapters are moved to standard OpenID Connect libraries before cutover. Confirm the target release's upgrade notes on backchannel logout token validation. The step is done when each client has a signed test record.
Run a parallel environment for rollback
The new server runs beside WildFly with the same realms, and the WildFly server stays fully available as the rollback target. A named group of users is pointed at the new hostname for testing while production traffic stays on the old server. Testers log defects, and the team reviews login failures and metrics on the new server; Keycloak exposes Prometheus-format metrics at /metrics on its management interface when started with metrics enabled. Changes made in either environment during this period must be reconciled, so the team agrees which system is the source of truth. The step is done when the test group signs off and every open defect has an owner.
Cut over DNS, database and client redirects
In a change window agreed in advance, the team stops writes to the WildFly server, runs the database migration, and then moves the public hostname to the new server through DNS or the reverse proxy. Keycloak migrates its schema automatically at startup by default, or administrators can apply the SQL themselves, which the upgrading guide suggests for large deployments. Final redirect and post-logout URIs are updated in every client, and check any /auth path prefix that clients or the proxy still use. The reverse proxy should restrict paths so the admin console and Administration REST API sit on a different hostname or context path from public frontend URLs. The step is done when smoke tests pass on the public hostname and no client redirects to the old server.
Decommission WildFly after the rollback window
When the rollback window defined in the cutover plan closes, the team confirms that no traffic reaches the WildFly server and takes a final backup of its configuration and any remaining state. The server is then shut down, and its host, standalone configuration, custom modules and certificates are removed or archived under your retention policy. Confirm the retention period with your compliance lead before anything is deleted. The step is done when monitoring shows no requests to the old hostname and the decommissioning record is filed.
What drives the cost and duration of the move
This table lists the factors that change how much effort the move takes and how long it runs, along with what to request in a written quote. Read each row against your own Keycloak inventory, since a small realm count can still hide heavy XML and provider work. Inventory, rebuild, testing and cutover are one-time work, while operator updates, patching and provider maintenance recur after the move.
| Driver | Why it matters | What to ask for in a quote |
|---|---|---|
| Custom providers and themes | Each provider JAR and theme needs rebuilding and retesting against the Quarkus distribution. Rebuilt providers then need maintenance with every release. | Count of providers and themes, their source, build method, and whether custom code is rewritten or only rebuilt. |
| XML and CLI configuration | Legacy standalone XML and jboss-cli scripts must be mapped by hand to Quarkus server options and build settings. | Number of XML and CLI files, the settings they control, and whether scripts run in your deployment pipelines. |
| Clients hard-coding /auth or old redirect URIs | The /auth path change and old redirect URIs break applications and proxies that were not updated, so each client needs retesting at cutover. | Count of clients, redirect URI patterns, and which application teams or vendors make the changes. |
| Database and schema migration | Schema migration runs automatically at startup by default or can be applied manually as SQL. Manual steps add DBA review and rollback planning. | Database engine and version (PostgreSQL 14 to 18 is supported), who applies schema changes, and backup and rollback steps. |
| Realms and user store size | More realms and larger user stores extend export, import, validation and login testing time. | Realm count, user totals per realm, and whether realm export and import is in scope. |
| User federation and brokered identity providers | LDAP, Active Directory and brokered providers each need connection, mapper and login flow checks after the move. | Count of federation links and brokered providers, and whether test accounts exist in each directory for verification. |
| High availability design | The supported high availability designs need a synchronously replicated database, which may require database or network changes before cutover. | Current topology, whether a synchronously replicated database exists, and which supported design the target uses. |
| Metrics and monitoring at /metrics | Prometheus metrics at /metrics are served on the management interface only when metrics are enabled at startup. | Whether scrape configurations, dashboards and alerts move to the new endpoint, and who updates them. |
| Parallel run period | A parallel run keeps the old and new servers live for comparison, which adds hosting and coordination for that period. | Whether a parallel run is included, how long it is written into scope, and the rollback plan if cutover fails. |
What usually goes wrong in a Keycloak WildFly to Quarkus migration
Most failed migrations from the WildFly distribution do not fail at cutover. They fail because a custom provider, a client registration, a secret or an upgrade step was carried across without being tested on the Quarkus side. Each card names one failure, what causes it, and the check that prevents it before production.
Provider built against the wrong distribution
Custom providers, themes and SPIs written for WildFly often compile cleanly and then fail when Quarkus loads them at startup. The provider must be rebuilt against the target Keycloak release and packaged for the Quarkus distribution, with the build step run before the server starts. Confirm that every provider JAR is rebuilt from source for the target version, and test a clean build in staging that starts with a copy of the production configuration.
Clients broken by the path change
The move away from the /auth context path changes discovery URLs, token endpoints and admin links for every application that uses them. Applications with hard-coded issuer values or stale redirect URIs fail with errors that look like application login bugs. Inventory each client, record its issuer and redirect URIs, and agree in advance whether each application is updated in the same change window or served through a temporary compatibility path.
Logout and token validation failures found late
Logout flows and token validation in client libraries often pass smoke tests and fail under real session patterns, such as expired refresh tokens or single logout across several applications. If the target is Keycloak 26.8.1, review the 26.8 upgrade notes for three changes: enforced SMTP StartTLS without plaintext fallback, mandatory signature validation of backchannel logout tokens from external providers, and login failures persisted to the database by default. Test logout from every client and confirm mail delivery before cutover.
Unplanned upgrades and irreversible schema changes
Operator updates applied automatically can move a cluster to a new release before the team has tested it. Keycloak migrates its database schema at startup by default, and once the new release has written to the schema, returning to the old image is unlikely to work. Set the Operator to manual approval, rehearse the migration on a restored copy of production, and take a verified database backup immediately before cutover. For large databases, decide whether to apply the SQL manually.
Secrets that must be re-entered after export
Export and import tooling may carry realm and client configuration while omitting client secrets, LDAP bind passwords, SMTP credentials and signing keys. The migration then stalls until someone re-enters those values, and a wrong value can break federation or mail without an obvious error. Inventory every secret that the WildFly XML and realm exports reference, store each one in your secrets manager, and verify each after import with a test login, LDAP bind or sent message.
Admin console exposed on the public hostname
The production guide calls for a reverse proxy with path restrictions and for the admin console and Administration REST API to sit on a different hostname or context path from public frontend URLs. Migrations often reuse an old proxy rule that forwards every path, which publishes the admin console to the internet. Before cutover, test admin and management paths from outside your network, and confirm that the metrics endpoint on the management interface is reachable only from your monitoring systems.
Questions teams ask before they migrate Keycloak to Quarkus
How much does a Keycloak WildFly to Quarkus migration cost?
The cost follows from the written scope, and DeployOpen does not publish a price list. The main components are inventory of realms, clients, custom providers, themes and deployment files; rewriting XML subsystem configuration into Quarkus settings; rebuilding and testing custom providers; setting up a test environment; client flow testing; parallel run support; rollback rehearsal; and handover documentation. The migration itself is one-time work, while support, upgrades and testing retainers recur and are scoped separately. Costs rise with the number of custom providers, realms, clients, integrations, and clustering or database complexity. When requesting a quote, ask for itemized deliverables, stated assumptions, the work your team is responsible for, exclusions, and how change requests are priced.
How long does a Keycloak migration from WildFly to Quarkus take?
Duration depends on three inputs: the results of the inventory, the number of providers that must be rebuilt, and the length of the parallel run window. A small deployment with few custom components and a short parallel run needs far less time than a deployment with many realms, bespoke providers and long validation cycles. The inventory is the first step because it shows which settings map directly, which need redesign, and which custom code must be rebuilt. Ask for a timeline in writing that lists its dependencies, including client owner reviews, change window availability and sign-off dates, so delays on your side are visible in the plan.
What must our team provide for a Keycloak Quarkus migration engagement?
Your team needs to provide six things before work starts. First, access to the inventory, including server configuration files, realm exports, custom provider source code, deployment manifests and database details. Second, a test environment close enough to production to validate login, token and logout behavior. Third, a named owner for each client application who can confirm expected behavior. Fourth, a change window for cutover and, if needed, a window for rollback. Fifth, access to identity administrators and server logs during testing. Sixth, written sign-off on the rollback plan before the cutover date is set. Missing any of these usually moves the schedule, so confirm them during scoping.
Can our own identity team migrate Keycloak to Quarkus without a partner?
Yes, if your team has the skills to rebuild custom providers against the Quarkus distribution and to test client flows end to end. Those skills include Java build tooling, Keycloak's provider model, the new configuration options, and OpenID Connect and SAML testing. The Keycloak upgrading guide documents the changes between the WildFly and Quarkus distributions, and the work is manageable with a documented upgrade path and a rehearsed rollback. Teams that lack one of these skills, or that must complete the work within a fixed change calendar, often bring in a partner for a fixed-scope piece such as provider rebuilds or cutover testing. Decide on the split by listing the skills each task needs.
Does DeployOpen provide a compliance attestation for our Keycloak migration?
No. DeployOpen does not issue audit reports, attestations or certifications. Independent auditors and certification bodies perform those assessments. What DeployOpen does is prepare systems, controls and evidence for them. For a migration, that can include documented configuration baselines, mapped authentication settings, test results for login and logout flows, change records, rollback test records and access review inputs. Your auditor decides whether that evidence meets the framework you are assessed against. Ask the auditor early which records they expect, so the migration produces them during the work instead of after cutover.
Does moving to Red Hat build of Keycloak change the migration plan?
It can. The Red Hat build of Keycloak is Red Hat's supported distribution based on the open source Keycloak project, and it replaces Red Hat Single Sign-On. The distribution, the version it ships and its support terms determine the target version, the supported database and deployment method, and the upgrade steps. Confirm these with Red Hat before scoping, including whether your subscription covers the target version and how it is packaged for your platform. Once the target is confirmed, the inventory and provider rebuild work follows the same structure, but the test matrix and cutover steps should be rechecked against the chosen distribution.
What usually breaks during a WildFly to Quarkus Keycloak migration?
Four areas cause most failures. Custom providers that depend on WildFly modules or classes no longer available in the Quarkus distribution fail at build or startup, so they need to be rebuilt and retested. XML subsystem settings have no one-to-one equivalent for some options, so each setting must be mapped and checked. The /auth path change breaks redirect URIs, reverse proxy rules, bookmarks and hardcoded client URLs unless they are updated together. Database connection, clustering and TLS settings also differ and must be validated under load. Test each client's login, token refresh and logout flows against the new server before cutover, and keep the old server available for rollback until the parallel run ends.
How DeployOpen scopes and delivers a Keycloak migration
DeployOpen plans and delivers the move from a pre-17 Keycloak on WildFly to the Quarkus distribution inside your own infrastructure, with a written scope agreed before work starts. The work covers XML configuration rewrites, custom provider rebuilds, the change from the /auth path and the new Operator, with each step tested against your realms and clients.
How we scope
- Inventory every Keycloak realm, client, user federation link, custom provider and theme on the current WildFly server
- Confirm which standalone XML settings must map to Quarkus options or build-time configuration before any change is made
- Record the written scope, deliverables and timeline together, with clear statements of what the migration excludes
How we build
- Rebuild custom providers and themes against the Quarkus distribution and test each one in a staging copy of your data
- Move the /auth path change into reverse proxy rules and client redirect URIs, then verify login flows end to end
- Deploy with the Keycloak Operator in manual approval mode so each upgrade is reviewed before it reaches production
How we hand over
- Deliver the rewritten configuration, build scripts and provider source with a runbook your team can operate
- Document the database migration path, whether schema changes run automatically at startup or as reviewed SQL, and the rollback steps
- Walk your operators through the test results, open issues and the checks they should repeat after each future upgrade
How we support
- Offer ongoing support, upgrades and continuous testing as a retainer after handover, if your team wants that cover
- Keep metrics enablement, backups and monitoring scope visible in the written agreement so ownership stays clear
- Confirm with Keycloak release notes and your own environment before each minor version, since breaking changes are opt-in
