Merge pull request #829 from stianst/master
KEYCLOAK-805 Add overview section to migration docs
This commit is contained in:
Stian Thorgersen
commit
da5332608c
1 changed files with 211 additions and 130 deletions
|
|
@ -1,23 +1,103 @@
|
|||
<chapter id="Migration_from_older_versions">
|
||||
<title>Migration from older versions</title>
|
||||
<sect1>
|
||||
|
||||
<para>
|
||||
To upgrade to a new version of Keycloak first download and install the new version of Keycloak. You then have to
|
||||
migrate the database, keycloak-server.json, providers, themes and applications from the old version.
|
||||
</para>
|
||||
|
||||
<section>
|
||||
<title>Migrate database</title>
|
||||
<para>
|
||||
Keycloak provides automatic migration of the database. It's highly recommended that you backup your
|
||||
database prior to upgrading Keycloak.
|
||||
</para>
|
||||
<para>
|
||||
To enable automatic upgrading of the database if you're using a relational database make sure
|
||||
<literal>databaseSchema</literal> is set to <literal>update</literal> for <literal>connectionsJpa</literal>:
|
||||
<programlisting>
|
||||
"connectionsJpa": {
|
||||
"default": {
|
||||
...
|
||||
"databaseSchema": "update"
|
||||
}
|
||||
}
|
||||
</programlisting>
|
||||
</para>
|
||||
<para>
|
||||
For MongoDB do the same, but for <literal>connectionsMongo</literal>:
|
||||
<programlisting>
|
||||
"connectionsMongo": {
|
||||
"default": {
|
||||
...
|
||||
"databaseSchema": "update"
|
||||
}
|
||||
}
|
||||
</programlisting>
|
||||
</para>
|
||||
<para>
|
||||
When you start the server with this setting your database will automatically be migrated if the database
|
||||
schema has changed in the new version.
|
||||
</para>
|
||||
</section>
|
||||
|
||||
<section>
|
||||
<title>Migrate keycloak-server.json</title>
|
||||
<para>
|
||||
You should copy <literal>standalone/configuration/keycloak-server.json</literal> from the old version to
|
||||
make sure any configuration changes you've done are added to the new installation. The version specific
|
||||
section below will list any changes done to this file that you have to do when upgrading from one version
|
||||
to another.
|
||||
</para>
|
||||
</section>
|
||||
|
||||
<section>
|
||||
<title>Migrate providers</title>
|
||||
<para>
|
||||
If you have implemented any SPI providers you need to copy them to the new server. The version
|
||||
specific section below will mention if any of the SPI's have changed. If they have you may have to update
|
||||
your code accordingly.
|
||||
</para>
|
||||
</section>
|
||||
|
||||
<section>
|
||||
<title>Migrate themes</title>
|
||||
<para>
|
||||
If you have created a custom theme you need to copy them to the new server. The version specific section below
|
||||
will mention if changes have been made to themes. If there is you may have to update your themes accordingly.
|
||||
</para>
|
||||
</section>
|
||||
|
||||
<section>
|
||||
<title>Migrate application</title>
|
||||
<para>
|
||||
If you deploy applications directly to the Keycloak server you should copy them to the new server. For any
|
||||
applications including those not deployed directly to the Keycloak server you should upgrade the adapter.
|
||||
The version specific section below will mention if any changes are required to applications.
|
||||
</para>
|
||||
</section>
|
||||
|
||||
<section>
|
||||
<title>Version specific migration</title>
|
||||
<section>
|
||||
<title>Migrating from 1.0.x.Final to 1.1.Beta1</title>
|
||||
<itemizedlist>
|
||||
<listitem>RealmModel JPA and Mongo storage schema has changed</listitem>
|
||||
<listitem>UserSessionModel JPA and Mongo storage schema has changed as these interfaces have been refactored</listitem>
|
||||
<listitem>
|
||||
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.
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
</sect1>
|
||||
<sect1>
|
||||
</section>
|
||||
<section>
|
||||
<title>Migrating from 1.0 RC-1 to RC-2</title>
|
||||
<itemizedlist>
|
||||
<listitem>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.</listitem>
|
||||
</itemizedlist>
|
||||
</sect1>
|
||||
<sect1>
|
||||
</section>
|
||||
<section>
|
||||
<title>Migrating from 1.0 Beta 4 to RC-1</title>
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
|
|
@ -27,8 +107,8 @@
|
|||
The signature is the same as refresh token minus the grant type form parameter. See documentation for details.
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
</sect1>
|
||||
<sect1>
|
||||
</section>
|
||||
<section>
|
||||
<title>Migrating from 1.0 Beta 1 to Beta 4</title>
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
|
|
@ -56,8 +136,8 @@
|
|||
user.
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
</sect1>
|
||||
<sect1>
|
||||
</section>
|
||||
<section>
|
||||
<title>Migrating from 1.0 Alpha 4 to Beta 1</title>
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
|
|
@ -84,8 +164,8 @@
|
|||
for me details.
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
</sect1>
|
||||
<sect1>
|
||||
</section>
|
||||
<section>
|
||||
<title>Migrating from 1.0 Alpha 2 to Alpha 3</title>
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
|
|
@ -104,8 +184,8 @@
|
|||
Subject in AccessToken has been changed to the User ID.
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
</sect1>
|
||||
<sect1>
|
||||
</section>
|
||||
<section>
|
||||
<title>Migrating from 1.0 Alpha 1 to Alpha 2</title>
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
|
|
@ -130,5 +210,6 @@
|
|||
credentials tab in the administration console.
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
</sect1>
|
||||
</section>
|
||||
</section>
|
||||
</chapter>
|
||||
Loading…
Reference in a new issue