Fix upgrading guide

upgrading

@@ -1 +0,0 @@
-Subproject commit 2eabfe81fdc1b40355e194b9cca930e51a4c831c

upgrading/index.adoc

@@ -0,0 +1,6 @@
+:toc:
+:toclevels: 3
+:numbered:
+
+include::topics/templates/document-attributes-community.adoc[]
+include::topics.adoc[]

upgrading/master-docinfo.xml

@@ -0,0 +1,25 @@
+<productname>{project_name}</productname>
+<productnumber>{project_versionDoc}</productnumber>
+<subtitle>For Use with {project_name} {project_versionDoc}</subtitle>
+<title>{upgradingguide_name}</title>
+<release>{book_project_doc_info_version_url}</release>
+<abstract>
+    <para>This book is a guide to upgrading your application from a previous version of {project_name} {project_versionDoc}. </para>
+</abstract>
+<authorgroup>
+    <orgname>Red Hat Customer Content Services </orgname>
+</authorgroup>
+<legalnotice lang="en-US" version="5.0" xmlns="http://docbook.org/ns/docbook">
+  <para> 		Copyright <trademark class="copyright"></trademark> 2016 Red Hat, Inc. 	</para>
+  <para>Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at</para>
+  <para>
+    <ulink url="http://www.apache.org/licenses/LICENSE-2.0">    http://www.apache.org/licenses/LICENSE-2.0</ulink>
+  </para>
+  <para>Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.</para>
+</legalnotice>

upgrading/master.adoc

@@ -0,0 +1,11 @@
+:toc:
+:toclevels: 2
+:numbered:
+
+include::topics/templates/document-attributes-product.adoc[]
+
+:upgrading_guide:
+
+= {upgradingguide_name}
+
+include::topics.adoc[]

upgrading/pom.xml

@@ -0,0 +1,37 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+    <modelVersion>4.0.0</modelVersion>
+
+    <parent>
+        <groupId>org.keycloak.documentation</groupId>
+        <artifactId>documentation-parent</artifactId>
+        <version>1.0.0-SNAPSHOT</version>
+        <relativePath>../</relativePath>
+    </parent>
+
+    <name>Upgrading Guide</name>
+    <artifactId>upgrading</artifactId>
+    <packaging>pom</packaging>
+
+    <build>
+        <plugins>
+            <plugin>
+                <groupId>org.asciidoctor</groupId>
+                <artifactId>asciidoctor-maven-plugin</artifactId>
+                <executions>
+                    <execution>
+                        <id>asciidoc-to-html</id>
+                    </execution>
+                </executions>
+            </plugin>
+            <plugin>
+                <artifactId>maven-antrun-plugin</artifactId>
+                <executions>
+                    <execution>
+                        <id>echo-output</id>
+                    </execution>
+                </executions>
+            </plugin>
+        </plugins>
+    </build>
+</project>

upgrading/topics.adoc

@@ -0,0 +1,11 @@
+ifeval::[{project_product}==true]
+include::topics/rhsso/intro.adoc[leveloffset=0]
+include::topics/rhsso/changes.adoc[leveloffset=0]
+include::topics/rhsso/upgrading.adoc[leveloffset=0]
+endif::[]
+
+ifeval::[{project_community}==true]
+include::topics/keycloak/intro.adoc[leveloffset=0]
+include::topics/keycloak/upgrading.adoc[leveloffset=0]
+include::topics/keycloak/changes.adoc[leveloffset=0]
+endif::[]

upgrading/topics/install_new_version.adoc

@@ -0,0 +1,70 @@
+[[_install_new_version]]
+
+== Upgrading {project_name} server
+
+It is important that you upgrade {project_name} server before upgrading the adapters.
+
+To upgrade {project_name} server, complete the following steps:
+
+. Prior to applying the upgrade, handle any open transactions and delete the data/tx-object-store/ transaction directory.
+. Download the new server archive
+. Move the downloaded archive to the desired location.
+. Extract the archive. This step installs a clean instance of the latest {project_name} release.
+. For standalone installations, copy the {project_dirref}/standalone/ directory from the previous installation over the
+  directory in the new installation.
++
+For domain installations, copy the {project_dirref}/domain/ directory from the previous installation over the directory
+in the new installation.
++
+For domain installations, create the empty directory {project_dirref}/domain/deployments.
++
+NOTE: 
+Files in the bin directory should not be overwritten by the files from previous versions. Changes should be made manually.
+
+. Copy any custom modules that have been added to the modules directory.
+. Run the applicable upgrade script below.
+
+=== Running the Standalone Mode Upgrade Script
+To run the upgrade script for standalone mode, complete the following steps:
+
+. If you are using a different configuration file than the default one, edit the migration script to specify the new file name.
+. Stop the server.
+. Run the upgrade script: 
+
+ bin/jboss-cli.sh --file=bin/migrate-standalone.cli
+
+=== Running the Standalone-High Availability Mode Upgrade Script
+For standalone-high availability (HA) mode, all instances must be upgraded at the same time.
+
+To run the upgrade script for standalone-HA mode, complete the following steps:
+
+. If you are using a different configuration file than the default one, edit the migration script to specify the new file name.
+. Stop the server.
+. Run the upgrade script: 
+
+ bin/jboss-cli.sh --file=bin/migrate-standalone-ha.cli
+
+=== Running the Domain Mode Upgrade Script
+For domain mode, all instances must be upgraded at the same time.
+
+To run the upgrade script for domain mode, complete the following steps:
+
+. If you have changed the profile name, you must edit the upgrade script to change a variable near the beginning of the script.
+. Edit the domain script to include the location of the keycloak-server.json file.
+. Stop the server.
+. Run the upgrade script on the domain controller only: 
+
+ bin/jboss-cli.sh --file=bin/migrate-domain.cli
+
+=== Running the Domain-clustered Mode Upgrade Script
+For domain-clustered mode, all instances must be upgraded at the same time. 
+
+To run the upgrade script for domain-clustered mode, complete the following steps:
+
+. If you have changed the profile name, you must edit the upgrade script to change a variable near the beginning of the script. 
+. Edit the domain-clustered script to include the location of the keycloak-server.json file.
+. Stop the server.
+. Run the upgrade script on the domain controller only: 
+
+ bin/jboss-cli.sh --file=bin/migrate-domain-clustered.cli
+

upgrading/topics/keycloak/changes.adoc

@@ -0,0 +1,542 @@
+== Migration Changes
+
+=== Migrating to 3.2.0
+
+==== New Password Hashing algorithms
+
+We've added two new password hashing algorithms (pbkdf2-sha256 and pbkdf2-sha512). New realms will use the pbkdf2-sha256
+hashing algorithm with 27500 hashing iterations. Since pbkdf2-sha256 is slightly faster than pbkdf2 the iterations was
+increased to 27500 from 20000.
+
+Existing realms are upgraded if the password policy contains the default value for hashing algorithm (not specified) and
+iteration (20000). If you have changed the hashing iterations you need to manually change to pbkdf2-sha256 if you'd like
+to use the more secure hashing algorithm.
+
+==== ID Token requires scope=openid
+
+OpenID Connect specification requires that parameter `scope` with value `openid` is used in initial authorization request. So in {project_name}
+2.1.0 we changed our adapters to use `scope=openid` in the redirect URI to {project_name}. Now we changed the server part too and ID token
+will be sent to the application just if `scope=openid` is really used. If it's not used, then ID token will be skipped and just Access token and Refresh token will be sent to the application.
+This also allows that you can ommit the generation of ID Token on purpose - for example for space or performance purposes.
+
+Direct grants (OAuth2 Resource Owner Password Credentials Grant) and Service accounts login (OAuth2 Client credentials grant) also don't use ID Token by default now.
+You need to explicitly add `scope=openid` parameter to have ID Token included.
+
+==== Authentication sessions and Action tokens
+
+We are working on support for multiple datacenters. As the initial step, we introduced authentication session and action tokens.
+Authentication session replaces Client session, which was used in previous versions. Action tokens are currently used especially for the scenarios, where
+the authenticator or requiredActionProvider requires sending email to the user and requires user to click on the link in email.
+
+Here are concrete changes related to this, which may affect you for the migration.
+
+First change related to this is introducing new infinispan caches `authenticationSessions` and `actionTokens` in `standalone.xml` or `standalone-ha.xml`. If you use our migration CLI, you
+don't need to care much as your `standalone(-ha).xml` files will be migrated automatically.
+
+Second change is changing of some signatures in methods of authentication SPI. This may affect you if you use custom `Authenticator` or
+`RequiredActionProvider`. Classes `AuthenticationFlowContext` and `RequiredActionContext` now allow to retrieve authentication session
+instead of client session.
+
+We also added some initial support for sticky sessions. You may want to change your loadbalancer/proxy server and configure it if you want to suffer from it and have better performance.
+The route is added to the new `AUTH_SESSION_ID` cookie. More info in the clustering documentation.
+
+Another change is, that `token.getClientSession()` was removed. This may affect you for example if you're using Client Initiated Identity Broker Linking feature.
+
+The `ScriptBasedAuthenticator` changed the binding name from `clientSession` to `authenticationSession`, so you would need to update your scripts if you're using this authenticator.
+
+Finally we added some new timeouts to the admin console. This allows you for example to specify different timeouts for the email actions triggered by admin and by user himself.
+
+=== Migrating to 2.5.1
+
+==== Migration of old offline tokens
+
+If you migrate from version 2.2.0 or older and you used offline tokens, then your offline tokens didn't have KID in the token header.
+We added KID to the token header in 2.3.0 together with the ability to have multiple realm keys, so {project_name} is able to find the correct key based on the token KID.
+
+For the offline tokens without KID, {project_name} 2.5.1 will always use the active realm key to find the proper key for the token verification. In other words, migration of old
+offline tokens will work. So for example, your user requested offline token in 1.9.8, then you migrate from 1.9.8 to 2.5.1 and then your user will be
+still able to refresh his old offline token in 2.5.1 version.
+
+But there is limitation, that once you change the realm active key, the users won't be able to refresh old offline tokens
+anymore. So you shouldn't change the active realm key until all your users with offline tokens refreshed their tokens. Obviously newly
+refreshed tokens will have KID in the header, so after all users exchange their old offline tokens, you are free to change the active realm key.
+
+=== Migrating to 2.5.0
+
+==== Changes to the infinispan caches
+
+The `realms` cache defined in the infinispan subsystem in `standalone.xml` or `standalone-ha.xml` configuration file, now has the eviction with the 10000 records by default.
+This is the same default like the `users` cache.
+
+Also the `authorization` cache now doesn't have any eviction on it by default.
+
+
+=== Migrating to 2.4.0
+
+==== Server SPI split into Server SPI and Sever SPI Private
+
+The keycloak-server-spi module has been split into keycloak-server-spi and keycloak-server-spi-private. APIs within
+keycloak-server-spi will not change between minor releases, while we reserve the right and may quite likely change
+APIs in keycloak-server-spi-private between minor releases.
+
+==== Key encryption algorithm in SAML assertions
+
+Key in SAML assertions and documents are now encrypted using RSA-OAEP encryption scheme.
+If you want to use encrypted assertions, make sure that service providers understand this encryption scheme.
+In the unlikely case that SP would not be able to handle the new scheme, {project_name}
+can be made to use legacy RSA-v1.5 encryption scheme when started with system property
+`keycloak.saml.key_trans.rsa_v1.5` set to `true`.
+
+==== Infinispan caches realms and users are always local
+
+Even if you use {project_name} in cluster, the caches `realms` and `users` defined in infinispan subsystem in `standalone-ha.xml` are
+always local caches now. There is separate cache `work`, which handles sending invalidation messages between cluster nodes and informing whole cluster
+what records in underlying `realms` and `users` caches should be invalidated.
+
+=== Migrating to 2.3.0
+
+==== Default max results on paginated endpoints
+
+All Admin REST API endpoints that support pagination now have a default max results set to 100. If you want to return
+ more than 100 entries you need to explicitly specify that with `?max=<RESULTS>`.
+
+==== `realm-public-key` adapter property not recommended
+
+In 2.3.0 release we added support for Public Key Rotation. When admin rotates the realm keys in Keycloak admin console, the Client
+Adapter will be able to recognize it and automatically download new public key from Keycloak. However this automatic download of new
+keys is done just if you don't have `realm-public-key` option in your adapter with the hardcoded public key. For this reason, we don't recommend
+to use `realm-public-key` option in adapter configuration anymore.
+
+Note this option is still supported, but it may be useful just if you really want to have hardcoded public key in your adapter configuration
+and never download the public key from Keycloak. In theory, one reason for this can be to avoid man-in-the-middle attack if you have untrusted network between adapter and Keycloak,
+however in that case, it is much better option to use HTTPS, which will secure all the requests between adapter and Keycloak.
+
+==== Added infinispan cache `keys`
+
+In this release, we added new cache `keys` to the infinispan subsystem, which is defined in `standalone.xml` or `standalone-ha.xml` configuration file.
+It has also some eviction and expiration defined. This cache is internally used for caching the external public keys of the entities
+trusted by the server (Identity providers or clients, which uses authentication with signed JWT).
+
+=== Migrating to 2.2.0
+
+==== `databaseSchema` property deprecated
+
+The `databaseSchema` property for both JPA and Mongo is now deprecated and has been replaced by `initializeEmpty`
+and `migrationStrategy`. `initializeEmpty` can bet set to `true` or `false` and controls if an empty database should
+be initialized. `migrationStrategy` can be set to `update`, `validate` and `manual`. `manual` is only supported for
+relational databases and will write an SQL file with the required changes to the database schema. Please note that
+for Oracle database, the created SQL file contains `SET DEFINE OFF` command understood by Oracle SQL clients.
+Should the script be consumed by any other client, please replace the lines with equivalent command of the tool of
+your choice that disables variable expansion or remove it completely if such functionality is not applicable.
+
+==== Changes in Client's Valid Redirect URIs
+The following scenarios are affected:
+
+* When a Valid Redirect URI with query component is saved in a Client (e.g. `\http://localhost/auth?foo=bar`), `redirect_uri` in authorization request must exactly match this URI (or other registered URI in this Client).
+* When a Valid Redirect URI without a query component is saved in a Client, `redirect_uri` must exactly match as well.
+* Wildcards in registered Valid Redirect URIs are no longer supported when query component is present in this URI, so the `redirect_uri` needs to exactly match this saved URI as well.
+* Fragments in registered Valid Redirect URIs (like `\http://localhost/auth#fragment`) are no longer allowed.
+
+==== Authenticate by default removed from Identity Providers
+
+Identity providers no longer has an option to set it as a default authenticaton provider. Instead go to Authentication, select the `Browser` flow and configure the `Identity Provider Redirector`. It has an option to set the default identity provider.
+
+=== Migrating to 2.0.0
+
+==== Upgrading from 1.0.0.Final no longer supported
+
+Upgrading from 1.0.0.Final is no longer supported. To upgrade to this version upgrade to 1.9.8.Final prior to upgrading
+to 2.0.0.
+
+=== Migrating to 1.9.5
+
+==== Default password hashing interval increased to 20K
+
+The default password hashing interval for new realms has been increased to 20K (from 1 previously). This change will have an impact
+on performance when users authenticate. For example with the old default (1) it takes less than 1 ms to hash a password, but with
+the new default (20K) the same operation can take 50-100 ms.
+
+=== Migrating to 1.9.3
+
+==== Add User script renamed
+
+The script to add admin users to Keycloak has been renamed to `add-user-keycloak`.
+
+=== Migrating to 1.9.2
+
+==== Adapter option auth-server-url-for-backend-requests removed
+
+We've removed the option auth-server-url-for-backend-requests as there were issues in some scenarios when it was used. In more details,
+it was possible to access the Keycloak server from 2 different contexts (internal and external), which was causing issues in token validations etc.
+
+If you still want to use the optimization of network, which this option provided (avoid the application to send backchannel requests
+through loadbalancer but send them to local Keycloak server directly) you may need to handle it at hosts configuration (DNS) level.
+
+
+=== Migrating to 1.9.0
+
+==== Themes and providers directory moved
+
+We've moved the themes and providers directories from `standalone/configuration/themes` and `standalone/configuration/providers` to `themes` and `providers` respectively.
+If you have added custom themes and providers you need to move them to the new location.
+You also need to update `keycloak-server.json` as it's changed due to this.
+
+==== Adapter Subsystems only bring in dependencies if Keycloak is on
+
+Previously, if you had installed our SAML or OIDC Keycloak subsystem adapters into Wildfly or JBoss EAP, we would automatically include Keycloak client jars into EVERY application irregardless if you were using Keycloak or not.
+These libraries are now only added to your deployment if you have Keycloak authentication turned on for that adapter (via the subsystem, or auth-method in web.xml
+
+==== Client Registration service endpoints moved
+
+The Client Registration service endpoints have been moved from `{realm}/clients` to `{realm}/clients-registrations`.
+
+==== Session state parameter in authentication response renamed
+
+In the OpenID Connect authentication response we used to return the session state as `session-state` this is not correct according to the specification and has been renamed to `session_state`.
+
+==== Deprecated OpenID Connect endpoints
+
+In 1.2 we deprecated a number of endpoints that where not consistent with the OpenID Connect specifications, these have now been removed.
+This also applies to the validate token endpoints that was replaced with the new introspect endpoint in 1.8.
+
+==== Updates to theme templates
+
+Feedback in template.ftl has been moved and format has changed slightly.
+
+==== Module and Source Code Re-org
+
+Most of our modules and source code have been consolidated into two maven modules:  keycloak-server-spi and keycloak-services.
+SPI interfaces are in server-spi, implementations are in keycloak-services.
+All JPA dependent modules have been consolidated under keycloak-model-jpa.
+Same goes with mongo and Infinispan under modules keycloak-model-mongo and keycloak-model-infinispan.
+
+==== For adapters, session id changed after login
+
+To plug a security attack vector, for platforms that support it (Tomcat 8, Undertow/Wildfly, Jetty 9), the Keycloak OIDC and SAML adapters will change the session id after login.
+You can turn off this behavior check adapter config switches.
+
+==== SAML SP Client Adapter Changes
+
+Keycloak SAML SP Client Adapter now requires a specific endpoint, `/saml` to be registered with your IDP.
+
+=== Migrating to 1.8.0
+
+==== Admin account
+
+In previous releases we shipped with a default admin user with a default password, this has now been removed.
+If you are doing a new installation of 1.8 you will have to create an admin user as a first step.
+This can be done easily by following the steps in <<_create_admin_user,Admin User>>.
+
+==== OAuth2 Token Introspection
+
+In order to add more compliance with OAuth2 specification, we added a new endpoint for token introspection.
+The new endpoint can reached at `/realms/{realm}/protocols/openid-connect/token/introspect` and it is solely based on `RFC-7662.`
+
+The `/realms/{realm}/protocols/openid-connect/validate` endpoint is now deprecated and we strongly recommend you to move to the new introspection endpoint as soon as possible.
+The reason for this change is that RFC-7662 provides a more standard and secure introspection endpoint.
+
+The new token introspection URL can now be obtained from OpenID Connect Provider's configuration at `/realms/{realm}/.well-known/openid-configuration`.
+There you will find a claim with name `token_introspection_endpoint` within the response.
+Only `confidential clients` are allowed to invoke the new endpoint, where these clients will be usually acting as a resource server and looking for token metadata in order to perform local authorization checks.
+
+=== Migrating to 1.7.0.CR1
+
+==== Direct access grants disabled by default for clients
+
+In order to add more compliance with OpenID Connect specification, we added flags into admin console to Client Settings page, where you can enable/disable various kinds of OpenID Connect/OAuth2 flows (Standard flow, Implicit flow, Direct Access Grants, Service Accounts). As part of this, we have `Direct Access Grants` (corresponds to OAuth2 `Resource Owner Password Credentials Grant`) disabled by default for new clients.
+
+Clients migrated from previous version have `Direct Access Grants` enabled just if they had flag `Direct Grants Only` on.
+The `Direct Grants Only` flag was removed as if you enable Direct Access Grants and disable both Standard+Implicit flow, you will achieve same effect.
+
+We also added built-in client `admin-cli` to each realm.
+This client has `Direct Access Grants` enabled.
+So if you're using Admin REST API or Keycloak admin-client, you should update your configuration to use `admin-cli` instead of `security-admin-console` as the latter one doesn't have direct access grants enabled anymore by default.
+
+==== Option 'Update Profile On First Login' moved from Identity provider to Review Profile authenticator
+
+In this version, we added `First Broker Login`, which allows you to specify what exactly should be done when new user is logged through Identity provider (or Social provider), but there is no existing Keycloak user yet linked to the social account.
+As part of this work, we added option `First Login Flow` to identity providers where you can specify the flow and then you can configure this flow under `Authentication` tab in admin console.
+
+We also removed the option `Update Profile On First Login` from the Identity provider settings and moved it to the configuration of `Review Profile` authenticator.
+So once you specify which flow should be used for your Identity provider (by default it's `First Broker Login` flow), you go to `Authentication` tab, select the flow and then you configure the option under `Review Profile` authenticator.
+
+==== Element 'form-error-page' in web.xml not supported anymore
+
+form-error-page in web.xml will no longer work for client adapter authentication errors.
+You must define an error-page for the various HTTP error codes.
+See documentation for more details if you want to catch and handle adapter error conditions.
+
+==== IdentityProviderMapper changes
+
+There is no change in the interface itself or method signatures.
+However there is some change in behavior.
+We added `First Broker Login` flow in this release and the method `IdentityProviderMapper.importNewUser` is now called after `First Broker Login` flow is finished.
+So if you want to have any attribute available in `Review Profile` page, you would need to use the method `preprocessFederatedIdentity` instead of `importNewUser` . You can set any attribute by invoke `BrokeredIdentityContext.setUserAttribute` and that will be available on `Review profile` page.
+
+=== Migrating to 1.6.0.Final
+
+==== Option that refresh tokens are not reusable anymore
+
+Old versions of Keycloak allowed reusing refresh tokens multiple times.
+Keycloak still permits this, but also have an option `Revoke refresh token` to disallow it.
+Option is in in admin console under token settings.
+When a refresh token is used to obtain a new access token a new refresh token is also included.
+When option is enabled, then this new refresh token should be used next time the access token is refreshed.
+It won't be possible to reuse old refresh token multiple times.
+
+==== Some packages renamed
+
+We did a bit of restructure and renamed some packages.
+It is mainly about renaming internal packages of util classes.
+The most important classes used in your application ( for example AccessToken or KeycloakSecurityContext ) as well as the SPI are still unchanged.
+However there is slight chance that you will be affected and will need to update imports of your classes.
+For example if you are using multitenancy and KeycloakConfigResolver, you will be affected as for example class HttpFacade was moved to different package - it is `org.keycloak.adapters.spi.HttpFacade` now.
+
+==== Persisting user sessions
+
+We added support for offline tokens in this release, which means that we are persisting "offline" user sessions into database now.
+If you are not using offline tokens, nothing will be persisted for you, so you don't need to care about worse performance for more DB writes.
+However in all cases, you will need to update `standalone/configuration/keycloak-server.json` and add `userSessionPersister` like this:
+
+[source]
+----
+"userSessionPersister": {
+    "provider": "jpa"
+},
+----
+If you want sessions to be persisted in Mongo instead of classic RDBMS, use provider `mongo` instead.
+
+=== Migrating to 1.5.0.Final
+
+==== Realm and User cache providers
+
+Infinispan is now the default and only realm and user cache providers.
+In non-clustered mode a local Infinispan cache is used.
+We've also removed our custom in-memory cache and the no cache providers.
+If you have realmCache or userCache set in keycloak-server.json to mem or none please remove these.
+As Infinispan is the only provider there's no longer any need for the realmCache and userCache objects so these can be removed.
+
+==== Uses Session providers
+
+Infinispan is now the default and only user session provider.
+In non-clustered mode a local Infinispan cache is used.
+We've also removed the JPA and Mongo user session providers.
+If you have userSession set in keycloak-server.json to mem, jpa or mongo please remove it.
+As Infinispan is the only provider there's no longer any need for the userSession object so it can be removed.
+
+For anyone that wants to achieve increased durability of user sessions this can be achieved by configuring the user session cache with more than one owner or use a replicated cache.
+It's also possible to configure Infinispan to persist caches, although that would have impacts on performance.
+
+==== Contact details removed from registration and account management
+
+In the default theme we have now removed the contact details from the registration page and account management.
+The admin console now lists all the users attributes, not just contact specific attributes.
+The admin console also has the ability to add/remove attributes to a user.
+If you want to add contact details, please refer to the address theme included in the examples.
+
+=== Migrating to 1.3.0.Final
+
+==== Direct Grant API always enabled
+
+In the past Direct Grant API (or Resource Owner Password Credentials) was disabled by default and there was an option on a realm to enable it.
+The Direct Grant API is now always enabled and the option to enable/disable for a realm is removed.
+
+==== Database changed
+
+There are again few database changes.
+Remember to backup your database prior to upgrading.
+
+==== UserFederationProvider changed
+
+There are few minor changes in UserFederationProvider interface.
+You may need to sync your implementation when upgrade to newer version and upgrade few methods, which has changed signature.
+Changes are really minor, but were needed to improve performance of federation.
+
+==== WildFly 9.0.0.Final
+
+Following on from the distribution changes that was done in the last release the standalone download of Keycloak is now based on WildFly 9.0.0.Final.
+This also affects the overlay which can only be deployed to WildFly 9.0.0.Final or JBoss EAP 6.4.0.GA.
+WildFly 8.2.0.Final is no longer supported for the server.
+
+==== WildFly, JBoss EAP and JBoss AS7 adapters
+
+There are now 3 separate adapter downloads for WildFly, JBoss EAP and JBoss AS7:
+
+* eap6
+* wf9
+* wf8
+* as7
+
+Make sure you grab the correct one.
+
+You also need to update standalone.xml as the extension module and subsystem definition has changed.
+See <<_jboss_adapter_installation,Adapter Installation>> for details.
+
+=== Migrating from 1.2.0.Beta1 to 1.2.0.RC1
+
+==== Distribution changes
+
+Keycloak is now available in 3 downloads: standalone, overlay and demo bundle.
+The standalone is intended for production and non-JEE developers.
+Overlay is aimed at adding Keycloak to an existing WildFly 8.2 or EAP 6.4 installation and is mainly for development.
+Finally we have a demo (or dev) bundle that is aimed at developers getting started with Keycloak.
+This bundle contains a WildFly server, with Keycloak server and adapter included.
+It also contains all documentation and examples.
+
+==== Database changed
+
+This release contains again a number of changes to the database.
+The biggest one is Application and OAuth client merge.
+Remember to backup your database prior to upgrading.
+
+==== Application and OAuth client merge
+
+Application and OAuth clients are now merged into `Clients`.
+The UI of admin console is updated and database as well.
+Your data from database should be automatically updated.
+The previously set Applications will be converted into Clients with `Consent required` switch off and OAuth Clients will be converted into Clients with this switch on.
+
+=== Migrating from 1.1.0.Final to 1.2.0.Beta1
+
+==== Database changed
+
+This release contains a number of changes to the database.
+Remember to backup your database prior to upgrading.
+
+==== `iss` in access and id tokens
+
+The value of `iss` claim in access and id tokens have changed from `realm name` to `realm url`.
+This is required by OpenID Connect specification.
+If you're using our adapters there's no change required, other than if you've been using bearer-only without specifying `auth-server-url` you have to add it now.
+If you're using another library (or RSATokenVerifier) you need to make the corresponding changes when verifying `iss`.
+
+==== OpenID Connect endpoints
+
+To comply with OpenID Connect specification the authentication and token endpoints have been changed to having a single authentication endpoint and a single token endpoint.
+As per-spec `response_type` and `grant_type` parameters are used to select the required flow.
+The old endpoints (`/realms/{realm}/protocols/openid-connect/login`, `/realms/{realm}/protocols/openid-connect/grants/access`, `/realms/{realm}/protocols/openid-connect/refresh`, `/realms/{realm}/protocols/openid-connect/access/codes)` are now deprecated and will be removed in a future version.
+
+==== Theme changes
+
+The layout of themes have changed.
+The directory hierarchy used to be `type/name` this is now changed to `name/type`.
+For example a login theme named `sunrise` used to be deployed to `standalone/configuration/themes/login/sunrise`, which is now moved to `standalone/configuration/themes/sunrise/login`.
+This change was done to make it easier to have group the different types for the same theme into one folder.
+
+If you deployed themes as a JAR in the past you had to create a custom theme loader which required Java code.
+This has been simplified to only requiring a plain text file (`META-INF/keycloak-themes.json`) to describe the themes included in a JAR.
+See the <<_themes,themes>> section in the docs for more information.
+
+==== Claims changes
+
+Previously there was `Claims` tab in admin console for application and OAuth clients.
+This was used to configure which attributes should go into access token for particular application/client.
+This was removed and replaced with <<_mappers,Protocol mappers>>, which are more flexible.
+
+You don't need to care about migration of database from previous version.
+We did migration scripts for both RDBMS and Mongo, which should ensure that claims configured for particular application/client will be converted into corresponding protocol mappers (Still it's safer to backup DB before migrating to newer version though). Same applies for exported JSON representation from previous version.
+
+==== Social migration to identity brokering
+
+We refactored social providers SPI and replaced it with <<_identity_broker,identity brokering SPI>>, which is more flexible.
+The `Social` tab in admin console is renamed to `Identity Provider` tab.
+
+Again you don't need to care about migration of database from previous version similarly like for Claims/protocol mappers.
+Both configuration of social providers and "social links" to your users will be converted to corresponding Identity providers.
+
+Only required action from you would be to change allowed `Redirect URI` in the admin console of particular 3rd party social providers.
+You can first go to the Keycloak admin console and copy Redirect URI from the page where you configure the identity provider.
+Then you can simply paste this as allowed Redirect URI to the admin console of 3rd party provider (IE.
+Facebook admin console).
+
+=== Migrating from 1.1.0.Beta2 to 1.1.0.Final
+
+* WEB-INF/lib
++`standalone/configuration/providers`<<_providers,+providers>>
+
+
+=== Migrating from 1.1.0.Beta1 to 1.1.0.Beta2
+
+* Adapters are now a separate download.  They are not included in appliance and war distribution.  We have too many now and the distro
+  is getting bloated.
+* org.keycloak.adapters.tomcat7.KeycloakAuthenticatorValve
++`org.keycloak.adapters.tomcat.KeycloakAuthenticatorValve`
+
+* JavaScript adapter now has idToken and idTokenParsed properties. If you use idToken to retrieve first name, email, etc. you need to change this to idTokenParsed.
+* The as7-eap-subsystem and keycloak-wildfly-subsystem have been merged into one keycloak-subsystem.  If you have an existing standalone.xml
+  or domain.xml, you will need edit near the top of the file and change the extension module name to org.keycloak.keycloak-subsystem.
+  For AS7 only, the extension module name is org.keycloak.keycloak-as7-subsystem.
+* Server installation is no longer supported on AS7.  You can still use AS7 as an application client.
+
+=== Migrating from 1.0.x.Final to 1.1.0.Beta1
+
+* RealmModel JPA and Mongo storage schema has changed
+* UserSessionModel JPA and Mongo storage schema has changed as these interfaces have been refactored
+* Upgrade your adapters, old adapters are not compatible with Keycloak 1.1.  We interpreted JSON Web Token and OIDC ID Token specification incorrectly.  'aud'
+  claim must be the client id, we were storing the realm name in there and validating it.
+
+=== Migrating from 1.0 RC-1 to RC-2
+
+* A lot of info level logging has been changed to debug. Also, a realm no longer has the jboss-logging audit listener by default.
+  If you want log output when users login, logout, change passwords, etc. enable the jboss-logging audit listener through the admin console.
+
+=== Migrating from 1.0 Beta 4 to RC-1
+
+* logout REST API has been refactored.  The GET request on the logout URI does not take a session_state
+  parameter anymore.  You must be logged in in order to log out the session.
+  You can also POST to the logout REST URI.  This action requires a valid refresh token to perform the logout.
+  The signature is the same as refresh token minus the grant type form parameter.  See documentation for details.
+
+=== Migrating from 1.0 Beta 1 to Beta 4
+
+* LDAP/AD configuration is changed.  It is no longer under the "Settings" page.  It is now under
+  Users->Federation.  Add Provider will show you an "ldap" option.
+* Authentication SPI has been removed and rewritten.  The new SPI is UserFederationProvider and is
+  more flexible.
+* ssl-not-required
++`ssl-required`
++`all`
++`external`
++`none`
+
+* DB Schema has changed again.
+* Created applications now have a full scope by default.  This means that you don't have to configure
+  the scope of an application if you don't want to.
+* Format of JSON file for importing realm data was changed. Now role mappings is available under the JSON record of particular
+  user.
+
+=== Migrating from 1.0 Alpha 4 to Beta 1
+
+* DB Schema has changed.  We have added export of the database to Beta 1, but not the ability to import
+  the database from older versions. This will be supported in future releases.
+* For all clients except bearer-only applications, you must specify at least one redirect URI.  Keycloak
+  will not allow you to log in unless you have specified a valid redirect URI for that application.
+* Direct Grant API
++`ON`
+
+* standalone/configuration/keycloak-server.json
+* JavaScript adapter
+* Session Timeout
+
+=== Migrating from 1.0 Alpha 2 to Alpha 3
+
+* SkeletonKeyToken, SkeletonKeyScope, SkeletonKeyPrincipal, and SkeletonKeySession have been renamed to:
+  AccessToken, AccessScope, KeycloakPrincipal, and KeycloakAuthenticatedSession respectively.
+* ServleOAuthClient.getBearerToken() method signature has changed.  It now returns an AccessTokenResponse
+  so that you can obtain a refresh token too.
+* Adapters now check the access token expiration with every request.  If the token is expired, they will
+  attempt to invoke a refresh on the auth server using a saved refresh token.
+* Subject in AccessToken has been changed to the User ID.
+
+=== Migrating from 1.0 Alpha 1 to Alpha 2
+
+* DB Schema has changed.  We don't have any data migration utilities yet as of Alpha 2.
+* JBoss and Wildfly adapters are now installed via a JBoss/Wildfly subsystem.  Please review the adapter
+  installation documentation.  Edits to standalone.xml are now required.
+* There is a new credential type "secret".  Unlike other credential types, it is stored in plain text in
+  the database and can be viewed in the admin console.
+* There is no longer required Application or OAuth Client credentials.  These client types are now
+  hard coded to use the "secret" credential type.
+* Because of the "secret" credential change to Application and OAuth Client, you'll have to update
+  your keycloak.json configuration files and regenarate a secret within the Application or OAuth Client
+  credentials tab in the administration console.

upgrading/topics/keycloak/intro.adoc

@@ -0,0 +1,9 @@
+[[intro]]
+
+== Introduction
+
+This guide describes how to upgrade {project_name}. It is recommended that you start by upgrading the {project_name}
+server first and {project_name} adapters second.
+
+Before upgrading make sure to read the instructions carefully and carefully review the changes listed in
+<<migration-changes,Migration Chanages>>.

upgrading/topics/keycloak/upgrading.adoc

@@ -0,0 +1,16 @@
+[[_upgrading]]
+
+== Upgrading {project_name} Server
+
+include::../prep_migration.adoc[leveloffset=1]
+
+include::../install_new_version.adoc[leveloffset=1]
+
+include::../migrate_db.adoc[leveloffset=1]
+
+include::../migrate_themes.adoc[leveloffset=1]
+
+
+== Upgrading {project_name} Adapters
+
+include::../upgrade_adapters.adoc[leveloffset=1]

upgrading/topics/migrate_db.adoc

@@ -0,0 +1,56 @@
+[[_migrate_db]]
+
+== Migrating the Database
+
+{project_name} can automatically migrate the database schema, or you can choose to do it manually. By default the
+database is automatically migrated when you start the new installation for the first time.
+
+=== Automatic Relational Database Migration
+
+To enable automatic upgrading of the database schema, set the migrationStrategy property value to "update" for the
+default connectionsJpa provider:
+
+ <spi name="connectionsJpa">
+    <provider name="default" enabled="true">
+        <properties>
+            ...
+            <property name="migrationStrategy" value="update"/>
+        </properties>
+    </provider>
+</spi>
+
+Or run this CLI command:
+
+[source,bash]
+----
+/subsystem=keycloak-server/spi=connectionsJpa/provider=default/:map-put(name=properties,key=migrationStrategy,value=update)
+----
+
+When you start the server with this setting your database is automatically migrated if the database schema has changed
+in the new version.
+
+=== Manual Relational Database Migration
+
+To enable manual upgrading of the database schema, set the migrationStrategy property value to "manual" for the default
+connectionsJpa provider:
+
+ <spi name="connectionsJpa">
+    <provider name="default" enabled="true">
+        <properties>
+            ...
+            <property name="migrationStrategy" value="manual"/>
+        </properties>
+    </provider>
+</spi>
+
+Or run this CLI command:
+
+[source,bash]
+----
+/subsystem=keycloak-server/spi=connectionsJpa/provider=default/:map-put(name=properties,key=migrationStrategy,value=manual)
+----
+
+When you start the server with this configuration it checks if the database needs to be migrated. The required changes
+are written to an SQL file that you can review and manually run against the database. For further details on how to
+apply this file to the database, see the documentation for the relational database you’re using. After the changes have
+been written to the file, the server exits.

upgrading/topics/migrate_themes.adoc

@@ -0,0 +1,84 @@
+[[_migrate_themes]]
+
+== Migrating Themes
+
+If you have created any custom themes they must be migrated to the new server. Any changes to the built-in themes might
+need to be reflected in your custom themes, depending on which aspects you have customized.
+
+You must copy your custom themes from the old server “themes” directory to the new server “themes” directory.
+After that you need to review the changes below and consider if the changes need to be applied to your custom theme.
+
+In summary:
+
+* If you have customized any of the changed templates listed below you need to compare the template from the base theme
+  to see if there are changes you need to apply.
+* If you have customized any of the styles and are extending the {project_name} themes you need to review the changes to
+  the styles. If you are extending the base theme you can skip this step.
+* If you have customized messages you might need to change the key or value or to add additional messages.
+
+ifeval::[{project_product}==true]
+Each step is described in more detail below the list of changes.
+
+include::rhsso/migrate_themes-changes-71.adoc[leveloffset=0]
+endif::[]
+
+=== Migrating Templates
+
+If you have customized any of the templates you need to carefully review the changes that have been made to the templates
+to decide if you need to apply these changes to your customized templates. Most likely you will need to apply the same
+changes to your customized templates. If you have not customized any of the listed templates you can skip this section.
+
+A best practice is to use a diff tool to compare the templates to see what changes you might need to make to your
+customized template. If you have only made minor changes it is simpler to compare the updated template to your
+customized template. However, if you have made many changes it might be easier to compare the new template to your
+customized old template, as this will show you what changes you need to make.
+
+The following screenshot compares the info.ftl template from the Login theme and an example custom theme:
+
+.Comparison of the updated version of a Login theme template with an example custom Login theme template
+image:images/theme-migration-meld-info-1.png[]
+
+From this comparison it is easy to identify that the first change (“Hello world!!”) was a customization, while the
+second change (“if pageRedirectUri”) is a change to the base theme. By copying the second change to your custom template,
+you have successfully updated your customized template.
+
+For the alternative approach the following screenshot compares the info.ftl template from the old installation with
+the updated info.ftl template from the new installation:
+
+.Comparison of an example custom Login theme template with the updated version of the Login theme template
+image:images/theme-migration-meld-info-2.png[]
+
+From this comparison it is easy to identify what has been changed in the base template. You will then manually have to
+make the same changes to your modified template. Since this approach is not as simple as the first approach, only use
+this approach if the first one is not feasible.
+
+=== Migrating Messages
+
+If you have added support for another language, you need to apply all the changes listed above. If you have not added
+support for another language, you might not need to change anything; you only have to make changes if you have changed
+an affected message in your theme.
+
+For added values, review the value of the message in the base theme to determine if you need to customize that message.
+
+For renamed keys, rename the key in your custom theme.
+
+For changed values, check the value in the base theme to determine if you need to make changes to your custom theme.
+
+=== Migrating Styles
+
+If you are inheriting styles from the keycloak or rh-sso themes you might need to update your custom styles to reflect
+changes made to the styles from the built-in themes.
+
+A best practice is to use a diff tool to compare the changes to stylesheets between the old server installation and the
+new server installation.
+
+For example, using the diff command:
+
+[source,bash,subs=+attributes]
+----
+$ diff {project_dirref}_OLD/themes/keycloak/login/resources/css/login.css \
+{project_dirref}_NEW/themes/keycloak/login/resources/css/login.css
+----
+
+Review the changes and determine if they affect your custom styling.
+

upgrading/topics/prep_migration.adoc

@@ -0,0 +1,20 @@
+[[_prep_migration]]
+
+== Preparing for Upgrading
+
+Before you upgrade, be aware of the order in which you need to perform the upgrade steps. Also note potential issues
+that can occur within the upgrade process. In general, you must upgrade {project_name} server first, and then upgrade
+the adapters.
+
+. Prior to applying the upgrade, handle any open transactions and delete the data/tx-object-store/ transaction directory.
+. Back up the old installation (configuration, themes, and so on).
+. Back up the database. For detailed information on how to back up the database, see the documentation for the relational
+  database you’re using.
+. Upgrade {project_name} server.
+* Testing the upgrade in a non-production environment first, to prevent any installation issues from being exposed in
+  production, is a best practice.
+* Be aware that after the upgrade the database will no longer be compatible with the old server
+* Ensure the upgraded server is functional before upgrading adapters in production.
+. If you need to revert the upgrade, first restore the old installation, and then restore the database from the backup copy.
+. Upgrade the adapters.
+

upgrading/topics/rhsso/changes.adoc

@@ -0,0 +1,24 @@
+== About Changes from RH-SSO 7.0 to RH-SSO 7.1
+
+The following changes have occurred from RH-SSO 7.0 to RH-SSO 7.1. Review these changes carefully before upgrading.
+
+=== Realm Keys
+For RH-SSO 7.0 only one set of keys could be associated with a realm. This meant that when changing the keys all current cookies and tokens would be invalidated and all users would have to re-authenticate. For RH-SSO 7.1 support for multiple keys for one realm has been added. At any given time one set of keys is the active keys used for signatures, but there can be multiple keys used to verify signatures. This means that old cookies and tokens can be verified, then refreshed with the new signatures, allowing users to remain authenticated when keys are changed. There are also some changes to how keys are managed through the Admin Console and Admin REST API; for more details see link:{adminguide_link}#realm_keys[Realm Keys] in the _{adminguide_name}_.
+
+To allow seamless key rotation you must remove hard-coded keys from client adapters. The client adapters will automatically retrieve keys from the server as long as the realm key is not specified. Client adapters will also retrieve new keys automatically when keys are rotated.
+
+=== Client Redirect URI Matching
+For RH-SSO 7.0 query parameters are ignored when matching valid redirect URIs for a client. For RH-SSO 7.1 query parameters are no longer ignored. If you need to include query parameters in the redirect URI you must specify the query parameters in the valid redirect URI for the client (for example, \https://hostname/app/login?foo=bar) or use a wildcard (for example, \https://hostname/app/login/*). Fragments are also no longer permitted in Valid Redirect URIs (that is, \https://hostname/app#fragment).
+
+=== Automatically Redirect to Identity Provider
+For RH-SSO 7.1, identity providers cannot be set as the default authentication provider. To automatically redirect to an identity provider for RH-SSO 7.1 you must now configure the identity provider redirector. For more information see link:{adminguide_link}#default_identity_provider[Default Identity Provider] in the _{adminguide_name}_. If you previously had an identity provider with the default authentication provider option set, this value is automatically used as the value for the identity provider redirector when the server is upgraded to RH-SSO 7.1.
+
+=== Admin REST API
+For RH-SSO 7.0 paginated endpoints in the Admin REST API return all results if the maxResults query parameter was not specified. This could cause issues with a temporary high load and requests timing out when a large number of results were returned (for example, users). For RH-SSO 7.1 a maximum of 100 results are returned if a value for maxResults is not specified. You can return all results by specifying maxResults as -1.
+
+=== Server Configuration
+For RH-SSO 7.0 server configuration is split between the keycloak-server.json file and the standalone/domain.xml or domain.xml file. For RH-SSO 7.1 the keycloak-server.json file has been removed and all server configuration is done through the standalone.xml or domain.xml file. The upgrading procedure for RH-SSO 7.1 automatically migrates the server configuration from the keycloak-server.json file to the standalone.xml or domain.xml file.
+
+=== Key Encryption Algorithm in SAML Assertions
+For RH-SSO 7.1, keys in SAML assertions and documents are now encrypted using the RSA-OAEP encryption scheme. To use encrypted assertions, ensure your service providers support this encryption scheme. In the event that you have service providers that do not support RSA-OAEP, RH-SSO can be configured to use the legacy RSA-v1.5 encryption scheme by starting the server with the system property “keycloak.saml.key_trans.rsa_v1.5” set to true. If you do this  you should upgrade your service providers as soon as possible to be able to revert to the more secure RSA-OAEP encryption scheme.
+

upgrading/topics/rhsso/intro.adoc

@@ -0,0 +1,43 @@
+[[intro]]
+
+== Introduction
+
+Red Hat Single Sign-On (RH-SSO) 7.1 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.0 to Red Hat Single Sign-On 7.1.
+
+=== About Upgrades
+
+==== 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.0 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.0 to Red Hat Single Sign-On 7.1, 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 7 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 7.1.0 to 7.1.1. These release
+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 7.1.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.

upgrading/topics/rhsso/migrate_themes-changes-71.adoc

@@ -0,0 +1,25 @@
+The changes that have been made for RH-SSO 7.1 include:
+
+**Templates**
+
+* Account: account.ftl
+* Account: federatedIdentity.ftl
+* Account: totp.ftl
+* Login: info.ftl
+* Login: login-config-totp.ftl
+* Login: login-reset-password.ftl
+* Login: login.ftl
+
+**Messages**
+
+* Account: editAccountHtmlTtile renamed to editAccountHtmlTitle
+* Account: role_uma_authorization added
+* Login: loginTotpStep1 value changed
+* Login: invalidPasswordGenericMessage added
+* Login: invlidRequesterMessage renamed to invalidRequesterMessage
+* Login: clientDisabledMessage added
+
+**Styles**
+
+* Account: account.css
+* Login: login.css

upgrading/topics/rhsso/patching-rpm-installation.adoc

@@ -0,0 +1,20 @@
+[[rpm-patching]]
+= Patching an RPM Installation
+
+.Prerequisites
+* Ensure that the base operating system is up to date, and is subscribed and enabled to get updates from the standard Red Hat Enterprise Linux repositories.
+* Ensure that you are subscribed to the relevant RH-SSO repository for the update.
+* Back up all configuration files, deployments, and user data.
+
+[IMPORTANT]
+====
+For a managed domain, the RH-SSO domain controller should be updated first.
+====
+
+
+To install a RH-SSO patch via RPM from your subscribed repository, update your Red Hat Enterprise Linux system using the following command:
+
+[source,bash,options="nowrap"]
+----
+yum update
+----

upgrading/topics/rhsso/patching-zip-installation.adoc

@@ -0,0 +1,155 @@
+[[zip-patching]]
+= Patching a ZIP/Installer Installation
+
+Patches for a ZIP installation of RH-SSO are available to download from the
+link:https://access.redhat.com/[Red Hat Customer Portal].
+
+For multiple RH-SSO hosts in a managed domain environment, individual hosts can be patched from your RH-SSO domain controller.
+
+In addition to applying a patch, you can also roll back the application of a patch.
+
+== Important Notes on ZIP Installation Patching
+
+* If you apply a patch that updates a module, the new patched JARs that are used at runtime are stored in `RHSSO_HOME/modules/system/layers/base/.overlays/_PATCH_ID_/_MODULE_`. The original unpatched files are left in `RHSSO_HOME/modules/system/layers/base/_MODULE_`, but these JARs are *not* used at runtime.
+* In order to significantly decrease the size of cumulative patch releases for RH-SSO 7 you cannot perform a partial roll back of a cumulative patch. For a patch that has been applied, you will only be able to roll back the whole patch.
++
+For example, if you apply CP03 to RH-SSO 7.0.0, you will not be able to roll back to CP01 or CP02. If you would like the ability to roll back to each cumulative patch release, each cumulative patch must be applied separately in the order they were released.
+
+== Applying a Patch
+
+NOTE:  RH-SSO servers that have been installed using the RPM method cannot be updated using these instructions. See the xref:rpm-patching[RPM instructions for applying a patch] instead.
+
+
+You can apply downloaded patches to a RH-SSO server using either the xref:zip_patching_management_cli[management CLI] or the xref:zip_patching_management_console[management console].
+
+[[zip_patching_management_cli]]
+.Applying a Patch to RH-SSO Using the Management CLI
+
+. Download the patch file from the Red Hat Customer Portal at https://access.redhat.com/downloads/.
+
+. From the link:{appserver_managementcli_link}[management CLI], apply the patch using the following command, including the appropriate path to the patch file:
++
+[options="nowrap"]
+----
+patch apply /path/to/downloaded-patch.zip
+----
++
+[NOTE]
+====
+To patch another RH-SSO host in a managed domain, you can specify the RH-SSO host name using the `--host=` argument. For example:
+
+[options="nowrap"]
+----
+patch apply /path/to/downloaded-patch.zip --host=my-host
+----
+====
++
+The patch tool will warn if there are any conflicts in attempting to apply the patch. If there are conflicts, enter `patch --help` for the available arguments to re-run the command with an argument specifying how to resolve the conflicts.
+
+. Restart the RH-SSO server for the patch to take effect:
++
+[options="nowrap"]
+----
+shutdown --restart=true
+----
+
+[[zip_patching_management_console]]
+.Applying a Patch to RH-SSO Using the Management Console
+. Download the patch file from the Red Hat Customer Portal at https://access.redhat.com/downloads/.
+. Open the link:{appserver_managementconsole_link}[management console] and navigate to the *Patch Management* view.
+.. For a standalone server, click the *Patching* tab.
++
+.The Patch Management Screen for a Standalone Server
+image:images/patching-standalone-tab.png[The Patch Management Screen for a Standalone Server]
+.. For a server in a managed domain, click the *Patching* tab, then select the host that you want to patch from the table, and click *View*.
++
+.The Patch Management Screen for a Managed Domain
+image:images/patching-domain-tab.png[The Patch Management Screen for a Managed Domain]
+
+. Click *Apply a New Patch*.
+.. If you are patching a managed domain host, on the next screen select whether to shutdown the servers on the host, and click *Next*.
+
+. Click the *Browse* button, select the downloaded patch you want to apply, and then click *Next*.
++
+.Apply Patch Screen
+image:images/patching-select-patch.png[Apply Patch Screen]
+.. If there are any conflicts in attempting to apply the patch, a warning will be displayed. Click *View error details* to see the detail of the conflicts. If there is a conflict, you can either cancel the operation, or select the *Override all conflicts* check box and click *Next*. Overriding conflicts will result in the content of the patch overriding any user modifications.
+
+. After the patch has been successfully applied, select whether to restart RH-SSO now for the patch to take effect, and click *Finish*.
+
+== Rolling Back a Patch
+
+You can roll back a previously applied RH-SSO patch using either the xref:zip_rollback_management_cli[management CLI] or the xref:zip_rollback_management_console[management console].
+
+IMPORTANT: Rolling back a patch using the patch management system is not intended as a general uninstall functionality. It is only intended to be used immediately after the application of a patch that had undesirable effects.
+
+.Prerequisites
+* A patch that was previously applied.
+
+[WARNING]
+====
+When following either procedure, use caution when specifying the value of the `Reset Configuration` option:
+
+If set to `TRUE`, the patch rollback process will also roll back the RH-SSO server configuration files to their pre-patch state. Any changes that were made to the RH-SSO server configuration files after the patch was applied will be lost.
+
+If set to `FALSE`, the server configuration files will not be rolled back. In this situation, it is possible that the server will not start after the rollback, as the patch may have altered configurations, such as namespaces, which may no longer be valid and will have to be fixed manually.
+====
+
+[[zip_rollback_management_cli]]
+.Rolling Back a Patch Using the Management CLI
+. From the management CLI, use the `patch history` command to find the ID of the patch that you want to roll back.
++
+--
+NOTE: If you are using a managed domain, you must add the `--host=_HOSTNAME_` argument to the commands in this procedure to specify the RH-SSO host.
+--
+
+. Roll back the patch with the appropriate patch ID from the previous step.
++
+[options="nowrap"]
+----
+patch rollback --patch-id=PATCH_ID --reset-configuration=TRUE
+----
++
+The patch tool will warn if there are any conflicts in attempting to roll back the patch. If there are conflicts, enter `patch --help` for the available arguments to re-run the command with an argument specifying how to resolve the conflicts.
+
+.  Restart the RH-SSO server for the patch roll back to take effect:
++
+[options="nowrap"]
+----
+shutdown --restart=true
+----
+
+[[zip_rollback_management_console]]
+.Rolling Back a Patch Using the Management Console
+. Open the management console and navigate to the *Patch Management* view.
+.. For a standalone server, click the *Patching* tab.
+.. For a server in a managed domain, click the *Patching* tab, then select the host that you want to patch from the table, and click *View*.
+
+. Select the patch that you want to rollback from those listed in the table, then click *Rollback*.
++
+.Recent Patch History Screen
+image:images/patching-rollback-table.png[Recent Patch History Screen]
+.. If you are rolling back a patch on a managed domain host, on the next screen select whether to shutdown the servers on the host, and click *Next*.
+
+. Choose your options for the rollback process, then click *Next*.
++
+.Patch Rollback Options
+image:images/patching-rollback-options.png[Patch Rollback Options]
+
+. Confirm the options and the patch to be rolled back, then click *Next*.
+.. If there are any conflicts in attempting to rollback the patch and the *Override all* option was not selected, a warning will be displayed. Click *View error details* to see the detail of the conflicts. If there is a conflict, you can either cancel the operation, or click *Choose Options* and try the operation again with the *Override all* check box selected. Overriding conflicts will result in the rollback operation overriding any user modifications.
+
+. After the patch has been successfully rolled back, select whether to restart the RH-SSO server now for the changes to take effect, and click *Finish*.
+
+== Clearing Patch History
+
+When patches are applied to a RH-SSO server, the content and history of the patches are preserved for use in rollback operations. If multiple cumulative patches are applied, the patch history may use a significant amount of disk space.
+
+You can use the following management CLI command to remove all older patches that are not currently in use. When using this command, only the latest cumulative patch is preserved along with the GA release. This is only useful for freeing space if multiple cumulative patches have previously been applied.
+
+[options="nowrap"]
+----
+/core-service=patching:ageout-history
+----
+
+IMPORTANT: If you clear the patch history, you will not be able to roll back a previously applied patch.

upgrading/topics/rhsso/patching_adapters.adoc

@@ -0,0 +1,20 @@
+[[_patching_js_adapter]]
+==== Patching the JavaScript Adapter
+
+There are no patching mechanism available for the JavaScript adapter and this is distributed as a complete new download.
+To upgrade a JavaScript adapter that has been copied to your web application, complete the following steps:
+
+. Download the new archive.
+. Overwrite the keycloak.js file in your application with the keycloak.js file from the downloaded archive.
+
+
+[[_patching_nodejs_adapter]]
+==== Patching the Node.js Adapter
+
+There are no patching mechanism available for the Node.js adapter and this is distributed as a complete new download.
+To upgrade a Node.js adapter that has been copied to your web application, complete the following steps:
+
+. Download the new archive.
+. Remove the existing Node.js adapter directory
+. Unzip the updated file into its place
+. Change the dependency for keycloak-connect in the package.json of your application

upgrading/topics/rhsso/upgrading.adoc

@@ -0,0 +1,31 @@
+[[_upgrading]]
+
+== Upgrading {project_name} Server
+
+The upgrade process for the {project_name} server is different if you are upgrading to a different
+minor release or not.
+
+If you are upgrading to a new minor release, for example from 7.0.0 to 7.1.0, follow the steps in xref:_upgrading_minor[Minor Upgrades].
+
+If you are upgrading to a new micro release, for example from 7.1.0 to 7.1.1, follow the steps in xref:_upgrading_micro[Micro Upgrades].
+
+[[_upgrading_minor]]
+=== Minor Upgrades
+
+include::../prep_migration.adoc[leveloffset=2]
+
+include::../install_new_version.adoc[leveloffset=2]
+
+include::../migrate_db.adoc[leveloffset=2]
+
+include::../migrate_themes.adoc[leveloffset=2]
+
+[[_upgrading_micro]]
+=== Micro Upgrades
+
+include::patching-zip-installation.adoc[leveloffset=3]
+include::patching-rpm-installation.adoc[leveloffset=3]
+
+== Upgrading {project_name} Adapters
+
+include::../upgrade_adapters.adoc[leveloffset=1]

upgrading/topics/templates

@@ -0,0 +1 @@
+../../topics/templates

upgrading/topics/upgrade_adapters.adoc

@@ -0,0 +1,35 @@
+[[_upgrade_adapters]]
+
+It is important that you upgrade {project_name} server first, and then upgrade the adapters. Earlier versions of the
+adapter might work with later versions of {project_name} server, but earlier versions of {project_name} server might not
+work with later versions of the adapter.
+
+
+[[_upgrade_eap_adapter]]
+== Upgrading the EAP Adapter
+
+To upgrade the {appserver_name} adapter, complete the following steps:
+
+. Download the new adapter archive.
+. Remove the previous adapter modules by deleting the `{appserver_dirref}/modules/system/add-ons/keycloak/` directory.
+. Unzip the downloaded archive into {appserver_dirref}.
+
+
+[[_upgrade_js_adapter]]
+== Upgrading the JavaScript Adapter
+
+To upgrade a JavaScript adapter that has been copied to your web application, complete the following steps: 
+
+. Download the new adapter archive.
+. Overwrite the keycloak.js file in your application with the keycloak.js file from the downloaded archive.
+
+
+[[_upgrade_nodejs_adapter]]
+== Upgrading the Node.js Adapter
+
+To upgrade a Node.js adapter that has been copied to your web application, complete the following steps:
+
+. Download the new adapter archive.
+. Remove the existing Node.js adapter directory
+. Unzip the updated file into its place
+. Change the dependency for keycloak-connect in the package.json of your application