488 lines
No EOL
29 KiB
XML
Executable file
488 lines
No EOL
29 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 to 1.7.0.CR1</title>
|
|
<simplesect>
|
|
<title>Option 'Update Profile On First Login' moved from Identity provider to Review Profile authenticator</title>
|
|
<para>
|
|
form-error-page in web.xml will no longer work for client adapter authentication errors. You must define an error-page for
|
|
the the various HTTP error codes. See documentation for more details if you want to catch and handle adapter error conditions.
|
|
</para>
|
|
<para>
|
|
In this version, we added <literal>First Broker Login</literal>, 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 <literal>First Login Flow</literal> to identity providers where
|
|
you can specify the flow and then you can configure this flow under <literal>Authentication</literal> tab in admin console.
|
|
</para>
|
|
<para>
|
|
We also removed the option <literal>Update Profile On First Login</literal> from the Identity provider settings and moved it
|
|
to the configuration of <literal>Review Profile</literal> authenticator. So once you specify which flow should be used for your
|
|
Identity provider (by default it's <literal>First Broker Login</literal> flow), you go to <literal>Authentication</literal> tab, select the flow
|
|
and then you configure the option under <literal>Review Profile</literal> authenticator.
|
|
</para>
|
|
</simplesect>
|
|
</section>
|
|
<section>
|
|
<title>Migrating to 1.6.0.Final</title>
|
|
<simplesect>
|
|
<title>Option that refresh tokens are not reusable anymore</title>
|
|
<para>
|
|
Old versions of Keycloak allowed reusing refresh tokens multiple times. Keycloak still permits this,
|
|
but also have an option <literal>Revoke refresh token</literal> 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.
|
|
</para>
|
|
</simplesect>
|
|
<simplesect>
|
|
<title>Some packages renamed</title>
|
|
<para>
|
|
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 <literal>org.keycloak.adapters.spi.HttpFacade</literal> now.
|
|
</para>
|
|
</simplesect>
|
|
<simplesect>
|
|
<title>Persisting user sessions</title>
|
|
<para>
|
|
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 <literal>standalone/configuration/keycloak-server.json</literal> and add <literal>userSessionPersister</literal>
|
|
like this:
|
|
<programlisting>
|
|
"userSessionPersister": {
|
|
"provider": "jpa"
|
|
},
|
|
</programlisting>
|
|
If you want sessions to be persisted in Mongo instead of classic RDBMS, use provider <literal>mongo</literal> instead.
|
|
</para>
|
|
</simplesect>
|
|
</section>
|
|
<section>
|
|
<title>Migrating to 1.5.0.Final</title>
|
|
<simplesect>
|
|
<title>Realm and User cache providers</title>
|
|
<para>
|
|
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.
|
|
</para>
|
|
</simplesect>
|
|
<simplesect>
|
|
<title>Uses Session providers</title>
|
|
<para>
|
|
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.
|
|
</para>
|
|
<para>
|
|
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.
|
|
</para>
|
|
</simplesect>
|
|
<simplesect>
|
|
<title>Contact details removed from registration and account management</title>
|
|
<para>
|
|
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.
|
|
</para>
|
|
</simplesect>
|
|
</section>
|
|
<section>
|
|
<title>Migrating to 1.3.0.Final</title>
|
|
<simplesect>
|
|
<title>Direct Grant API always enabled</title>
|
|
<para>
|
|
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.
|
|
</para>
|
|
</simplesect>
|
|
<simplesect>
|
|
<title>Database changed</title>
|
|
<para>
|
|
There are again few database changes. Remember to backup your database prior to upgrading.
|
|
</para>
|
|
</simplesect>
|
|
<simplesect>
|
|
<title>UserFederationProvider changed</title>
|
|
<para>
|
|
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.
|
|
</para>
|
|
</simplesect>
|
|
<simplesect>
|
|
<title>WildFly 9.0.0.Final</title>
|
|
<para>
|
|
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 als 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.
|
|
</para>
|
|
</simplesect>
|
|
<simplesect>
|
|
<title>WildFly, JBoss EAP and JBoss AS7 adapters</title>
|
|
<para>
|
|
There are now 3 separate adapter downloads for WildFly, JBoss EAP and JBoss AS7:
|
|
<itemizedlist>
|
|
<listitem><literal>eap6</literal> - for JBoss EAP 6.x</listitem>
|
|
<listitem><literal>wf9</literal> - for WildFly 9.x</listitem>
|
|
<listitem><literal>wf8</literal> - for WildFly 8.x</listitem>
|
|
<listitem><literal>as7</literal> - for JBoss AS 7.x</listitem>
|
|
</itemizedlist>
|
|
Make sure you grab the correct one.
|
|
</para>
|
|
<para>
|
|
You also need to update standalone.xml as the extension module and subsystem definition has changed.
|
|
See <link linkend="jboss-adapter-installation">Adapter Installation</link> for details.
|
|
</para>
|
|
</simplesect>
|
|
</section>
|
|
<section>
|
|
<title>Migrating from 1.2.0.Beta1 to 1.2.0.RC1</title>
|
|
<simplesect>
|
|
<title>Distribution changes</title>
|
|
<para>
|
|
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.
|
|
</para>
|
|
</simplesect>
|
|
<simplesect>
|
|
<title>Database changed</title>
|
|
<para>
|
|
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.
|
|
</para>
|
|
</simplesect>
|
|
<simplesect>
|
|
<title>Application and OAuth client merge</title>
|
|
<para>
|
|
Application and OAuth clients are now merged into <literal>Clients</literal>. 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 <literal>Consent required</literal>
|
|
switch off and OAuth Clients will be converted into Clients with this switch on.
|
|
</para>
|
|
</simplesect>
|
|
</section>
|
|
<section>
|
|
<title>Migrating from 1.1.0.Final to 1.2.0.Beta1</title>
|
|
<simplesect>
|
|
<title>Database changed</title>
|
|
<para>
|
|
This release contains a number of changes to the database. Remember to backup your database prior to
|
|
upgrading.
|
|
</para>
|
|
</simplesect>
|
|
<simplesect>
|
|
<title><literal>iss</literal> in access and id tokens</title>
|
|
<para>
|
|
The value of <literal>iss</literal> claim in access and id tokens have changed from <literal>realm name</literal>
|
|
to <literal>realm url</literal>. 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 <literal>auth-server-url</literal>
|
|
you have to add it now. If you're using another library (or RSATokenVerifier) you need to make the corresponding
|
|
changes when verifying <literal>iss</literal>.
|
|
</para>
|
|
</simplesect>
|
|
<simplesect>
|
|
<title>OpenID Connect endpoints</title>
|
|
<para>
|
|
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 <literal>response_type</literal>
|
|
and <literal>grant_type</literal> parameters are used to select the required flow. The old endpoints (<literal>/realms/{realm}/protocols/openid-connect/login</literal>,
|
|
<literal>/realms/{realm}/protocols/openid-connect/grants/access</literal>, <literal>/realms/{realm}/protocols/openid-connect/refresh</literal>,
|
|
<literal>/realms/{realm}/protocols/openid-connect/access/codes)</literal> are now deprecated and will be removed
|
|
in a future version.
|
|
</para>
|
|
</simplesect>
|
|
<simplesect>
|
|
<title>Theme changes</title>
|
|
<para>
|
|
The layout of themes have changed. The directory hierarchy used to be <literal>type/name</literal>
|
|
this is now changed to <literal>name/type</literal>. For example a login theme named <literal>sunrise</literal>
|
|
used to be deployed to <literal>standalone/configuration/themes/login/sunrise</literal>, which is now
|
|
moved to <literal>standalone/configuration/themes/sunrise/login</literal>. This change was done to
|
|
make it easier to have group the different types for the same theme into one folder.
|
|
</para>
|
|
<para>
|
|
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 (<literal>META-INF/keycloak-themes.json</literal>)
|
|
to describe the themes included in a JAR. See the <link linkend='themes'>themes</link> section in the docs for more information.
|
|
</para>
|
|
</simplesect>
|
|
<simplesect>
|
|
<title>Claims changes</title>
|
|
<para>
|
|
Previously there was <literal>Claims</literal> 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 <link linkend='mappers'>Protocol mappers</link>, which are more flexible.
|
|
</para>
|
|
<para>
|
|
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.
|
|
</para>
|
|
</simplesect>
|
|
<simplesect>
|
|
<title>Social migration to identity brokering</title>
|
|
<para>
|
|
We refactored social providers SPI and replaced it with <link linkend="identity-broker">identity brokering SPI</link>,
|
|
which is more flexible. The <literal>Social</literal> tab in admin console is renamed to <literal>Identity Provider</literal> tab.
|
|
</para>
|
|
<para>
|
|
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.
|
|
</para>
|
|
<para>
|
|
Only required action from you would be to change allowed <literal>Redirect URI</literal> 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).
|
|
</para>
|
|
</simplesect>
|
|
</section>
|
|
<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> |