JBoss.orgCommunity Documentation

Chapter 30. Migration from older versions

30.1. Migrate database
30.2. Migrate keycloak-server.json
30.3. Migrate providers
30.4. Migrate themes
30.5. Migrate application
30.6. Version specific migration
30.6.1. Migrating from 1.1.0.Final to 1.2.0.Beta1
30.6.2. Migrating from 1.1.0.Beta2 to 1.1.0.Final
30.6.3. Migrating from 1.1.0.Beta1 to 1.1.0.Beta2
30.6.4. Migrating from 1.0.x.Final to 1.1.0.Beta1
30.6.5. Migrating from 1.0 RC-1 to RC-2
30.6.6. Migrating from 1.0 Beta 4 to RC-1
30.6.7. Migrating from 1.0 Beta 1 to Beta 4
30.6.8. Migrating from 1.0 Alpha 4 to Beta 1
30.6.9. Migrating from 1.0 Alpha 2 to Alpha 3
30.6.10. Migrating from 1.0 Alpha 1 to Alpha 2

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.

Keycloak provides automatic migration of the database. It's highly recommended that you backup your database prior to upgrading Keycloak.

To enable automatic upgrading of the database if you're using a relational database make sure databaseSchema is set to update for connectionsJpa:

"connectionsJpa": {
    "default": {
        ...
        "databaseSchema": "update"
    }
}

For MongoDB do the same, but for connectionsMongo:

"connectionsMongo": {
    "default": {
        ...
        "databaseSchema": "update"
    }
}

When you start the server with this setting your database will automatically be migrated if the database schema has changed in the new version.

You should copy standalone/configuration/keycloak-server.json 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.

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.

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.

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.

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

We refactored social providers SPI and replaced it with 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).