Keycloak upgrades and support

When Keycloak upgrades and support are worth handing to a partner

Most teams that run Keycloak handle upgrades in-house at first, and a partner becomes worth considering once the upgrade queue starts competing with product and infrastructure work. Sign-in for every application depends on the Keycloak instance, so the decision is less about whether your engineers can run an upgrade and more about whether they can afford to do it on the project's current cadence. Keycloak plans four minor releases a year, and its current release at the time of writing is 26.8.1, published October 13, 2026. Each minor release brings a release note review, a test pass against your realms, and a production change window, all owned by people who also run other systems.

The triggers that usually move this work outside the team are predictable. The first is the end of support for the line you run, which forces a move even when nothing is broken. The second is a security release, where the window to patch is short and the change may need to be deployed the same week. The third is a new application or realm that must be onboarded on a current version, which adds testing load to an upgrade that was already scheduled. The fourth is an operator update prompt, which matters most if you run the Keycloak Operator on Kubernetes, because the project strongly recommends manual approval mode to avoid unintended automatic upgrades. Each trigger should lead to a decision about who reads the notes, who tests, and who approves the change.

Go-live is where support questions start, and they are different from build questions. Teams ask how to read upgrade notes for behavior changes that affect their clients, such as the 26.8 changes to SMTP StartTLS, backchannel logout token validation and persisted login failures. They ask whether database schema migration should run automatically at startup or be applied manually, a choice the upgrading guide suggests for large deployments. They also ask how to keep a staging realm representative enough to catch regressions. Before you engage a partner, confirm in writing which of these questions they will answer, which versions they support, and how fast they respond to a security release.

When you request a quote for ongoing support, ask for the scope in terms you can check: the Keycloak versions covered, the environments included, the number of upgrade cycles per year, whether security releases are handled out of band, and who performs database and operator changes. Ask whether the work is fixed-scope for a defined upgrade or a retainer for continuing support, and what is excluded, such as custom SPI extensions, themes or federation changes that need their own testing. DeployOpen scopes these engagements from written requirements, so the quote should reflect the platform you actually operate rather than a generic service tier.

What a Keycloak upgrade and support engagement includes

An upgrade engagement moves one running Keycloak environment from its current release to a chosen target without surprising users or the operations team. The work packages below follow the order a change actually takes, and the support card covers what happens once the new version is live.

Upgrade assessment

We read the release notes for every version between your current release and the target, then map each behavior change to your realms, clients, identity providers and custom code. Recent upgrade notes include 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. Each one can affect sign-in or email flows, so the assessment lists them by impact. Deliverable: a written assessment with a risk register and a list of configuration changes.

Test realm and client validation

We build or copy a test realm that reflects production clients, identity providers, authentication flows and role mappings, then run the target release against it. Sign-in tests cover each protocol your applications use, including OpenID Connect, OAuth 2.0 and SAML 2.0 flows, plus logout and token refresh. Custom themes and SPI extensions are exercised separately because they carry their own upgrade cost. Deliverable: a test report with pass and fail results per client and a list of fixes applied to the test realm.

Database migration planning

Keycloak applies schema changes automatically at startup by default. For large deployments the upgrade guide suggests applying the SQL manually, which lets a database team review and schedule it. We confirm which option fits your database, whether it is one of the supported production databases or a managed service, and whether the migration needs a maintenance window or a backup point. Deliverable: a migration plan covering the chosen mode, backup and restore steps, and the sequence for each environment.

Operator or container update procedure

The update path depends on how Keycloak runs. On Kubernetes with the Keycloak Operator, the project strongly recommends manual approval mode for operator updates to prevent unintended upgrades, so the procedure defines who approves each change and when. For container or virtual machine installs, we document the image or package pinning, configuration file changes and the order in which nodes restart in a cluster. Deliverable: a runbook with step-by-step update commands, approval points and node restart order.

Production cutover with rollback

The cutover runbook sets the window, the freeze on configuration changes, the backup taken before the upgrade and the checks that decide whether to proceed at each step. Rollback steps are written before the window opens, including how to restore the database backup and redeploy the previous release image or package. We confirm rollback is possible at each stage, since a schema change may not reverse cleanly. Deliverable: a signed-off cutover plan with go and no-go criteria and a tested rollback procedure.

Post-upgrade verification and support

After cutover we run the test realm checks against production, confirm metrics and logs are flowing, and watch login failure rates and latency for an agreed period. The support service then covers scheduled reviews of release notes and configuration, incident response within the scope you agree in writing, and retainer options that set how often reviews happen and what is covered. We do not promise specific response times here, so confirm them against the agreed scope. Deliverable: a verification report, followed by a support schedule and retainer terms.

How Keycloak's four minor releases a year change upgrade planning

Since Keycloak 26.0, the project plans four minor releases a year and a major release every two to three years. For a support calendar, this means minor upgrades arrive several times a year, so they need a standing place in operations rather than an occasional project. The project also says breaking changes in a minor release are opt-in. A minor upgrade can therefore be routine and still change behavior once a setting is enabled. A major upgrade is different. It bundles larger changes and deserves its own plan, test cycle and rollback path. Before you build the calendar, confirm which release your environment targets. The current release is 26.8.1, published October 13, 2026, but your target should follow your change window and your testing capacity.

The 26.8 upgrade notes show what opt-in and enforced changes look like in practice. Four items need a decision. First, SMTP StartTLS is enforced without plaintext fallback, which affects password reset and notification mail if your relay does not offer TLS. Second, backchannel logout tokens from external identity providers must pass signature validation, which affects any brokered logout flow. Third, login failures are persisted to the database by default, which affects database growth and event retention. Fourth, the deprecated multi-site feature is replaced by the stateless feature, which changes the high availability design. Read each item against your own realms, identity providers, mail path and database, and record which ones apply to you.

Each item needs a named owner and a test because a line in release notes is not evidence that the environment behaves correctly. The owner decides whether the change applies, accepts the risk if it does, and signs off on the result. The mail owner would check that a password reset sent through the production relay succeeds over StartTLS. The federation owner would confirm that each external provider signs its logout tokens and that a test logout completes. The database owner would measure table growth after a scripted set of failed logins and set a retention rule. The platform owner would plan the move off multi-site in a non-production cluster first. Illustrative example: if the test shows the relay refusing StartTLS, the owner has a clear problem to fix before the upgrade, not after.

Keep these decisions in a simple upgrade register with one row per release and per change. Record the release, the change, whether it applies, the owner, the test performed, the evidence and the date of sign-off. This register becomes the basis for the next minor upgrade and for any support request. When you ask a partner or vendor for an upgrade quote, ask them to include release-note review, the register, testing against your realms and a fallback plan in the written scope. Also confirm the version line you run. The Red Hat build of Keycloak is a separate supported distribution, and Red Hat's product page showed version 26.6 as its latest, so its release timing can differ from the community release you target.

What drives Keycloak upgrade effort and duration

This table lists the factors that most change how much work a Keycloak upgrade takes, why each one matters, and one way to keep it under control. Use it to see which parts of your estate need inventory and testing before you ask for a quote. The main takeaway is that custom extensions, federation and environment count usually matter more than the Keycloak version gap itself.

Driver	Why it changes effort	How to keep it down
Number of realms and clients	Each realm and client carries its own configuration, mappers and flows that must be re-tested after a release. Upgrade notes can affect any of them.	Export realm configuration as code, keep client counts tidy, and test a representative set of realms rather than every one by hand.
Custom themes	Login and account themes use templates that can change between releases, so each theme needs a compatibility check and visual testing.	Keep themes minimal, avoid overriding templates you do not need, and keep theme changes in version control.
Custom SPI extensions	Custom user storage providers, authenticators and event listeners compile against Keycloak APIs and must be rebuilt and retested for every target release.	List every extension with its owner and purpose, and prefer built-in features where they meet the requirement.
LDAP and Active Directory federation	Federation settings, sync schedules and attribute mappers interact with directory schemas, so changes need validation against a directory test environment.	Document mapper configuration and run sync tests in a non-production directory before each upgrade.
Brokered external identity providers	Upgrade notes can change token validation rules for external providers, such as mandatory signature checks on backchannel logout tokens, so each broker needs checking.	Maintain an inventory of brokers with their protocol, certificate dates and logout settings, and test first login flows after each change.
Database platform and size	Schema migration time and rollback options depend on the database engine, version and data volume, and the upgrade guide suggests manual migration for large deployments.	Take a tested backup before migration, confirm the engine version is on the supported list, and rehearse migration on a restored copy.
Cluster topology	Multi-site and availability zone designs multiply the number of nodes to update and the cache and replication behavior to verify, and the deprecated multi-site feature may need a move to a different design.	Use a rolling update order documented in advance and verify failover on a staging cluster that matches production topology.
Kubernetes operator use versus manual installs	Operator-managed installs need operator version compatibility checks and approval workflows, while manual installs need hand-built packaging and rollout steps for each node.	Set operator updates to manual approval, pin versions in source control, and script manual install steps so they repeat the same way.
Number of environments	Every environment, including development, test, staging and production, repeats the upgrade and its checks, and drift between them makes results harder to trust.	Keep environments built from the same definitions and promote one tested change set through each environment in order.
Community build versus Red Hat build	The community project publishes minor releases several times a year, while the Red Hat build follows Red Hat's supported release schedule and support terms, which can set the target version and timing.	Confirm with Red Hat which build version and support window applies to your subscription before planning the target release.

How a Keycloak upgrade moves from upgrade notes to go-live

This sequence turns an upgrade from a version change into a documented, tested and approved change, so each step produces evidence that the next one depends on. It covers the path from the current inventory to a production cutover and a post-upgrade review.

Take an inventory of the current deployment
Your team and the DeployOpen engineer record the running Keycloak version, how it is deployed (standalone, container, or the Keycloak Operator), the database product and version, the high availability design, custom providers and themes, and the realms and clients in use. The output is a current-state inventory that names every component an upgrade could touch. The step is done when the inventory has been reviewed and signed off by the owner of the identity service.
Read the upgrade notes between releases
The engineer reads the upgrade notes for every release between your current version and the target, and maps each behavior change to your inventory. Items such as enforced SMTP StartTLS, mandatory signature validation of backchannel logout tokens from external providers, and login failures persisted to the database by default are checked against your mail, logout and logging setup. The output is a written impact list with an owner and a disposition for each item, including any that need a configuration change or a code change in a custom provider.
Build a staging copy and run the database migration
The team restores a recent copy of the production database into a staging environment that matches production configuration, then starts the target version against it. Keycloak migrates the schema automatically at startup by default. For large deployments, the upgrading guide describes applying the migration SQL manually, which lets your database team review and schedule the changes. The output is a staging instance on the target version with a migration log that shows no errors and a recorded list of schema changes.
Test realms, clients and sign-in flows
Testers run scripted sign-in tests against staging for each realm and client, covering OIDC and SAML logins, token claims, role and group mappings, user federation, identity brokering, MFA enrollment and any custom authentication flows or themes. Results are compared with the pre-upgrade baseline. The output is a test report listing each realm and client tested, the pass or fail result, and the defects with their owners. The step is done when no open defect blocks go-live and the business owners of each application have accepted the results.
Approve operator updates in manual mode
For Keycloak on Kubernetes, the Keycloak Operator documentation strongly recommends manual approval for operator updates to avoid unintended automatic upgrades. The change control owner reviews the pending install plan from Operator Lifecycle Manager, confirms it matches the approved target version, and approves it only in the agreed change window. The output is a recorded approval that names the version, the approver and the time, linked to the change ticket.
Cut over to production
The team runs the agreed production change plan: a fresh database backup, a confirmed rollback path to the prior version and database state, the upgrade itself, and a smoke test of sign-in for each critical application. The output is a production instance on the target version with a cutover log and a smoke test record. If a smoke test fails, the rollback path is executed and the failure is logged before any further change is attempted.
Hold a post-upgrade review
After go-live, the team reviews login failure rates, error logs, metrics and any support tickets raised by application owners, and compares them with the baseline. Open items from the impact list are assigned and tracked to closure. The output is a post-upgrade review record that states the outcome, the open actions with owners, and any changes to the runbook, which becomes the input for the next upgrade cycle. Ask your support provider to confirm in writing which of these reviews are included in the agreed scope.

Which parts of a Keycloak upgrade teams keep in-house and which they outsource

This table splits each stage of a Keycloak upgrade into the work an internal team usually keeps and the work a partner usually takes on, with the skill each stage needs. Read it as a starting point for deciding who owns each stage, then confirm the split against your own staffing and change-control rules. The main takeaway is that release decisions and business sign-off usually stay with your organization, while database, rollout and regression work often benefit from outside hands.

Upgrade stage	Skill needed and who usually holds it	Typical split
Release calendar and business sign-off	Identity architecture and change management. Usually held in-house by the identity owner and service owners.	Keep in-house
Reading upgrade notes against local configuration	Identity architecture. Internal architects usually own the decision, with a partner often drafting the impact list.	Shared
Database administration and schema migration	Database administration. Internal DBAs usually approve, while a partner or internal DBAs may execute automatic or manual migration.	Shared or outsourced
Realm and client regression testing	Application testing and identity configuration. Partners often run the test plan, while application owners verify their own sign-in flows.	Often outsourced
Operator or container rollout	Kubernetes and release engineering. Platform teams often hold this, and partners may script and rehearse the rollout.	Shared or outsourced
Security review of changed defaults	Security review of changed defaults such as SMTP StartTLS and token validation. Usually held in-house by the security team, with partner input.	Keep in-house
Ongoing monitoring of sign-in errors	Monitoring and operations. Internal operations teams usually keep alerts, while a support retainer may cover triage and tuning.	Shared or outsourced

What goes wrong in Keycloak upgrades and how to prevent it

Keycloak upgrades usually fail in a few predictable places: a release changes a default, an operator applies an update nobody approved, or a component outside the core server stops matching the new version. The cards below cover six failure modes, each paired with the check that prevents it. Review them before scheduling the first upgrade, not after the first sign-in ticket.

Upgrade notes skipped

Keycloak says breaking changes in a minor release are opt-in, but the 26.8 upgrade notes list enforced changes, including mandatory signature validation of backchannel logout tokens from external providers. A team that jumps versions without reading each intermediate note can find sign-in or logout behaving differently for users on the first day. Prevention: read every note between the current and target version, mark each item as applies, does not apply, or needs a test, and assign an owner to each one.

Operator updates applied automatically

The Keycloak Operator documentation strongly recommends manual approval mode for operator updates to avoid unintended automatic upgrades. With automatic approval, a new operator version can roll a running Keycloak instance to a release nobody has tested, often outside a planned change window. Prevention: set manual approval on the operator subscription, treat each update as a tracked change with a test realm run, and confirm in writing who is allowed to approve it.

Schema migration without a backup

Keycloak migrates its database schema automatically at startup by default, so a restarted pod can change tables on a live database before anyone reviews the change. An upgrade that runs against production data without a verified backup has no clean rollback path. Prevention: take a backup or snapshot and test that it restores, decide between automatic and manual migration (the upgrade guide suggests manual SQL for large deployments), and rehearse the restore before the change window opens.

Themes and SPIs break after release

Custom login and account themes and service provider interface extensions, such as custom user storage or event listeners, are built against a specific Keycloak release. After an upgrade they can fail to load, render incorrectly, or call an interface that has changed, and the first sign of trouble is often a broken login page. Prevention: inventory every theme and extension, record the Keycloak version each was built against, and run sign-in tests in a test realm before promoting the build.

SMTP changes stop password resets

Keycloak 26.8 enforces StartTLS for SMTP without plaintext fallback. A mail relay that offered plaintext only, or that presents a certificate the server does not trust, will refuse the connection, so password reset and email verification messages fail for users without an obvious error on the sign-in page. Prevention: send a test email from each realm using the production mail configuration in staging, confirm the relay's TLS support and certificate chain, and alert on failed sends after go-live.

Staging that differs from production

A staging environment with one node, the development file database or no external identity providers will not expose the problems above. Node count, HA design, database engine and version, reverse proxy path rules, hostnames and connected providers all change how a release behaves. Prevention: match these to production, include backchannel logout with at least one external provider in the test plan, and write down every deliberate difference so the upgrade risk is known before cutover.

How Keycloak upgrades differ by deployment and starting point

A plain virtual machine or container install is the most direct upgrade path because your team controls the binary or image, the startup order and the timing. The main work is reading the upgrade notes for every release between your current version and the target, then testing against a copy of production data. Database schema migration runs automatically at startup by default, so a failed migration can block the node from starting, which makes a verified backup and a rehearsal essential.

Before you start, confirm:

Database engine and version: the target release supports a defined list of production databases, and PostgreSQL support is listed for versions 14 to 18.
Schema migration mode: whether startup migration is acceptable or whether your DBA must apply the SQL manually, which the upgrading guide suggests for large deployments.
Behavior changes: the 26.8 notes include enforced SMTP StartTLS without plaintext fallback and mandatory signature validation of backchannel logout tokens from external providers.
Rollback plan: whether a schema change can be reversed, since a rolled-back binary may not start against a migrated database.
Node sequencing: how a rolling restart is staged if more than one node runs behind a load balancer.

Confirm these items against the upgrading guide for your exact source and target versions before scheduling the change window.

What your team must provide before a Keycloak upgrade starts

Before a Keycloak upgrade is scheduled, the client has to supply a set of inputs that the upgrade team cannot reliably reconstruct on its own. The first is read access to the running configuration and the exact version currently deployed, including the server image or package tag, the operator version if the Keycloak Operator is in use, and the startup options. The platform or identity engineering team usually owns this. Without the exact starting version, the upgrade path, the list of upgrade notes that apply and the behavior changes to test cannot be determined. Confirm the running version from the server itself, not from the deployment record, since the two often drift. Next, the client provides a current database backup and a staging database of similar size and shape. The database administration team usually owns the backup, and the platform team owns the staging copy. Keycloak migrates its schema automatically at startup by default, or the team applies the SQL manually for large deployments, so a restorable backup taken before the change is the only reliable rollback path for schema changes. The staging copy should contain realistic volumes of users, sessions and events so that migration duration and any event or login-failure table growth are visible before production. Ask the database owner to confirm the supported database type and version against Keycloak's documented list, since the migration path depends on it. The client also supplies an inventory of realms, clients, identity providers, user federation links and custom extensions, along with test accounts for each sign-in path. Application owners usually provide the client list, and the identity team provides realms and federation settings. Custom themes, authentication flows and service provider interface extensions must be named explicitly because each one can break at a major or minor release. Test accounts should cover password sign-in, one-time passwords, WebAuthn or passkeys, brokered logins and any directory-backed users, and they should be usable without a shared personal login. The last three items are governance. Someone must approve the operator or change window, since the Keycloak Operator documentation strongly recommends manual approval mode for operator updates to avoid unintended automatic upgrades, and a change owner should hold that approval. A named owner for sign-in incidents must be available during and after the window, because login failures are the first visible symptom of a problem. Finally, the business must state the rollback criteria it accepts, such as a threshold of failed sign-ins, a broken client flow or an unacceptable duration, and who has authority to trigger rollback. Agreeing these criteria before the upgrade starts avoids debate during an incident.

What do Keycloak upgrade and support services cost and take?

What drives the fee for a Keycloak upgrade compared with an ongoing support retainer?

The upgrade fee follows the written scope of one version change, while a support retainer is a recurring commitment covering an agreed set of activities over a period. Upgrade drivers include the number of realms, custom themes and SPI extensions, the number of clients and identity providers, the database and high availability design, and how many environments must be moved. Retainer drivers include the response expectations agreed in writing, how often releases are reviewed, and how much monitoring or testing is included. Ask for the two to be quoted separately so you can see which parts are one-time and which recur. DeployOpen does not publish a price list, so a quote follows from the written scope.

How long does a Keycloak upgrade take and what changes the timeline?

No fixed duration applies to every upgrade, so the timeline depends on the scope agreed in writing. The main drivers are the number of minor releases crossed, the amount of custom code that must be retested, the size of the database schema change, and whether the deployment runs on the Keycloak Operator or in a clustered high availability design. Upgrades that cross more release notes take longer to review, and custom authentication flows or SPI extensions add test cycles. Keycloak's upgrade notes for 26.8 list specific behavior changes, such as enforced SMTP StartTLS and mandatory signature validation of backchannel logout tokens from external providers, and each one that touches your setup adds review and testing time. Ask for the timeline to be broken into review, staging, test and cutover phases.

Can our own team upgrade Keycloak without a partner?

Yes, a capable internal team can upgrade Keycloak alone if it works from the upgrade notes, uses a staging copy of production, and runs a written test plan before cutover. The release notes for each version list behavior changes, and the upgrading guide describes how to handle database schema migration. Keycloak migrates its schema automatically at startup by default, but the guide suggests manual migration for large deployments, so your team should decide which approach fits. The main risk is testing coverage: realms, login flows, client redirects, federation sync and token behavior all need checks. Keep a rollback path and a database backup before any change. A partner can take on any part of this, so confirm which steps your team keeps.

How much time do our internal staff need to give an upgrade or support engagement?

Internal effort depends on how much of the work your staff keep and how many people must approve changes. Typical contributions include an owner for the identity platform, people who know the applications and their redirect URIs, a database administrator for backup and migration, someone who can approve changes to the Keycloak Operator or infrastructure, and testers who can sign in to each application after a change. Keycloak's Operator documentation recommends manual approval mode for operator updates, so a named approver is needed before each upgrade. Ask the provider to list every internal role, the expected time per role and the dates they are needed, and confirm these in the written scope.

How does Keycloak support differ before and after go-live?

Before go-live, support is part of the project: architecture decisions, realm and client design, database and high availability setup, testing and cutover are delivered against a fixed scope. After go-live, support shifts to operations, which usually means monitoring, incident response, security updates, minor release reviews and periodic upgrades. Since Keycloak plans four minor releases a year, a retainer should state how each release is reviewed and when it is applied. Pre-production support often includes runbooks and knowledge transfer, while post-production support focuses on stability and change control. Ask which activities are included after go-live, how urgent issues are handled, and what is excluded, such as new applications or custom development.

What should we ask for in a written quote for Keycloak upgrade and support?

A useful quote lists the scope in specific terms rather than general ones. Ask for the Keycloak version in place and the target version, the list of realms, clients, identity providers, user federation links, custom themes and SPI extensions, the database product and version, the high availability design, and the environments included. Ask which deliverables you receive, such as upgrade notes applied to your setup, a staging copy, a test plan, a rollback plan, and documentation. Ask for the one-time fee and the recurring fee separately, the assumptions behind each, the internal roles expected of your staff, the exclusions, and how changes to scope are priced. Confirm the response expectations for support in writing and the notice period for any change to the agreed scope.

What does a Keycloak upgrade need before testing starts?

Before testing starts, you need an inventory and a stable baseline. Record the current Keycloak version, the database and its version, the deployment method, and every realm and client with its redirect URIs and token settings. Export configuration where possible and confirm the backups you can restore from. Read the upgrade notes for every version between the current and target release, and mark each behavior change that touches your setup. Build a staging environment with a copy of production data, or a representative subset with sanitized user records, and make sure it uses the same database product and high availability layout. Agree on the test plan and acceptance criteria with the application owners before the upgrade window opens.

How DeployOpen scopes, delivers and supports Keycloak upgrades

DeployOpen treats each Keycloak upgrade as a scoped engagement: we read the release notes against your realms, clients and deployment, build and test the upgrade in non-production environments, and hand over a runbook your team can repeat. Ongoing support after go-live is available as a retainer.

How we scope

We inventory your current Keycloak version, realms, clients, federation links and database engine before proposing any work.
We map the release notes between your version and the target against your configuration to flag behavior changes that apply to you.
The written scope names the target version, environments covered, database migration approach and the testing and handover deliverables.

How we build

We rebuild a staging environment that matches production topology, including the database, high availability layout and reverse proxy rules.
We choose between automatic schema migration at startup and manual SQL migration, based on deployment size and your change controls.
We test sign-in, token issuance, brokered logins, federation sync and admin workflows in a copy of your realms before any production change.

How we hand over

We deliver a written upgrade runbook with rollback steps, pre-checks, post-checks and the configuration changes made.
For Operator-managed clusters, we set up update approval so that upgrades run only after a named person approves them.
We document the test results, open issues and any opt-in settings you chose to enable, so your team can repeat the process.

How we support

Support after go-live covers the scope agreed in writing, and it can be arranged as an ongoing retainer for recurring upgrades.
We can review each new minor release for changes that affect your deployment before your team schedules the upgrade window.
Support terms, response expectations and the systems covered are confirmed in the retainer agreement, which you should review before signing.