== 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 a 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. Read the link:{adminguide_link}#_audience[{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.

=== JavaScipt 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.

=== Google Identity Provider updated to use Google Sign-in authentication system

The Google Identity Provider implementation in {project_name} up to version 7.2.5 relies on the Google+ API endpoints
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 7.2.6 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.developers.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.