CIAM-956 Forward port 7.5 Upgrading Guide changes to upstream (#1257)

* Changing Keycloak release to 15.0.2 as the starting point for migrating to SSO 7.5

(cherry picked from commit bbd909a64e0588e7b63a8aabf698f2d609003705)

* CIAM-956 Fixing conflicts

(cherry picked from commit 8452c8d1e0fdb284423f84bda91604f49d21a750)

release_notes/topics/14_0_0.adoc

@@ -30,4 +30,4 @@ endif::[]
 
 == Other improvements
 
-* The support for configuring maximum number of active authentication sessions. The default value is set to 300 authentication sessions (browser tabs) per a browser's session
+* The support for configuring maximum number of active authentication sessions. The default value is set to 300 authentication sessions (browser tabs) per a browser's session

securing_apps/topics/oidc/java/fuse7-adapter.adoc

@@ -4,7 +4,7 @@
 
 {project_name} supports securing your web applications running inside https://developers.redhat.com/products/fuse/overview[JBoss Fuse 7].
 
-JBoss Fuse 7 leverages Undertow adapter which is essentially the same as 
+JBoss Fuse 7 leverages Undertow adapter which is essentially the same as
 ifeval::[{project_community}==true]
 <<_jboss_adapter,EAP 7 / WildFly Adapter>>
 endif::[]

server_admin/topics/authentication/kerberos.adoc

@@ -53,13 +53,13 @@ Ensure the keytab file `/tmp/http.keytab` is accessible on the host where {proje
 
 [[_server_setup]]
 
-Install a Kerberos client on your machine. 
+Install a Kerberos client on your machine.
 
 .Procedure
 . Install a Kerberos client. If your machine runs Fedora, Ubuntu, or RHEL, install the link:https://www.freeipa.org/page/Downloads[freeipa-client] package, containing a Kerberos client and other utilities.
-. Configure the Kerberos client (on Linux, the configuration settings are in the link:https://web.mit.edu/kerberos/krb5-1.12/doc/admin/conf_files/krb5_conf.html[/etc/krb5.conf] file ). 
+. Configure the Kerberos client (on Linux, the configuration settings are in the link:https://web.mit.edu/kerberos/krb5-1.12/doc/admin/conf_files/krb5_conf.html[/etc/krb5.conf] file ).
 +
-Add your Kerberos realm to the configuration and configure the HTTP domains your server runs on. 
+Add your Kerberos realm to the configuration and configure the HTTP domains your server runs on.
 +
 For example, for the MYDOMAIN.ORG realm, you can configure the `domain_realm` section like this:
 +
@@ -95,7 +95,7 @@ To authenticate with Kerberos backed by an LDAP server, configure the <<_ldap, L
 .Ldap kerberos integration
 image:{project_images}/ldap-kerberos.png[LDAP Kerberos Integration]
 +
-. Toggle *Allow Kerberos authentication* to *ON* 
+. Toggle *Allow Kerberos authentication* to *ON*
 
 *Allow Kerberos authentication* makes {project_name} use the Kerberos principal access user information so information can import into the {project_name} environment.
 
@@ -128,7 +128,8 @@ When you install https://www.docker.com/[docker], run a docker image with the Fr
 
 ===== ApacheDS testing Kerberos server
 
-For quick testing and unit tests, use a simple http://directory.apache.org/apacheds/[ApacheDS] Kerberos server. You must build {project_name} from the source and then run the Kerberos server with the maven-exec-plugin from our test suite. See details https://github.com/keycloak/keycloak/blob/main/docs/tests.md#kerberos-server[here].
+For quick testing and unit tests, use a simple http://directory.apache.org/apacheds/[ApacheDS] Kerberos server. You must build {project_name} from the source and then run the Kerberos server with the maven-exec-plugin from our test suite. See details
+https://github.com/keycloak/keycloak/blob/main/docs/tests.md#kerberos-server[here].
 endif::[]
 
 ==== Credential delegation
@@ -156,7 +157,7 @@ GSSContext context = gssManager.createContext(serviceName, krb5Oid,
 ----
 
 ifeval::[{project_community}==true]
-Examples of this code exist in `examples/kerberos` in the {project_name} example distribution or demo distribution download. You can also check the example sources directly https://github.com/keycloak/keycloak/tree/master/examples/kerberos[here].
+Examples of this code exist in `examples/kerberos` in the {project_name} example distribution or demo distribution download. You can also check the example sources directly https://github.com/keycloak/keycloak/tree/main/examples/kerberos[here].
 endif::[]
 
 [NOTE]
@@ -171,7 +172,7 @@ Credential delegation has security implications, so use it only if necessary and
 
 ==== Cross-realm trust
 
-In the Kerberos protocol, the `realm` is a set of Kerberos principals. The definition of these principals exists in the Kerberos database, which is typically an LDAP server. 
+In the Kerberos protocol, the `realm` is a set of Kerberos principals. The definition of these principals exists in the Kerberos database, which is typically an LDAP server.
 
 The Kerberos protocol allows cross-realm trust. For example, if 2 Kerberos realms, A and B, exist, then cross-realm trust will allow the users from realm A to access realm B's resources. Realm B trusts realm A.
 
@@ -189,7 +190,7 @@ The cross-realm trust is unidirectional by default. You must add the principal `
 
 * Configure {project_name} server
 
-** When using an LDAP storage provider with Kerberos support, configure the server principal for realm B, as in this example: `HTTP/mydomain.com@B`. The LDAP server must find the users from realm A if users from realm A are to successfully authenticate to {project_name}, because {project_name} must perform the SPNEGO flow and then find the users. 
+** When using an LDAP storage provider with Kerberos support, configure the server principal for realm B, as in this example: `HTTP/mydomain.com@B`. The LDAP server must find the users from realm A if users from realm A are to successfully authenticate to {project_name}, because {project_name} must perform the SPNEGO flow and then find the users.
 
 For example, Kerberos principal user `john@A` must be available in the LDAP under an LDAP DN such as `uid=john,ou=People,dc=example,dc=com`. If you want users from realm A and B to authenticate, ensure that LDAP can find users from both realms A and B.
 

topics/templates/document-attributes-product.adoc

@@ -12,7 +12,7 @@
 :project_name_full: Red Hat Single Sign-On
 :project_version_base: 7.5
 :project_version: 7.5.0
-:keycloak_upgrade_version: 15.0.x
+:keycloak_upgrade_version: 15.0.2
 :project_versionDoc: 7.5
 :project_templates_base_url: https://raw.githubusercontent.com/jboss-container-images/redhat-sso-7-openshift-image/sso75-cpaas-dev/templates
 :project_latest_image_tag: {project_versionDoc}

upgrading/topics/install_new_version.adoc

@@ -32,13 +32,11 @@ To upgrade {project_name} server RPM distribution, complete the following steps:
 +
 For Red Hat Enterprise Linux 7:
 +
- subscription-manager repos --enable=jb-eap-7.3-for-rhel-7-server-rpms
+ subscription-manager repos --enable=rh-sso-7.5-for-rhel-7-x86_64-rpms
- subscription-manager repos --enable=rh-sso-7.4-for-rhel-7-server-rpms
 +
 For Red Hat Enterprise Linux 8:
-
++
- subscription-manager repos --enable=jb-eap-7.3-for-rhel-8-x86_64-rpms --enable=rhel-8-for-x86_64-baseos-rpms --enable=rhel-8-for-x86_64-appstream-rpms
+ subscription-manager repos --enable=rh-sso-7.5-for-rhel-8-x86_64-rpms
- subscription-manager repos --enable=rh-sso-7.4-for-rhel-8-x86_64-rpms
 +
 [NOTE]
 ====

upgrading/topics/rhsso/changes-75.adoc

@@ -0,0 +1,115 @@
+== 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.
+
+
+
+

upgrading/topics/rhsso/changes.adoc

@@ -3,6 +3,7 @@
 
 Review these changes carefully before upgrading.
 
+include::changes-75.adoc[leveloffset=1]
 include::changes-74.adoc[leveloffset=1]
 include::changes-73.adoc[leveloffset=1]
 include::changes-72.adoc[leveloffset=1]