== RH SSO 7.5

The following changes have occurred from {project_name} 7.4 to {project_name} 7.5.

=== Upgrade to EAP 7.4

The {project_name} server was upgraded to use EAP 7.4 as the underlying container. This change does not directly involve any specific {project_name} server functionality, but a few changes relate to the migration.

==== Dependency updates

The dependencies were updated to the versions used by EAP 7.4 server. For example, the Infinispan component version is now 11.0.

==== Configuration changes

There are a 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. 

==== SmallRye manual changes
Manual changes are required when standalone.xml contains references to SmallRye modules. These modules were removed from the underlying {appserver_name} distribution, and the server does not start if the configuration references them. The server configuration migration via `migrate-standalone.cli` fails before any changes are made to the configuration.

To correct this problem, remove all the lines that refer to SmallRye modules. In the default configuration, you need to remove specifically the following lines:

[source,xml]
<extension module="org.wildfly.extension.microprofile.config-smallrye"/>
<extension module="org.wildfly.extension.microprofile.health-smallrye"/>
<extension module="org.wildfly.extension.microprofile.metrics-smallrye"/>

[source,xml]
<subsystem xmlns="urn:wildfly:microprofile-config-smallrye:1.0"/>
<subsystem xmlns="urn:wildfly:microprofile-health-smallrye:2.0" security-enabled="false" empty-liveness-checks-status="${env.MP_HEALTH_EMPTY_LIVENESS_CHECKS_STATUS:UP}" empty-readiness-checks-status="${env.MP_HEALTH_EMPTY_READINESS_CHECKS_STATUS:UP}"/>
<subsystem xmlns="urn:wildfly:microprofile-metrics-smallrye:2.0" security-enabled="false" exposed-subsystems="*" prefix="${wildfly.metrics.prefix:wildfly}"/>

==== Cross-Datacenter replication changes

* You will need to upgrade {jdgserver_name} server to version {jdgserver_version_latest}. The older version may still work, but it is not guaranteed as it is no longer tested.

* We recommend that you use the `protocolVersion` property added to the remote-store element when configuring Infinispan caches. When connecting to the {jdgserver_name} server {jdgserver_version_latest}, the recommended version of the hotrod protocol version is 2.9. The Infinispan library version differs among {project_name} server and {jdgserver_name} server. For more details, see the Cross-Datacenter documentation.

* We recommend that you use `remoteStoreSecurityEnabled` property under the `connectionsinfinispan` subsystem. For more details, see the Cross-Datacenter documentation.

=== UserModel Migration 
The  `UserModel` includes certain fields, `username`, `email`, `firstName` and `lastName`, which are now converted to custom attributes.  This change was made to prepare for adding more sophisticated user profiles to {project_name} in an upcoming version.

NOTE: If a database contains users with custom attributes of that exact name, these attributes will no longer be read from the database and may be deleted. Therefore, before upgrading to RH SSO 7.5, rename any custom attribute that matches one of these names.

This situation implies that the `username` can now also be accessed and set by  `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 should adapt their policies if they use the number of attributes in their evaluations. 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.

=== 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 to the new version. An example with the necessary changes can be found in the `examples/themes/theme/sunrise` directory. No additional setup is required.

=== New API for Instagram IdP

Instagram IdP now uses a new API. The old legacy API was *deprecated*. This change requires new API credentials. For details, please refer to the link:{adminguide_link}#instagram[{adminguide_name}].

For users who use Instagram IdP to log into Instagram, those users need a different authentication method, such as a password. They can log in to manually update their Instagram social links or create a new account in {project_name}. This restriction exists because Instagram user IDs in the previous API are incompatible with the new API. However the new API temporarily returns both new and old user IDs to allow migration. {project_name} automatically migrates the ID once the user logs in.

=== Valid Request URIs for SSRF protection
If you use the OpenID Connect parameter `request_uri`, your client needs to have `Valid Request URIs` configured to protect against SSRF attacks

You can configure this feature 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 that are permitted for the particular client. 

You could instead use wildcards or relative paths, such as the `Valid Redirect URIs` option. However, we recommend using as specific value as possible for security purposes.

=== Read-only user attributes 
Read-only user attributes are now available.  Some of these user attributes are not to be edited by the user or administrator when updating users with the REST API or with the {project_name} user interfaces. In particular, this change is important when you use any of the following:

* Custom user storage providers
* Custom authenticators
* Custom Javascript authorization policies that establish authorization based on a user attribute
* X.509 authenticator with a 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.

For more details, see the link:{adminguide_link}#_read_only_user_attributes[Threat model mitigation chapter].

=== No user session needed after Docker 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}].

=== Client Credentials Grant without default refresh token
For 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 result, no user session is created on the {project_name} server side after successful Client Credentials authentication. The result is improved performance and memory consumption. Clients that use Client Credentials Grant are encouraged to stop using refresh tokens and instead authenticate at every request with `grant_type=client_credentials` instead of using `refresh_token` as grant type.

In relation to this, {project_name} supports revocation of access tokens in the OAuth2 Revocation Endpoint. Therefore, clients are allowed to revoke individual access tokens if needed.

For backwards compatibility, you could stay with the previous version’s behavior. With that approach, the refresh token is still issued after a successful authentication with the Client Credentials Grant and also the user session is created.  For a particular client, you can enable the previous behavior in the Admin Console as follows:

.Procedure

. Click *Clients* in the menu.
. Click the client you want to modify.
. Expand the *OpenID Connect Compatibility Modes* section.
. Toggle *Use Refresh Tokens For Client Credentials Grant* to *ON*.
. Click *Save.*

=== Non-standard token introspection endpoint removed
In previous versions, {project_name} 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 was deprecated 
and is now removed.

=== LDAP no-import fix
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 non-LDAP mapped attributes were changed. This situation resulted in confusing behavior. The attribute appeared to be updated, but it was not updated. 

For example, if you had 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 are immediately informed about the reason.