KEYCLOAK-8735 updates to upgrade guide for RH-SSO 7.3
This commit is contained in:
Matthew Helmke
Stian Thorgersen
parent
a4f08465be
commit
717f2f5fe9
3 changed files with 144 additions and 3 deletions
140
upgrading/topics/rhsso/changes-73.adoc
Normal file
140
upgrading/topics/rhsso/changes-73.adoc
Normal file
|
|
@ -0,0 +1,140 @@
|
|||
== RH-SSO 7.3
|
||||
|
||||
The following changes have occurred from RH-SSO 7.2 to RH-SSO 7.3.
|
||||
|
||||
=== 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.
|
||||
|
||||
=== 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.
|
||||
|
||||
=== 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, but there are few changes related to the migration, which worth mentioning.
|
||||
|
||||
Dependency updates::
|
||||
The dependencies were updated to the versions used by Wildfly 14 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.
|
||||
|
||||
=== 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.
|
||||
|
||||
=== 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`.
|
||||
|
||||
|
|
@ -2,5 +2,6 @@
|
|||
|
||||
Review these changes carefully before upgrading.
|
||||
|
||||
include::changes-73.adoc[leveloffset=1]
|
||||
include::changes-72.adoc[leveloffset=1]
|
||||
include::changes-71.adoc[leveloffset=1]
|
||||
|
|
|
|||
|
|
@ -2,7 +2,7 @@
|
|||
|
||||
== Introduction
|
||||
|
||||
Red Hat Single Sign-On (RH-SSO) 7.2 is based on the Keycloak project and provides security for your web applications by
|
||||
Red Hat Single Sign-On (RH-SSO) 7.3 is based on the Keycloak project and provides security for your web applications by
|
||||
providing Web single sign-on capabilities based on popular standards such as SAML 2.0, OpenID Connect, and OAuth 2.0.
|
||||
The Red Hat Single Sign-On Server can act as a SAML or OpenID Connect-based identity provider, mediating with your
|
||||
enterprise user directory or third-party SSO provider for identity information and your applications using standards-based
|
||||
|
|
@ -14,7 +14,7 @@ RH-SSO instances from a single control point. The upgrade process differs depend
|
|||
implemented. Specific instructions for each mode are provided where applicable.
|
||||
|
||||
The purpose of this guide is to document the steps that are required to successfully upgrade from
|
||||
Red Hat Single Sign-On 7.1 to Red Hat Single Sign-On 7.2.
|
||||
Red Hat Single Sign-On 7.2 to Red Hat Single Sign-On 7.3.
|
||||
|
||||
=== About Upgrades
|
||||
|
||||
|
|
@ -28,7 +28,7 @@ that could require rewriting parts of applications or server extensions.
|
|||
|
||||
Red Hat Single Sign-On periodically provides point releases, which are minor updates that include bug fixes, security
|
||||
fixes, and new features. If you plan to upgrade from one Red Hat Single Sign-On point release to another, for example,
|
||||
from Red Hat Single Sign-On 7.1 to Red Hat Single Sign-On 7.2, code changes should not be required for applications or
|
||||
from Red Hat Single Sign-On 7.2 to Red Hat Single Sign-On 7.3, code changes should not be required for applications or
|
||||
custom server extensions as long as no private, unsupported, or tech preview APIs are used.
|
||||
|
||||
==== Micro Updates
|
||||
|
|
|
|||
Loading…
Reference in a new issue