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`:
[source]
----
"connectionsJpa": {
"default": {
...
"databaseSchema": "update"
}
}
----
For MongoDB do the same, but for `connectionsMongo`:
[source]
----
"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.
We've moved the themes and providers directories from `standalone/configuration/themes` and `standalone/configuration/providers` to `themes` and `providers` respectively.
If you have added custom themes and providers you need to move them to the new location.
You also need to update `keycloak-server.json` as it's changed due to this.
Previously, if you had installed our saml or oidc keycloak subsystem adapters into Wildfly or JBoss EAP, we would automatically include Keycloak client jars into EVERY application irregardless if you were using Keycloak or not.
These libraries are now only added to your deployment if you have keycloak authentication turned on for that adapter (via the subsystem, or auth-method in web.xml
In the OpenID Connect authentication response we used to return the session state as `session-state` this is not correct according to the specification and has been renamed to `session_state`.
To plug a security attack vector, for platforms that support it (Tomcat 8, Undertow/Wildfly, Jetty 9), the keycloak oidc and saml adapters will change the session id after login.
You can turn off this behavior check adapter config switches.
In order to add more compliance with OAuth2 specification, we added a new endpoint for token introspection.
The new endpoint can reached at `/realms/{realm}/protocols/openid-connect/token/introspect` and it is solely based on `RFC-7662.`
The `/realms/{realm}/protocols/openid-connect/validate` endpoint is now deprecated and we strongly recommend you to move to the new introspection endpoint as soon as possible.
The reason for this change is that RFC-7662 provides a more standard and secure introspection endpoint.
The new token introspection URL can now be obtained from OpenID Connect Provider's configuration at `/realms/{realm}/.well-known/openid-configuration`.
There you will find a claim with name `token_introspection_endpoint` within the response.
Only `confidential clients` are allowed to invoke the new endpoint, where these clients will be usually acting as a resource server and looking for token metadata in order to perform local authorization checks.
In order to add more compliance with OpenID Connect specification, we added flags into admin console to Client Settings page, where you can enable/disable various kinds of OpenID Connect/OAuth2 flows (Standard flow, Implicit flow, Direct Access Grants, Service Accounts). As part of this, we have `Direct Access Grants` (corresponds to OAuth2 `Resource Owner Password Credentials Grant`) disabled by default for new clients.
Clients migrated from previous version have `Direct Access Grants` enabled just if they had flag `Direct Grants Only` on.
The `Direct Grants Only` flag was removed as if you enable Direct Access Grants and disable both Standard+Implicit flow, you will achieve same effect.
We also added builtin client `admin-cli` to each realm.
This client has `Direct Access Grants` enabled.
So if you're using Admin REST API or Keycloak admin-client, you should update your configuration to use `admin-cli` instead of `security-admin-console` as the latter one doesn't have direct access grants enabled anymore by default.
In this version, we added `First Broker Login`, 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 `First Login Flow` to identity providers where you can specify the flow and then you can configure this flow under `Authentication` tab in admin console.
We also removed the option `Update Profile On First Login` from the Identity provider settings and moved it to the configuration of `Review Profile` authenticator.
So once you specify which flow should be used for your Identity provider (by default it's `First Broker Login` flow), you go to `Authentication` tab, select the flow and then you configure the option under `Review Profile` authenticator.
There is no change in the interface itself or method signatures.
However there is some change in behaviour.
We added `First Broker Login` flow in this release and the method `IdentityProviderMapper.importNewUser` is now called after `First Broker Login` flow is finished.
So if you want to have any attribute available in `Review Profile` page, you would need to use the method `preprocessFederatedIdentity` instead of `importNewUser` . You can set any attribute by invoke `BrokeredIdentityContext.setUserAttribute` and that will be available on `Review profile` page.
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 `org.keycloak.adapters.spi.HttpFacade` now.
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.
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.
Application and OAuth clients are now merged into `Clients`.
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 `Consent required` switch off and OAuth Clients will be converted into Clients with this switch on.
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 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,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 <<_mappers,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.
* 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.
