<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>