[[intro]]

== Upgrading Red Hat Single Sign-On

Red Hat Single Sign-On (RH-SSO) {project_versionDoc} is based on the Keycloak project and provides security for your web applications by
providing Web single sign-on capabilities based on popular standards such as SAML 2.0, OpenID Connect, and OAuth 2.0.
The Red Hat Single Sign-On Server can act as a SAML or OpenID Connect-based identity provider, mediating with your
enterprise user directory or third-party SSO provider for identity information and your applications using standards-based
tokens.

RH-SSO provides two operating modes: standalone server or managed domain. The standalone server operating mode represents
running RH-SSO as a single server instance. The managed domain operating mode allows for the management of multiple
RH-SSO instances from a single control point. The upgrade process differs depending on which operating mode has been
implemented. Specific instructions for each mode are provided where applicable.

The purpose of this guide is to document the steps that are required to successfully upgrade from
Red Hat Single Sign-On 7.x to Red Hat Single Sign-On {project_versionDoc}.

=== About upgrades

Depending on your version of RH-SSO, you choose one of three types of upgrade. However, if you starting from Keycloak, you choose xref:keycloak-migration[this procedure].

==== Major upgrades

A major upgrade or migration is required when RH-SSO is upgraded from one major release to another, for example, from
Red Hat Single Sign-On 7.2 to Red Hat Single Sign-On 8.0. There may be breaking API changes between major releases
that could require rewriting parts of applications or server extensions.

==== Minor updates

Red Hat Single Sign-On periodically provides point releases, which are minor updates that include bug fixes, security
fixes, and new features. If you plan to upgrade from one Red Hat Single Sign-On point release to another, for example,
from Red Hat Single Sign-On 7.3 to Red Hat Single Sign-On {project_versionDoc}, code changes should not be required for applications or
custom server extensions as long as no private, unsupported, or tech preview APIs are used.

==== Micro updates

Red Hat Single Sign-On {project_versionDoc} also periodically provides micro releases that contain bug and security fixes.
Micro releases increment the minor release version by the last digit, for example from  {project_versionDoc}.0 to {project_versionDoc}.1. These releases
do not require migration and should not impact the server configuration files. The patch management system for ZIP
installations can also rollback the patch and server configuration.

A micro release only contains the artifacts that have changed. For example if Red Hat Single Sign-On  {project_versionDoc}.1 contains changes to
the server and the JavaScript adapter, but not the EAP adapter, only the server and JavaScript adapter are released and require
updating.

[id="keycloak-migration"]
=== Migrating Keycloak to RH-SSO

You can migrate to Red Hat Single Sign-On, the supported Red Hat product, from Keycloak, the community project.

.Prerequisites

* To learn about new features before the upgrade, review the xref:release_changes[changes].
* Verify that you have installed the correct version of Keycloak as a starting point. To migrate to Red Hat Single Sign-On {project_versionDoc}, you need Keycloak {keycloak_upgrade_version}.

.Procedure

. Perform the xref:_upgrading_minor[Minor Upgrades] procedure. Although this procedure is labelled *Minor Upgrade*, the same steps apply for this migration.
. Perform the xref:_upgrade_adapters[Adapter Upgrade procedure].