240 lines
No EOL
13 KiB
XML
Executable file
240 lines
No EOL
13 KiB
XML
Executable file
<chapter id="Migration_from_older_versions">
|
|
<title>Migration from older versions</title>
|
|
|
|
<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.1.0.Beta2 to 1.1.0.Final</title>
|
|
<itemizedlist>
|
|
<listitem>
|
|
Providers are no longer loaded from <literal>WEB-INF/lib</literal>, they are now loaded
|
|
from <literal>standalone/configuration/providers</literal>. See the
|
|
<link linkend='providers'>providers</link> section for more details.
|
|
</listitem>
|
|
</itemizedlist>
|
|
</section>
|
|
<section>
|
|
<title>Migrating from 1.1.0.Beta1 to 1.1.0.Beta2</title>
|
|
<itemizedlist>
|
|
<listitem>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.</listitem>
|
|
<listitem>The tomcat adapter valve has moved to a different package. From <literal>org.keycloak.adapters.tomcat7.KeycloakAuthenticatorValve</literal> to <literal>org.keycloak.adapters.tomcat.KeycloakAuthenticatorValve</literal>
|
|
From the 'tomcat7' package to just 'tomcat'.
|
|
</listitem>
|
|
<listitem>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.</listitem>
|
|
<listitem>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.</listitem>
|
|
<listitem>Server installation is no longer supported on AS7. You can still use AS7 as an application client.</listitem>
|
|
</itemizedlist>
|
|
</section>
|
|
<section>
|
|
<title>Migrating from 1.0.x.Final to 1.1.0.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>
|
|
</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>
|
|
</section>
|
|
<section>
|
|
<title>Migrating from 1.0 Beta 4 to RC-1</title>
|
|
<itemizedlist>
|
|
<listitem>
|
|
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.
|
|
</listitem>
|
|
</itemizedlist>
|
|
</section>
|
|
<section>
|
|
<title>Migrating from 1.0 Beta 1 to Beta 4</title>
|
|
<itemizedlist>
|
|
<listitem>
|
|
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.
|
|
</listitem>
|
|
<listitem>
|
|
Authentication SPI has been removed and rewritten. The new SPI is UserFederationProvider and is
|
|
more flexible.
|
|
</listitem>
|
|
<listitem>
|
|
<literal>ssl-not-required</literal> property in adapter config has been removed. Replaced with
|
|
<literal>ssl-required</literal>, valid values are <literal>all</literal> (require SSL for all requests), <literal>external</literal>
|
|
(require SSL only for external request) and <literal>none</literal> (SSL not required).
|
|
</listitem>
|
|
<listitem>
|
|
DB Schema has changed again.
|
|
</listitem>
|
|
<listitem>
|
|
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.
|
|
</listitem>
|
|
<listitem>
|
|
Format of JSON file for importing realm data was changed. Now role mappings is available under the JSON record of particular
|
|
user.
|
|
</listitem>
|
|
</itemizedlist>
|
|
</section>
|
|
<section>
|
|
<title>Migrating from 1.0 Alpha 4 to Beta 1</title>
|
|
<itemizedlist>
|
|
<listitem>
|
|
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.
|
|
</listitem>
|
|
<listitem>
|
|
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.
|
|
</listitem>
|
|
<listitem>
|
|
Resource Owner Password Credentials flow is now disabled by default. It can be enabled by setting the toggle
|
|
for <literal>Direct Grant API</literal> <literal>ON</literal> under realm config in the admin console.
|
|
</listitem>
|
|
<listitem>
|
|
Configuration is now done through <literal>standalone/configuration/keycloak-server.json</literal>. This
|
|
should mainly affect those that use MongoDB.
|
|
</listitem>
|
|
<listitem>
|
|
JavaScript adapter has been refactored. See the <link linkend='javascript-adapter'>JavaScript adapter</link> section for more details.
|
|
</listitem>
|
|
<listitem>
|
|
The "Central Login Lifespan" setting no longer exists. Please see the <link linkend='session-timeouts'>Session Timeout</link> section
|
|
for me details.
|
|
</listitem>
|
|
</itemizedlist>
|
|
</section>
|
|
<section>
|
|
<title>Migrating from 1.0 Alpha 2 to Alpha 3</title>
|
|
<itemizedlist>
|
|
<listitem>
|
|
SkeletonKeyToken, SkeletonKeyScope, SkeletonKeyPrincipal, and SkeletonKeySession have been renamed to:
|
|
AccessToken, AccessScope, KeycloakPrincipal, and KeycloakAuthenticatedSession respectively.
|
|
</listitem>
|
|
<listitem>
|
|
ServleOAuthClient.getBearerToken() method signature has changed. It now returns an AccessTokenResponse
|
|
so that you can obtain a refresh token too.
|
|
</listitem>
|
|
<listitem>
|
|
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.
|
|
</listitem>
|
|
<listitem>
|
|
Subject in AccessToken has been changed to the User ID.
|
|
</listitem>
|
|
</itemizedlist>
|
|
</section>
|
|
<section>
|
|
<title>Migrating from 1.0 Alpha 1 to Alpha 2</title>
|
|
<itemizedlist>
|
|
<listitem>
|
|
DB Schema has changed. We don't have any data migration utilities yet as of Alpha 2.
|
|
</listitem>
|
|
<listitem>
|
|
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.
|
|
</listitem>
|
|
<listitem>
|
|
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.
|
|
|
|
</listitem>
|
|
<listitem>
|
|
There is no longer required Application or OAuth Client credentials. These client types are now
|
|
hard coded to use the "secret" credential type.
|
|
</listitem>
|
|
<listitem>
|
|
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.
|
|
</listitem>
|
|
</itemizedlist>
|
|
</section>
|
|
</section>
|
|
</chapter> |