== Migration Changes
=== Migrating to 24.0.0
include::changes-24_0_0.adoc[leveloffset=3]
=== Migrating to 23.0.2
include::changes-23_0_2.adoc[leveloffset=3]
=== Migrating to 23.0.0
include::changes-23_0_0.adoc[leveloffset=3]
=== Migrating to 22.0.4
include::changes-22_0_4.adoc[leveloffset=3]
=== Migrating to 22.0.2
include::changes-22_0_2.adoc[leveloffset=3]
=== Migrating to 22.0.0
include::changes-22_0_0.adoc[leveloffset=3]
=== Migrating to 21.1.0
include::changes-21_1_0.adoc[leveloffset=3]
=== Migrating to 21.0.2
include::changes-21_0_2.adoc[leveloffset=3]
=== Migrating to 21.0.0
include::changes-21_0_0.adoc[leveloffset=3]
=== Migrating to 20.0.0
include::changes-20_0_0.adoc[leveloffset=3]
=== Migrating to 19.0.2
include::changes-19_0_2.adoc[leveloffset=3]
=== Migrating to 19.0.0
include::changes-19_0_0.adoc[leveloffset=3]
=== Migrating to 18.0.0
include::changes-18_0_0.adoc[leveloffset=3]
=== Migrating to 17.0.0
include::changes-17_0_0.adoc[leveloffset=3]
=== Migrating to 16.0.0
include::changes-16_0_0.adoc[leveloffset=3]
=== Migrating to 14.0.0
==== Client policies migration
The Client policies feature was a preview feature since Keycloak 12 and did not have proper support. If you tried this feature and configured some client policies or client profiles
in Keycloak 12 or Keycloak 13, then you will need to configure your client policies and client profiles again in the new version. The format of the configuration changed significantly
as it was only a preview and hence we do not provide automatic migration of client policies and client profiles created in Keycloak 12 or Keycloak 13.
=== Migrating to 13.0.0
==== Manual migration step needed
Manual change is required when the standalone.xml contains references to any of the SmallRye modules.
SmallRye modules were removed from the underlying {appserver_name} distribution, and the server does not start
if the configuration references them. Thus if the configuration in the `standalone.xml` refers to these modules,
the server configuration migration via `migrate-standalone.cli` fails before any changes are made to the configuration.
In such case, to perform server configuration migration, you have to manually remove all the lines that refer
to SmallRye modules. In the default configuration, you need to remove specifically the following lines:
[source,xml]
[source,xml]
==== Upgrade to Wildfly 23
The {project_name} server was upgraded to use Wildfly 23 as the underlying container. This does not directly involve any
specific {project_name} server functionality, however, note these changes related to migration:
Dependency updates::
The dependencies were updated to the versions used by the Wildfly 23 server. For example, Infinispan is now `11.0.9.Final`.
Configuration changes::
A few configuration changes exist in the `standalone(-ha).xml` and `domain.xml` files. You should follow the <<_install_new_version>>
section to handle the migration of configuration files automatically. However, here are the most important changes, which you may need
if you made your own configuration changes:
* The `module` attribute of Infinispan cache containers is now *deprecated* (unused) and is *replaced with* the `modules` attribute,
representing the set of modules associated with this cache container's configuration. Moreover, there were also additional
changes to attributes of various elements, originating from the use of Wildfly 23 as the underlying container. For example,
the `managed-executor-service` and `managed-scheduled-executor-service` elements now recognize the new `hung-task-termination-period`
attribute. See link:https://docs.wildfly.org/23/wildscribe/index.html[the Wildfly 23 full model reference] for details.
==== Upgrade to Wildfly 22
The {project_name} server was upgraded to use Wildfly 22 as the underlying container. This does not directly involve any
specific {project_name} server functionality, however, note these changes related to migration:
Dependency updates::
The dependencies were updated to the versions used by the Wildfly 22 server. For example, Infinispan is now `11.0.8.Final`.
Configuration changes::
A few configuration changes exist in the `standalone(-ha).xml` and `domain.xml` files. You should follow the <<_install_new_version>>
section to handle the migration of configuration files automatically. However, here are the most important changes, which you may need
if you made your own configuration changes:
* The link:https://docs.wildfly.org/22/Admin_Guide.html#MicroProfile_Config_SmallRye[Eclipse MicroProfile Config], link:https://docs.wildfly.org/22/Admin_Guide.html#MicroProfile_Health_SmallRye[Eclipse MicroProfile Health], and link:https://docs.wildfly.org/22/Admin_Guide.html#MicroProfile_Metrics_SmallRye[Eclipse MicroProfile Metrics] subsystems are replaced with link:https://docs.wildfly.org/22/Admin_Guide.html#Health[WildFly subsystem for health] and link:https://docs.wildfly.org/22/Admin_Guide.html#MicroProfile_Metrics_SmallRye[WildFly subsystem for base metrics].
* The default Wildfly configuration now uses the ability to make use of an automatically generated self-signed certificate with Elytron. Refer to link:https://docs.wildfly.org/22/WildFly_Elytron_Security.html#update-wildfly-to-use-the-default-elytron-components-for-application-authentication[a dedicated `applicationSSC` server SSL context section] for details.
=== Migrating to 12.0.2
==== Read-only attributes
There was added support for the read-only user attributes. This includes the user attributes, which are not supposed to be edited by the user
or by the administrator when updating user with REST API or with the {project_name} user interfaces. It can be important especially if you
use:
* Custom user storage providers
* Custom authenticators
* Custom JavaScript authorization policies, which establish authorization based on some user attribute
* X.509 authenticator with custom attribute for mapping the X.509 certificate to the user identity
* Any other custom functionality, where some of the user attributes are used as the metadata for storing authentication/authorization/identity context rather
than simple user profile information.
See the details in the link:{adminguide_link}#read_only_user_attributes[Threat model mitigation chapter].
==== Valid Request URIs
If you use the OpenID Connect parameter `request_uri`, a requirement exists that your client needs to have `Valid Request URIs` configured.
This can be configured through the admin console on the client details page or through the admin REST API or client registration API. Valid Request URIs need
to contain the list of Request URI values, which are permitted for the particular client. This is to avoid SSRF attacks. There is possibility to use wildcards
or relative paths similarly such as the `Valid Redirect URIs` option, however for security purposes, we typically recommend to use as specific value
as possible.
=== Migrating to 13.0.0
==== Upgrade to Wildfly 22
The {project_name} server was upgraded to use Wildfly 22 as the underlying container. This does not directly involve any
specific {project_name} server functionality, but a few changes related to the migration, which are worth mentioning.
Dependency updates::
The dependencies were updated to the versions used by Wildfly 22 server. For example, Infinispan is now `11.0.8.Final`.
Configuration changes::
A few configuration changes exist in the `standalone(-ha).xml` and `domain.xml` files. You should follow the <<_install_new_version>>
section to handle the migration of configuration files automatically. If more detail is needed, because, for example, you did some
configuration changes on your own, the list of the most important changes follows:
* The link:https://docs.wildfly.org/22/Admin_Guide.html#MicroProfile_Config_SmallRye[Eclipse MicroProfile Config], link:https://docs.wildfly.org/22/Admin_Guide.html#MicroProfile_Health_SmallRye[Eclipse MicroProfile Health], and link:https://docs.wildfly.org/22/Admin_Guide.html#MicroProfile_Metrics_SmallRye[Eclipse MicroProfile Metrics] subsystems were replaced by link:https://docs.wildfly.org/22/Admin_Guide.html#Health[WildFly subsystem for health] and link:https://docs.wildfly.org/22/Admin_Guide.html#MicroProfile_Metrics_SmallRye[WildFly subsystem for base metrics].
* The default Wildfly configuration now utilizes the ability to make use of an automatically generated self-signed certificate with Elytron. Refer to link:https://docs.wildfly.org/22/WildFly_Elytron_Security.html#update-wildfly-to-use-the-default-elytron-components-for-application-authentication[a dedicated `applicationSSC` server SSL context section] for details.
=== Migrating to 12.0.0
==== Upgrade to Wildfly 21
The {project_name} server was upgraded to use Wildfly 21 as the underlying container. This does not directly involve any
specific {project_name} server functionality, however, note these changes related to migration:
Dependency updates::
The dependencies were updated to the versions used by the Wildfly 21 server. For example, Infinispan is now 11.0.4.Final.
Configuration changes::
A few configuration changes exist in the `standalone(-ha).xml` and `domain.xml` files. You should follow the <<_install_new_version>>
section to handle the migration of configuration files automatically. However, here are the most important changes, which you may need
if you made your own configuration changes:
* The `object-memory` element of Infinispan caches is now *deprecated* (unused) and is *replaced with* the `heap-memory` element.
==== Skip creation of user session for the Docker protocol authentication
No user session is created after successful authentication with the Docker protocol. For details, please refer to the link:{adminguide_link}#_docker[{adminguide_name}].
==== Upgrade to PatternFly 4
The {project_name} login theme components have been upgraded to PatternFly 4.
The old PatternFly 3 runs simultaneously with the new one, so it's possible to keep PF3 components.
However, some changes to the design of the login theme were performed. Please upgrade your custom login theme due them.
An example with the necessary changes can be found in the `keycloak/examples/themes/theme/sunrise` directory.
No additional setup is required.
==== Client Credentials Grant without refresh token by default
From this {project_name} version, the OAuth2 Client Credentials Grant endpoint does not issue refresh tokens by default. This behavior is aligned with the OAuth2 specification.
As a side effect of this change, no user session is created on the {project_name} server side after successful Client Credentials authentication, which results
in improved performance and memory consumption. Clients that use Client Credentials Grant are encouraged to stop using
refresh tokens and instead always authenticate at every request with `grant_type=client_credentials` instead of using `refresh_token` as grant type.
In relation to this, {project_name} has support for revocation of access tokens in the OAuth2 Revocation Endpoint, hence clients are allowed
to revoke individual access tokens if needed.
For backwards compatibility, a possibility to stick to the behavior of old versions exists. When this is used, the refresh token will be still issued after
a successful authentication with the Client Credentials Grant and also the user session will be created. This can be enabled for the particular client in
the {project_name} admin console, in client details in the section with `OpenID Connect Compatibility Modes` with the switch `Use Refresh Tokens For Client Credentials Grant`.
=== Migrating to 11.0.0
==== Upgrade to Wildfly 20
The {project_name} server was upgraded to use Wildfly 20 as the underlying container. This does not directly involve any
specific {project_name} server functionality, however, note these changes related to migration:
Dependency updates::
The dependencies were updated to the versions used by the Wildfly 20 server. For example, Infinispan is now 10.1.8.Final.
Configuration changes::
A few configuration changes exist in the `standalone(-ha).xml` and `domain.xml` files. You should follow the <<_install_new_version>>
section to handle the migration of configuration files automatically.
Cross-Datacenter Replication changes::
* You will need to upgrade {jdgserver_name} server to version {jdgserver_version}. The older version may still work, but it is
not guaranteed as they are not tested anymore.
* It is recommended to use the `protocolVersion` property added to the `remote-store` element when configuring Infinispan caches.
When connecting to the {jdgserver_name} server 9.4.18, the recommended version of the hotrod protocol version is 2.9 as the Infinispan
library version differs among {project_name} server and {jdgserver_name} server. For more details, see the
Cross-Datacenter documentation.
* It is recommended to use `remoteStoreSecurityEnabled` property under `connectionsInfinispan` subsystem. For more details,
see the Cross-Datacenter documentation.
==== LDAP no-import bugfix
In the previous {project_name} version, when the LDAP provider was configured with `Import Users` OFF, it was possible to update the
user even if some of non-LDAP mapped attributes were changed. This situation resulted in confusing behavior, when the attribute appeared to be updated,
but it was not. In the current version, the update is not allowed to be performed at all if any non-LDAP mapped attributes are changed.
This should not affect most of the deployments, but some can be affected under some rare circumstances. For example if you previously
tried to update a user with the admin REST API and the user had some incorrect attribute changes, the update was possible. With the
current version, the update is not possible and you will be immediately informed about the reason.
==== UserModel changes
The fields `username`, `email`, `firstName` and `lastName` in the `UserModel` are migrated to custom attributes as a preparation for adding more sophisticated user profiles to {project_name} in an upcoming version.
If a database contains users with custom attributes of that exact name, the custom attributes will need to be migrated before upgrading. This migration does not occur automatically. Otherwise, they will not be read from the database anymore and possibly deleted.
This situation implies that the `username` can now also be accessed and set via `UserModel.getFirstAttribute(UserModel.USERNAME)`. Similar implications exist for other fields.
Implementors of SPIs subclassing the `UserModel` directly or indirectly should ensure that the behavior between `setUsername` and `setSingleAttribute(UserModel.USERNAME, ...)` (and similar for the other fields) is consistent.
Users of the policy evaluation feature have to adapt their policies if they use the number of attributes in their evaluations since every user will now have four new attributes by default.
The public API of `UserModel` did not change. No changes to frontend resources or SPIs accessing user data are necessary.
Also, the database did not change yet.
==== Instagram IdP migrated to new the API
Instagram IdP now uses new API as the old legacy API was *deprecated*. This requires getting new API credentials. For details,
please refer to the link:{adminguide_link}#instagram[{adminguide_name}].
Special attention is required for existing users that use Instagram IdP, specially the ones for whom it is the only authentication
option. Such users have to log in to Keycloak using Instagram IdP before September 30th, 2020. After that day they'll have
to use a different authentication method (like password) to log in to manually update their Instagram social link, or create
a new account in Keycloak. This is because Instagram user IDs are not compatible between the old and new API, however the
new API temporarily returns both new and old user IDs to allow migration. Keycloak automatically migrates the ID once user
logs in.
==== Non-standard token introspection endpoint removed
In previous versions, Keycloak advertised two introspection endpoints: `token_introspection_endpoint` and `introspection_endpoint`.
The latter is the one defined by https://datatracker.ietf.org/doc/html/rfc8414#section-2[RFC-8414]. The former, previously deprecated,
has now been removed.
=== Migrating to 9.0.1
==== Legacy promise in JavaScript adapter
It is no longer necessary to set promiseType in the JavaScript adapter, and both are available at the same time. It is
recommended to update applications to use native promise API (`then` and `catch`) as soon as possible, as the legacy API
(`success` and `error`) will be removed at some point.
==== Duplicated top level groups
Version 9.0.1 fixes a problem which could create duplicated top level groups in the realm. Nevertheless the existence
of previous duplicated groups makes the upgrade process fail. The {project_name} server can be affected by this issue
if it is using an H2, MariaDB, MySQL or PostgreSQL database. Before launching the upgrade, check if the server contains
duplicated top level groups. For example the following SQL query can be executed at database level to list them:
----
SELECT REALM_ID, NAME, COUNT(*) FROM KEYCLOAK_GROUP WHERE PARENT_GROUP is NULL GROUP BY REALM_ID, NAME HAVING COUNT(*) > 1;
----
Only one top level group can exist in each realm with the same name. Duplicates should be reviewed and deleted before the
upgrade. The error in the upgrade contains the message `Change Set META-INF/jpa-changelog-9.0.1.xml::9.0.1-
KEYCLOAK-12579-add-not-null-constraint::keycloak failed.`
=== Migrating to 9.0.0
==== Improved handling of user locale
A number of improvements have been made to how the locale for the login page is selected, as well as when the locale
is updated for a user.
See the link:{adminguide_link}#_user_locale_selection[{adminguide_name}] for more details.
==== Deprecated methods in token representation Java classes
In the year 2038 an `int` is no longer able to hold the value of seconds since 1970, as such we are working on updating these to
`long` values. Moreover, another issue related with processing of `int` values exists in token representation. An `int` will by
default result into `0` in the JSON representation, while it should not be included.
See JavaDocs for further details on exact methods that have been deprecated and replacement methods.
=== Migrating to 8.0.2
==== More authentication flows changes
REQUIRED and ALTERNATIVE executions not supported at same flow::
In previous version, it was possible to have REQUIRED and ALTERNATIVE executions in the same authentication flow at the same level.
There were some issues with this approach and we did the refactoring in the Authentication SPI, which means that this is not considered
valid anymore. If ALTERNATIVE and REQUIRED executions are configured at the same level, the ALTERNATIVE executions are considered disabled.
So when migrating to the newest version, your existing authentication flows will be automatically migrated preserved the same behavior as existed in the previous version.
If they contain ALTERNATIVE executions at the same level as some REQUIRED executions, then the ALTERNATIVE executions will be added to the separate REQUIRED subflow. This
should ensure same/similar behavior of the particular authentication flow as in the previous version. We always recommend
to double-check the configuration of your authentication flow and test it to double-check that everything works as expected.
This recommendation is true in particular if you have some more customized authentication flows with custom authenticator implementations.
=== Migrating to 8.0.0
==== New default Hostname provider
The old request and fixed hostname providers are replaced with a new default hostname provider. The request
and fixed hostname providers are now deprecated and it is recommended to switch to the default hostname provider as
soon as possible.
==== Upgrade to Wildfly 18
The {project_name} server was upgraded to use Wildfly 18 as the underlying container. This does not directly involve any
specific {project_name} server functionality, however, note these changes related to migration:
Dependency updates::
The dependencies were updated to the versions used by the Wildfly 18 server. For example, Infinispan is now 9.4.16.Final.
Configuration changes::
A few configuration changes exist in the `standalone(-ha).xml` and `domain.xml` files. You should follow the <<_install_new_version>>
section to handle the migration of configuration files automatically.
Cross-Datacenter Replication changes::
* You will need to upgrade {jdgserver_name} server to version {jdgserver_version}. The older version may still work, but it is
not guaranteed as we don't test it anymore.
==== Deploying scripts to the server
Until now, administrators were allowed to upload scripts to the server through the {project_name} Administration Console as well as
through the RESTful Admin API.
For now on, this capability is *disabled* by default and users should prefer to deploy scripts directly to the server. For more details,
please take a look at link:{developerguide_jsproviders_link}[{developerguide_jsproviders_name}].
==== Client credentials in the JavaScript adapter
In the previous releases, developers were allowed to provide client credentials to the JavaScript adapter. For now on, this capability was *removed*, because client-side apps are not safe to keep secrets.
==== Authentication flows changes
We did some refactoring and improvements related to the authentication flows, which requires some attention during migration.
OPTIONAL execution requirement removed::
Regarding migration, the most important change is removing the support for the OPTIONAL requirement from authentication executions and
replacing it with the CONDITIONAL requirement, which allows more flexibility. The existing OPTIONAL authenticators configured in the
previous version are replaced with the CONDITIONAL subflows. These subflows have the `Condition - User Configured` condition configured
as first execution, and the previously OPTIONAL authenticator (for example `OTP Form`) as second execution. From the user's point of view,
the behavior during authentication is the same as in the previous version.
Changes in the Java SPI::
Some changes exist in the Java Authentication SPI and Credential Provider SPI. The interface `Authenticator` is not changed,
but you may be affected if you're developing more advanced authenticators, which introduce some new credential types (subclasses of `CredentialModel`).
There are changes on the `CredentialProvider` interface and introduction of some new interfaces like `CredentialValidator`. Also you
may be affected if your authenticator supported the OPTIONAL execution requirement. It is recommended to double-check the latest authentication
examples in the server development guide for more details.
Freemarker template changes::
Some changes in the freemarker templates exist. You may be affected if you have your own theme with custom freemarker
templates for login forms or some account forms, especially for the forms related to OTP. It is recommended to double-check changes in
the Freemarker templates in the latest {project_name} and align your templates according to it.
==== User credentials changes
We added more flexibility around storing of user credentials. Among other things, every user can have multiple credentials of the same
type, for example multiple OTP credentials. As a result, some changes to the database schema were performed. However the credentials from
the previous version should be automatically updated to the new format and users should be still able to login with their passwords or OTP
credentials set in the previous version.
=== Migrating to 7.0.0
==== Upgrade to Wildfly 17
The {project_name} server was upgraded to use Wildfly 17 as the underlying container. This does not directly involve any
specific {project_name} server functionality, however, note these changes related to migration:
Dependency updates::
The dependencies were updated to the versions used by the Wildfly 17 server. For example, Infinispan is now 9.4.14.Final.
Configuration changes::
A few configuration changes exist in the `standalone(-ha).xml` and `domain.xml` files. You should follow the <<_install_new_version>>
section to handle the migration of configuration files automatically.
Cross-Datacenter Replication changes::
* You will need to upgrade {jdgserver_name} server to version {jdgserver_version}. The older version may still work, but it is
not guaranteed as we don't test it anymore.
=== Migrating to 6.0.0
==== Upgrade to Wildfly 16
The {project_name} server was upgraded to use Wildfly 16 as the underlying container. This does not directly involve any
specific {project_name} server functionality, however, note these changes related to migration:
Dependency updates::
The dependencies were updated to the versions used by the Wildfly 16 server. For example, Infinispan is now 9.4.8.Final.
Configuration changes::
A few configuration changes exist in the `standalone(-ha).xml` and `domain.xml` files. You should follow the <<_install_new_version>>
section to handle the migration of configuration files automatically.
Cross-Datacenter Replication changes::
* You will need to upgrade {jdgserver_name} server to version {jdgserver_version}. The older version may still work, but it is
not guaranteed as we don't test it anymore.
==== New optional client scope
We have added a new `microprofile-jwt` optional client scope to handle the claims defined in the https://wiki.eclipse.org/MicroProfile/JWT_Auth[MicroProfile/JWT Auth Specification].
This new client scope defines protocol mappers to set the username of the authenticated user to the `upn` claim and to
set the realm roles to the `groups` claim.
==== Ability to propagate prompt=none to default IDP
We have added a new switch in the OIDC identity provider configuration named `Accepts prompt=none forward from client` to identify IDPs that
are able to handle forwarded requests that include the `prompt=none` query parameter.
Until now, when receiving an auth request with `prompt=none` a realm would return a `login_required` error if the user is
not authenticated in the realm without checking if the user has been authenticated by an IDP. From now on, if a default
IDP can be determined for the auth request (either by the use of the `kc_idp_hint` query param or by setting up a default IDP
for the realm) and if the `Accepts prompt=none forward from client` switch has been enabled for the IDP, the auth request is forwarded to the IDP
to check if the user has been authenticated there.
It is important to note that this switch is only taken into account if a default IDP is specified, in which case we know
where to forward the auth request without having to prompt the user to select an IDP. If a default IDP cannot be determined
we cannot assume which one will be used to fulfill the auth request so the request forwarding is not performed.
=== Migrating to 5.0.0
==== Upgrade to Wildfly 15
The {project_name} server was upgraded to use Wildfly 15 as the underlying container. This does not directly involve any
specific {project_name} server functionality, however, note these changes related to migration:
Dependency updates::
The dependencies were updated to the versions used by the Wildfly 15 server. For example, Infinispan is now 9.4.3.Final.
Configuration changes::
A few configuration changes exist in the `standalone(-ha).xml` and `domain.xml` files. You should follow the <<_install_new_version>>
section to handle the migration of configuration files automatically.
Cross-Datacenter Replication changes::
* You will need to upgrade {jdgserver_name} server to version {jdgserver_version}. The older version may still work, but it is
not guaranteed as we don't test it anymore.
=== Migrating to 4.8.2
==== Google Identity Provider updated to use Google Sign-in authentication system
The Google Identity Provider implementation in {project_name} up to version 4.8.1 relies on the Google+ API endpoints
for authorization and obtaining the user profile. From March 2019 onwards, Google is removing support
for the Google+ API in favor of the new Google Sign-in authentication system. The {project_name} identity provider has been updated
to use the new endpoints so if this integration is in use make sure you upgrade to {project_name} version 4.8.2 or later.
If you run into an error saying that the application identifier was not found in the directory, you will have to register the client application again in the
https://console.cloud.google.com/apis/credentials[Google API Console] portal to obtain a new application id and secret.
It is possible that you will need to adjust custom mappers for non-standard claims that were provided by Google+ user
information endpoint and are provided under different name by Google Sign-in API. Please consult Google documentation
for the most up-to-date information on available claims.
==== LinkedIn social broker updated to Version 2 of LinkedIn APIs
Accordingly with LinkedIn, all developers need to migrate to version 2.0 of their APIs and OAuth 2.0. As such, we have updated
our LinkedIn Social Broker.
Existing deployments using this broker may start experiencing errors when fetching user's profile using version 2 of
LinkedIn APIs. This error may be related with the lack of permissions granted to the client application used to configure the broker
which may not be authorized to access the Profile API or request specific OAuth2 scopes during the authentication process.
Even for newly created LinkedIn client applications, you need to make sure that the client is able to request the `r_liteprofile` and
`r_emailaddress` OAuth2 scopes, at least, as well that the client application can fetch current member's profile from the `https://api.linkedin.com/v2/me` endpoint.
Due to these privacy restrictions imposed by LinkedIn in regards to access to member's information and the limited set of claims returned by the
current member's Profile API, the LinkedIn Social Broker
is now using the member's email address as the default username. That means that the `r_emailaddress` is always set when
sending authorization requests during the authentication.
=== Migrating to 4.6.0
==== New default client scopes
We have added new realm default client scopes `roles` and `web-origins`. These client scopes contain protocol
mappers to add the roles of the user and allowed web origins to the token. During migration, these client scopes should be
automatically added to all the OpenID Connect clients as default client scopes. Hence no setup should be required after database
migration is finished.
===== Protocol mapper SPI addition
Related to this, a small addition to the (unsupported) Protocol Mappers SPI exists. You can be affected only if you
implemented a custom ProtocolMapper. A new `getPriority()` method on the ProtocolMapper interface got introduced. The method has the
default implementation set to return 0. If your protocol mapper implementation relies on the roles in the access token `realmAccess`
or `resourceAccess` properties, you may need to increase the priority of your mapper.
===== Audience resolving
Audiences of all the clients, for which authenticated user has at least one client role in the token, are automatically added
to the `aud` claim in the access token now. On the other hand, an access token may not automatically contain the audience of the
frontend client, for which it was issued. Read the link:{adminguide_link}#audience-support[{adminguide_name}] for more details.
==== JavaScript adapter promise
To use native JavaScript promise with the JavaScript adapter it is now required to set `promiseType` to `native` in the
init options.
In the past if native promise was available a wrapper was returned that provided both the legacy Keycloak promise and
the native promise. This was causing issues as the error handler was not always set prior to the native error event, which
resulted in `Uncaught (in promise)` error.
==== Microsoft Identity Provider updated to use the Microsoft Graph API
The Microsoft Identity Provider implementation in {project_name} up to version 4.5.0 relies on the Live SDK
endpoints for authorization and obtaining the user profile. From November 2018 onwards, Microsoft is removing support
for the Live SDK API in favor of the new Microsoft Graph API. The {project_name} identity provider has been updated
to use the new endpoints so if this integration is in use make sure you upgrade to {project_name} version 4.6.0 or later.
Legacy client applications registered under "Live SDK applications" won't work with the Microsoft Graph endpoints
due to changes in the id format of the applications. If you run into an error saying that the application identifier
was not found in the directory, you will have to register the client application again in the
https://account.live.com/developers/applications/create[Microsoft Application Registration] portal to obtain a new application id.
==== Upgrade to Wildfly 14
The {project_name} server was upgraded to use Wildfly 14 as the underlying container. This does not directly involve any
specific {project_name} server functionality, however, note these changes related to migration:
Dependency updates::
The dependencies were updated to the versions used by the Wildfly 14 server. For example, Infinispan is now 9.3.1.Final.
Configuration changes::
A few configuration changes exist in the `standalone(-ha).xml` and `domain.xml` files. You should follow the <<_install_new_version>>
section to handle the migration of configuration files automatically.
Cross-Datacenter Replication changes::
* You will need to upgrade {jdgserver_name} server to version {jdgserver_version}. The older version may still work, but it is
not guaranteed as we don't test it anymore.
ifeval::[{project_product}==true]
* The `protocolVersion` property of the `remote-store` element in the {project_name} configuration must be set to the value `2.6`.
This is required so the version of HotRod protocol is downgraded to be compatible with the version used by {jdgserver_name} {jdgserver_version}.
endif::[]
=== Migrating to 4.4.0
==== Upgrade to Wildfly 13
The {project_name} server was upgraded to use Wildfly 13 as the underlying container. This does not directly involve any
specific {project_name} server functionality, however, note these changes related to migration:
Dependency updates::
The dependencies were updated to the versions used by the Wildfly 13 server. For example, Infinispan is now 9.2.4.Final and Undertow is 2.0.9.Final
Configuration changes::
A few configuration changes exist in the `standalone(-ha).xml` and `domain.xml` files. You should follow the <<_install_new_version>>
section to handle the migration of configuration files automatically. However, here are the most important changes, which you may need
if you made your own configuration changes:
* Element `eviction` on infinispan caches is now *deprecated* (unused) and is *replaced with* element `object-memory`
* The `cache-container` element in Infinispan subsystem *does not recognize* the `jndi-attribute` anymore.
Cross-Datacenter Replication changes::
* You will need to upgrade {jdgserver_name} server to version {jdgserver_version}. The older version may still work, but it is
not guaranteed as we don't test it anymore.
* You don't need to configure security anymore in the {jdgserver_name} server configuration file.
ifeval::[{project_community}==true]
* The `transaction` element needs to be removed from the configuration of replicated caches in the {jdgserver_name} server
configuration file. This is needed because of the infinispan bug https://issues.redhat.com/browse/ISPN-9323.
endif::[]
=== Migration to 4.3.0
==== Hostname configuration
In previous versions it was recommended to use a filter to specify permitted hostnames. It is now possible to
set a fixed hostname which makes it easier to make sure the valid hostname is used and also allows internal
applications to invoke {project_name} through an alternative URL, for example an internal IP address. It is
recommended that you switch to this approach in production.
=== Migrating to 4.0.0
==== Client Templates changed to Client Scopes
We added support for Client Scopes, which requires some attention during migration.
Client Templates changed to Client Scopes::
Client Templates were changed to Client Scopes. If you had any Client Templates, their protocol mappers and role scope mappings
will be preserved.
Spaces replaced in the names::
Client templates with the space character in the name were renamed by replacing spaces with an underscore, because spaces are
not allowed in the name of client scopes. For example, a client template `my template` will be changed to client scope `my_template`.
Linking Client Scopes to Clients::
For clients which had the client template, the corresponding client scope
is now added as `Default Client Scope` to the client. So protocol mappers and role scope mappings will be preserved on the client.
Realm Default Client Scopes not linked with existing clients::
During the migration, the list of built-in client scopes is added to each realm as well as list of `Realm Default Client Scopes`. However,
existing clients are NOT upgraded and new client scopes are NOT automatically added to them. Also all the protocol mappers and role
scope mappings are kept on existing clients. In the new version, when you create a new client, it automatically has Realm Default Client Scopes
attached to it and it does not have any protocol mappers attached to it. We did not change existing clients during migration as it
would be impossible to properly detect customizations, which you will have for protocol mappers of the clients, for example. If you want to
update existing clients (remove protocol mappers from them and link them with client scopes), you will need to do it manually.
Consents need to be confirmed again::
The client scopes change required the refactoring of consents. Consents now point to client scopes, not to roles or protocol mappers.
Because of this change, the previously confirmed persistent consents by users are not valid anymore and users need to confirm
the consent page again after the migration.
Some configuration switches removed::
The switch `Scope Param Required` was removed from Role Detail. The switches `Consent Required` and `Consent Text` were removed
from the Protocol Mapper details. Those switches are replaced with the Client Scope feature.
==== Changes to Authorization Services
We added support for UMA 2.0. This version of the UMA specification introduced some important changes on how permissions are obtained from the server.
Here are the main changes introduced by UMA 2.0 support. See link:{authorizationguide_link}[{authorizationguide_name}] for details.
Authorization API was removed::
Prior to UMA 2.0 (UMA 1.0), client applications were using the Authorization API to obtain permissions from the server in the format of an RPT. The new version
of UMA specification has removed the Authorization API which was also removed from {project_name}. In UMA 2.0, RPTs can now be obtained from the token endpoint by using a specific grant type.
See link:{authorizationguide_link}#_service_obtaining_permissions[{authorizationguide_name}] for details.
Entitlement API was removed::
With the introduction of UMA 2.0, we decided to leverage the token endpoint and UMA grant type to allow obtaining RPTs from {project_name} and
avoid having different APIs. The functionality provided by the Entitlement API was kept the same and is still possible to obtain permissions for a set
of one or more resources and scopes or all permissions from the server in case no resource or scope is provided.
See link:{authorizationguide_link}#_service_obtaining_permissions[{authorizationguide_name}] for details.
Changes to UMA Discovery Endpoint::
UMA Discovery document changed, see link:{authorizationguide_link}#_service_authorization_api[{authorizationguide_name}] for details.
Changes to {project_name} Authorization JavaScript adapter::
The {project_name} Authorization JavaScript adapter (keycloak-authz.js) changed in order to comply with the changes introduced by UMA 2.0 while keeping
the same behavior as before. The main change is on how you invoke both `authorization` and `entitlement` methods which now
expect a specific object type representing an authorization request. This new object type provides more flexibility on how
permissions can be obtained from the server by supporting the different parameters supported by the UMA grant type.
See link:{authorizationguide_link}#_enforcer_js_adapter[{authorizationguide_name}] for details.
One of the main changes introduced by this release is that you are no longer required to exchange access tokens with RPTs in
order to access resources protected by a resource server (when not using UMA). Depending on how the policy enforcer is configured on the resource server side, you can just send regular
access tokens as a bearer token and permissions will still be enforced.
Changes to {project_name} Authorization Client Java API::
When upgrading to the new version of {project_name} Authorization Client Java API, you'll notice that some representation classes
were moved to a different package in `org.keycloak:keycloak-core`.
=== Migrating to 3.4.2
==== Added session_state parameter to OpenID Connect Authentication Response
The OpenID Connect Session Management specification requires that the parameter `session_state` is present in the OpenID Connect Authentication Response.
In past releases, we did not have this parameter, but now {project_name} adds this parameter by default, as required by the specification.
However, some OpenID Connect / OAuth2 adapters, and especially older {project_name} adapters, may have issues with this new parameter.
For example, the parameter will be always present in the browser URL after successful authentication to the client application.
In these cases, it may be useful to disable adding the `session_state` parameter to the authentication response. This can be done
for the particular client in the {project_name} admin console, in client details in the section with `OpenID Connect Compatibility Modes`,
described in <<_compatibility_with_older_adapters>>. Dedicated `Exclude Session State From Authentication Response` switch exists,
which can be turned on to prevent adding the `session_state` parameter to the Authentication Response.
NOTE: The parameter `session_state` was added in 3.4.2, however the switch `Exclude Session State From Authentication Response` was added
in 4.0.0.Beta1. If your {project_name} server is on 3.4.2 or 3.4.3 and you have issues with `session_state` parameter, you will need
to upgrade the server to 4.0.0.Beta1 or newer.
=== Migrating to 3.2.0
==== New password hashing algorithms
We've added two new password hashing algorithms (pbkdf2-sha256 and pbkdf2-sha512). New realms will use the pbkdf2-sha256
hashing algorithm with 27500 hashing iterations. Since pbkdf2-sha256 is slightly faster than pbkdf2 the iterations was
increased to 27500 from 20000.
Existing realms are upgraded if the password policy contains the default value for hashing algorithm (not specified) and
iteration (20000). If you have changed the hashing iterations you need to manually change to pbkdf2-sha256 if you'd like
to use the more secure hashing algorithm.
==== ID Token requires scope=openid
OpenID Connect specification requires that parameter `scope` with value `openid` is used in initial authorization request. So in {project_name}
2.1.0 we changed our adapters to use `scope=openid` in the redirect URI to {project_name}. Now we changed the server part too and ID token
will be sent to the application just if `scope=openid` is really used. If it's not used, then ID token will be skipped and just Access token and Refresh token will be sent to the application.
This also allows that you can omit the generation of ID Token on purpose - for example for space or performance purposes.
Direct grants (OAuth2 Resource Owner Password Credentials Grant) and Service accounts login (OAuth2 Client credentials grant) also don't use ID Token by default now.
You need to explicitly add `scope=openid` parameter to have ID Token included.
==== Authentication sessions and Action tokens
We are working on support for multiple datacenters. As the initial step, we introduced authentication session and action tokens.
Authentication session replaces Client session, which was used in previous versions. Action tokens are currently used especially for the scenarios, where
the authenticator or requiredActionProvider requires sending email to the user and requires user to click on the link in email.
Here are concrete changes related to this, which may affect you for the migration.
First change related to this is introducing new Infinispan caches `authenticationSessions` and `actionTokens` in `standalone.xml` or `standalone-ha.xml`. If you use our migration CLI, you
don't need to care much as your `standalone(-ha).xml` files will be migrated automatically.
Second change is changing of some signatures in methods of authentication SPI. This may affect you if you use custom `Authenticator` or
`RequiredActionProvider`. Classes `AuthenticationFlowContext` and `RequiredActionContext` now allow to retrieve authentication session
instead of client session.
We also added some initial support for sticky sessions. You may want to change your load balancer/proxy server and configure it if you don't want to suffer from it and want to have better performance.
The route is added to the new `AUTH_SESSION_ID` cookie. More info in the clustering documentation.
Another change is, that `token.getClientSession()` was removed. This may affect you for example if you're using Client Initiated Identity Broker Linking feature.
The `ScriptBasedAuthenticator` changed the binding name from `clientSession` to `authenticationSession`, so you would need to update your scripts if you're using this authenticator.
Finally we added some new timeouts to the admin console. This allows you for example to specify different timeouts for the email actions triggered by admin and by user himself.
=== Migrating to 2.5.1
==== Migration of old offline tokens
If you migrate from version 2.2.0 or older and you used offline tokens, then your offline tokens didn't have KID in the token header.
We added KID to the token header in 2.3.0 together with the ability to have multiple realm keys, so {project_name} is able to find the correct key based on the token KID.
For the offline tokens without KID, {project_name} 2.5.1 will always use the active realm key to find the proper key for the token verification. In other words, migration of old
offline tokens will work. So for example, your user requested offline token in 1.9.8, then you migrate from 1.9.8 to 2.5.1 and then your user will be
still able to refresh his old offline token in 2.5.1 version.
But a limitation exists. Once you change the realm active key, the users won't be able to refresh old offline tokens
anymore. So you shouldn't change the active realm key until all your users with offline tokens refreshed their tokens. Obviously newly
refreshed tokens will have KID in the header, so after all users exchange their old offline tokens, you are free to change the active realm key.
=== Migrating to 2.5.0
==== Changes to the Infinispan caches
The `realms` cache defined in the infinispan subsystem in `standalone.xml` or `standalone-ha.xml` configuration file, now has the eviction with the 10000 records by default.
This is the same default as the `users` cache.
Also the `authorization` cache now doesn't have any eviction on it by default.
=== Migrating to 2.4.0
==== Server SPI split into Server SPI and Sever SPI Private
The keycloak-server-spi module has been split into keycloak-server-spi and keycloak-server-spi-private. APIs within
keycloak-server-spi will not change between minor releases, while we reserve the right and may quite likely change
APIs in keycloak-server-spi-private between minor releases.
==== Key encryption algorithm in SAML assertions
Key in SAML assertions and documents are now encrypted using RSA-OAEP encryption scheme.
If you want to use encrypted assertions, make sure that service providers understand this encryption scheme.
In the unlikely case that SP would not be able to handle the new scheme, {project_name}
can be made to use legacy RSA-v1.5 encryption scheme when started with system property
`keycloak.saml.key_trans.rsa_v1.5` set to `true`.
==== Infinispan caches realms and users are always local
Even if you use {project_name} in cluster, the caches `realms` and `users` defined in infinispan subsystem in `standalone-ha.xml` are
always local caches now. A separate cache `work` exists, which handles sending invalidation messages between cluster nodes and informing whole cluster
what records in underlying `realms` and `users` caches should be invalidated.
=== Migrating to 2.3.0
==== Default max results on paginated endpoints
All Admin REST API endpoints that support pagination now have a default max results set to 100. If you want to return
more than 100 entries you need to explicitly specify that with `?max=`.
==== `realm-public-key` adapter property not recommended
In 2.3.0 release we added support for Public Key Rotation. When admin rotates the realm keys in Keycloak admin console, the Client
Adapter will be able to recognize it and automatically download new public key from Keycloak. However this automatic download of new
keys is done just if you don't have `realm-public-key` option in your adapter with the hardcoded public key. For this reason, we don't recommend
to use `realm-public-key` option in adapter configuration anymore.
Note this option is still supported, but it may be useful just if you really want to have hardcoded public key in your adapter configuration
and never download the public key from Keycloak. In theory, one reason for this can be to avoid man-in-the-middle attack if you have untrusted network between adapter and Keycloak,
however in that case, it is much better option to use HTTPS, which will secure all the requests between adapter and Keycloak.
==== Added Infinispan cache `keys`
In this release, we added new cache `keys` to the infinispan subsystem, which is defined in `standalone.xml` or `standalone-ha.xml` configuration file.
It has also some eviction and expiration defined. This cache is internally used for caching the external public keys of the entities
trusted by the server (Identity providers or clients, which uses authentication with signed JWT).
=== Migrating to 2.2.0
==== `databaseSchema` property *deprecated*
The `databaseSchema` property for both JPA and Mongo is now *deprecated* and is *replaced with* `initializeEmpty`
and `migrationStrategy`. `initializeEmpty` can bet set to `true` or `false` and controls if an empty database should
be initialized. `migrationStrategy` can be set to `update`, `validate` and `manual`. `manual` is only supported for
relational databases and will write an SQL file with the required changes to the database schema. Please note that
for Oracle database, the created SQL file contains `SET DEFINE OFF` command understood by Oracle SQL clients.
Should the script be consumed by any other client, please replace the lines with equivalent command of the tool of
your choice that disables variable expansion or remove it completely if such functionality is not applicable.
==== Changes in Client's Valid Redirect URIs
The following scenarios are affected:
* When a Valid Redirect URI with query component is saved in a Client (e.g. `\http://localhost/auth?foo=bar`), `redirect_uri` in authorization request must exactly match this URI (or other registered URI in this Client).
* When a Valid Redirect URI without a query component is saved in a Client, `redirect_uri` must exactly match as well.
* Wildcards in registered Valid Redirect URIs are no longer supported when query component is present in this URI, so the `redirect_uri` needs to exactly match this saved URI as well.
* Fragments in registered Valid Redirect URIs (like `\http://localhost/auth#fragment`) are no longer allowed.
==== Authenticate by default removed from Identity Providers
Identity providers no longer has an option to set it as a default authentication provider. Instead go to Authentication, select the `Browser` flow and configure the `Identity Provider Redirector`. It has an option to set the default identity provider.
=== Migrating to 2.0.0
==== Upgrading from 1.0.0.Final no longer supported
Upgrading from 1.0.0.Final is no longer supported. To upgrade to this version upgrade to 1.9.8.Final prior to upgrading
to 2.0.0.
=== Migrating to 1.9.5
==== Default password hashing interval increased to 20K
The default password hashing interval for new realms has been increased to 20K (from 1 previously). This change will have an impact
on performance when users authenticate. For example with the old default (1) it takes less than 1 ms to hash a password, but with
the new default (20K) the same operation can take 50-100 ms.
=== Migrating to 1.9.3
==== Add User script renamed
The script to add admin users to Keycloak has been renamed to `add-user-keycloak`.
=== Migrating to 1.9.2
==== Adapter option auth-server-url-for-backend-requests removed
We've removed the option auth-server-url-for-backend-requests due to issues in some scenarios when it was used. In more details,
it was possible to access the Keycloak server from 2 different contexts (internal and external), which was causing issues in token validations etc.
If you still want to use the optimization of network, which this option provided (avoid the application to send backchannel requests
through load balancer but send them to local Keycloak server directly) you may need to handle it at hosts configuration (DNS) level.
=== Migrating to 1.9.0
==== Themes and providers directory moved
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.
==== Adapter subsystems only bring in dependencies if Keycloak is on
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)
==== Client Registration service endpoints moved
The Client Registration service endpoints have been moved from `{realm-name}/clients` to `{realm-name}/clients-registrations`.
==== Session state parameter in authentication response renamed
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`.
==== Deprecated OpenID Connect endpoints
In 1.2 we deprecated a number of endpoints that where not consistent with the OpenID Connect specifications, these have now been removed.
This also applies to the validate token endpoint that is replaced with the new introspect endpoint in 1.8.
==== Updates to theme templates
Feedback in template.ftl has been moved and format has changed slightly.
==== Module and source code reorganization
Most of our modules and source code have been consolidated into two maven modules: keycloak-server-spi and keycloak-services.
SPI interfaces are in server-spi, implementations are in keycloak-services.
All JPA dependent modules have been consolidated under keycloak-model-jpa.
Same goes with mongo and Infinispan under modules keycloak-model-mongo and keycloak-model-infinispan.
==== For adapters, session id changed after login
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.
==== SAML SP Client adapter changes
Keycloak SAML SP Client adapter now requires a specific endpoint, `/saml` to be registered with your IDP.
=== Migrating to 1.8.0
==== Admin account
In previous releases we shipped with a default admin user with a default password, this has now been removed.
If you are doing a new installation of 1.8 you will have to create an admin user as a first step.
==== OAuth2 token introspection
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-name}/protocols/openid-connect/token/introspect` and it is solely based on `RFC-7662`.
The `/realms/{realm-name}/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-name}/.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.
=== Migrating to 1.7.0.CR1
==== Direct access grants disabled by default for clients
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 built-in 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.
==== Option 'Update Profile On First Login' moved from Identity provider to Review Profile authenticator
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 no Keycloak user linked to the social account exists yet.
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.
==== Element 'form-error-page' in web.xml not supported anymore
form-error-page in web.xml will no longer work for client adapter authentication errors.
You must define an error-page for the various HTTP error codes.
See documentation for more details if you want to catch and handle adapter error conditions.
==== IdentityProviderMapper changes
The interface itself and method signatures did not change. However some changes in the behavior exist.
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.
=== Migrating to 1.6.0.Final
==== Option that refresh tokens are not reusable anymore
Old versions of Keycloak allowed reusing refresh tokens multiple times.
Keycloak still permits this, but also have an option `Revoke refresh token` to disallow it.
Option is under token settings in admin console.
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.
==== Some packages renamed
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, a slight chance exists 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.
==== Persisting user sessions
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 `standalone/configuration/keycloak-server.json` and add `userSessionPersister` like this:
[source,json]
----
"userSessionPersister": {
"provider": "jpa"
},
----
If you want sessions to be persisted in Mongo instead of classic RDBMS, use provider `mongo` instead.
=== Migrating to 1.5.0.Final
==== Realm and User cache providers
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 the realmCache and userCache objects are no longer needed and can be removed.
==== Uses Session providers
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 the userSession object is no longer needed and 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.
==== Contact details removed from registration and account management
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.
=== Migrating to 1.3.0.Final
==== Direct Grant API always enabled
In the past Direct Grant API (or Resource Owner Password Credentials) was disabled by default and an option to enable it on a realm existed.
The Direct Grant API is now always enabled and the option to enable/disable for a realm is removed.
==== Database changed
There are again few database changes.
Remember to back up your database prior to upgrading.
==== UserFederationProvider changed
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.
==== WildFly 9.0.0.Final
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 also 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.
==== WildFly, JBoss EAP and JBoss AS7 adapters
There are now 3 separate adapter downloads for WildFly, JBoss EAP and JBoss AS7:
* eap6
* wf9
* wf8
* as7
Make sure you grab the correct one.
You also need to update standalone.xml as the extension module and subsystem definition has changed.
See link:{adapterguide_link}[{adapterguide_name}] for details.
=== Migrating from 1.2.0.Beta1 to 1.2.0.RC1
==== Distribution changes
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.
==== Database changed
This release contains again a number of changes to the database.
The biggest one is Application and OAuth client merge.
Remember to back up your database prior to upgrading.
==== Application and OAuth client merge
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.
=== Migrating from 1.1.0.Final to 1.2.0.Beta1
==== Database changed
This release contains a number of changes to the database.
Remember to back up your database prior to upgrading.
==== `iss` in access and id tokens
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 no change is required, except if you've been using bearer-only without specifying the `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`.
==== OpenID Connect endpoints
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-name}/protocols/openid-connect/login`, `/realms/{realm-name}/protocols/openid-connect/grants/access`, `/realms/{realm-name}/protocols/openid-connect/refresh`, `/realms/{realm-name}/protocols/openid-connect/access/codes`) are now deprecated and will be removed in a future version.
==== Theme changes
The layout of themes has 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 groups of 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.
==== Claims changes
Previously a dedicated `Claims` tab existed in the 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 is 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 back up DB before migrating to newer version though). Same applies for exported JSON representation from previous version.
==== Social migration to identity brokering
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).
=== Migrating from 1.1.0.Beta1 to 1.1.0.Beta2
* 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.
* `org.keycloak.adapters.tomcat7.KeycloakAuthenticatorValve`
+`org.keycloak.adapters.tomcat.KeycloakAuthenticatorValve`
* 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.
=== Migrating from 1.0.x.Final to 1.1.0.Beta1
* 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.
=== Migrating from 1.0 RC-1 to RC-2
* 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.
=== Migrating from 1.0 Beta 4 to RC-1
* 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.
=== Migrating from 1.0 Beta 1 to Beta 4
* 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`
+`ssl-required`
+`all`
+`external`
+`none`
* 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.
=== Migrating from 1.0 Alpha 4 to Beta 1
* 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.
* Direct Grant API
+`ON`
* standalone/configuration/keycloak-server.json
* JavaScript adapter
* Session Timeout
=== Migrating from 1.0 Alpha 2 to Alpha 3
* SkeletonKeyToken, SkeletonKeyScope, SkeletonKeyPrincipal, and SkeletonKeySession have been renamed to:
AccessToken, AccessScope, KeycloakPrincipal, and KeycloakAuthenticatedSession respectively.
* ServletOAuthClient.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.
=== Migrating from 1.0 Alpha 1 to Alpha 2
* 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 {appserver_name} subsystem. Please review the adapter
installation documentation. Edits to standalone.xml are now required.
* A new credential type "secret" got introduced. Unlike other credential types, it is stored in plain text in
the database and can be viewed in the admin console.
* Application and OAuth Client credentials are no longer required. 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 regenerate a secret within the Application or OAuth Client
credentials tab in the administration console.