169 lines
12 KiB
Text
169 lines
12 KiB
Text
== RH-SSO 7.3
|
|
|
|
The following changes have occurred from RH-SSO 7.2 to RH-SSO 7.3.
|
|
|
|
=== 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`.
|
|
|
|
=== 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 were replaced by the Client Scope feature.
|
|
|
|
=== 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, there is a small addition in the (unsupported) Protocol Mappers SPI. You can be affected only if you
|
|
implemented a custom ProtocolMapper. There is a new `getPriority()` method on the ProtocolMapper interface. 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. See the link:{adminguide_link}#_audience_resolve[{adminguide_name}] for more details.
|
|
|
|
=== Upgrade to EAP 7.2
|
|
|
|
The {project_name} server was upgraded to use EAP 7.2 as the underlying container. This does not directly involve any
|
|
specific {project_name} server functionality, but there are few changes related to the migration, which worth mentioning.
|
|
|
|
Dependency updates::
|
|
The dependencies were updated to the versions used by EAP 7.2 server. For example, Infinispan is now 9.3.1.Final.
|
|
|
|
Configuration changes::
|
|
There are few configuration changes 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]
|
|
* There is a need to add `protocolVersion` property with the value `2.6` to the configuration of the `remote-store` element in the
|
|
{project_name} configuration. This is required as there is a need to downgrade the version of HotRod protocol to be compatible
|
|
with the version used by {jdgserver_name} {jdgserver_version}.
|
|
endif::[]
|
|
|
|
=== 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.
|
|
|
|
=== 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} used to rely 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 the latest {project_name} version.
|
|
|
|
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.
|
|
|
|
=== Google Identity Provider updated to use Google Sign-in authentication system
|
|
|
|
The Google Identity Provider implementation in {project_name} used to rely 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 the latest {project_name} version.
|
|
|
|
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.
|