JBoss.orgCommunity Documentation
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.
This release contains a number of changes to the database. Remember to backup your database prior to upgrading.
The value of iss
claim in access and id tokens have changed from realm name
to realm url
. 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 auth-server-url
you have to add it now. If you're using another library (or RSATokenVerifier) you need to make the corresponding
changes when verifying iss
.
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 response_type
and grant_type
parameters are used to select the required flow. The old endpoints (/realms/{realm}/protocols/openid-connect/login
,
/realms/{realm}/protocols/openid-connect/grants/access
, /realms/{realm}/protocols/openid-connect/refresh
,
/realms/{realm}/protocols/openid-connect/access/codes)
are now deprecated and will be removed
in a future version.
The layout of themes have changed. The directory hierarchy used to be type/name
this is now changed to name/type
. For example a login theme named sunrise
used to be deployed to standalone/configuration/themes/login/sunrise
, which is now
moved to standalone/configuration/themes/sunrise/login
. This change was done to
make it easier to have group the different types for the same theme into one folder.
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 (META-INF/keycloak-themes.json
)
to describe the themes included in a JAR. See the themes section in the docs for more information.
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).
WEB-INF/lib
, they are now loaded
from standalone/configuration/providers
. See the
providers section for more details.
org.keycloak.adapters.tomcat7.KeycloakAuthenticatorValve
to org.keycloak.adapters.tomcat.KeycloakAuthenticatorValve
From the 'tomcat7' package to just 'tomcat'.
ssl-not-required
property in adapter config has been removed. Replaced with
ssl-required
, valid values are all
(require SSL for all requests), external
(require SSL only for external request) and none
(SSL not required).
Direct Grant API
ON
under realm config in the admin console.
standalone/configuration/keycloak-server.json
. This
should mainly affect those that use MongoDB.