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

Providers are no longer loaded from WEB-INF/lib, they are now loaded from standalone/configuration/providers. See the providers section for more details.

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. The tomcat adapter valve has moved to a different package. From org.keycloak.adapters.tomcat7.KeycloakAuthenticatorValve to org.keycloak.adapters.tomcat.KeycloakAuthenticatorValve From the 'tomcat7' package to just 'tomcat'. 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. 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. Server installation is no longer supported on AS7. You can still use AS7 as an application client.

RealmModel JPA and Mongo storage schema has changed UserSessionModel JPA and Mongo storage schema has changed as these interfaces have been refactored 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.

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.

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.

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. Authentication SPI has been removed and rewritten. The new SPI is UserFederationProvider and is more flexible. 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). DB Schema has changed again. 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. Format of JSON file for importing realm data was changed. Now role mappings is available under the JSON record of particular user.

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. 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. Resource Owner Password Credentials flow is now disabled by default. It can be enabled by setting the toggle for Direct Grant API ON under realm config in the admin console. Configuration is now done through standalone/configuration/keycloak-server.json. This should mainly affect those that use MongoDB. JavaScript adapter has been refactored. See the JavaScript adapter section for more details. The "Central Login Lifespan" setting no longer exists. Please see the Session Timeout section for me details.

SkeletonKeyToken, SkeletonKeyScope, SkeletonKeyPrincipal, and SkeletonKeySession have been renamed to: AccessToken, AccessScope, KeycloakPrincipal, and KeycloakAuthenticatedSession respectively. ServleOAuthClient.getBearerToken() method signature has changed. It now returns an AccessTokenResponse so that you can obtain a refresh token too. 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. Subject in AccessToken has been changed to the User ID.

DB Schema has changed. We don't have any data migration utilities yet as of Alpha 2. 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. 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. There is no longer required Application or OAuth Client credentials. These client types are now hard coded to use the "secret" credential type. 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.