KEYCLOAK-13759 Upgrading guide

server_admin/topics/identity-broker/first-login-flow.adoc

@@ -80,6 +80,7 @@ authenticators according to your needs. For example, you can add the Review Prof
 end users to confirm their profile information. You can also add authentication mechanisms to this flow, forcing a user to verify his credentials. This
 would require a more complex flow, for example setting the "Automatically Set Existing User" and "Password Form" as "Required" in an "Alternative" sub-flow.
 
+[[_disabling_automatic_user_creation]]
 ==== Disabling Automatic User Creation
 The Default first login flow will look up a Keycloak account matching the external identity, and will then offer to link them; if there is no matching Keycloak account, it will automatically create one.
 This default behavior may be unsuitable for some setups, for example, when using read-only LDAP user store (which means all users are pre-created).

topics/templates/document-attributes-product.adoc

@@ -31,11 +31,11 @@
 :adminguide_name: Server Administration Guide
 :adminguide_link: {project_doc_base_url}/server_administration_guide/
 :adminguide_authentication_flow_name: authentication flow
-:adminguide_authentication_flow_link: {adminguide_link}#authentication_flow
+:adminguide_authentication_flow_link: {adminguide_link}#_authentication-flows
 :adminguide_bruteforce_name: Password guess: brute force attacks
 :adminguide_bruteforce_link: {adminguide_link}#password-guess-brute-force-attacks
 :adminguide_disabling_automatic_user_creation_name: disabling automatic user creation
-:adminguide_disabling_automatic_user_creation_link: {adminguide_link}#disabling_automatic_user_creation
+:adminguide_disabling_automatic_user_creation_link: {adminguide_link}#_disabling_automatic_user_creation
 :adminguide_timeouts_name: Timeouts
 :adminguide_timeouts_link: {adminguide_link}#_timeouts
 :adminguide_clearcache_name: Clearing Server Caches
@@ -131,7 +131,7 @@
 :appserver_managementconsole_link: https://access.redhat.com/documentation/en-us/red_hat_jboss_enterprise_application_platform/7.0/html-single/configuration_guide/#management_console_overview
 
 :jdgserver_name: JDG
-:jdgserver_version: 7.3.0
+:jdgserver_version: 7.3.5
 :jdgserver_crossdcdocs_link: https://access.redhat.com/documentation/en-us/red_hat_data_grid/7.3/html/red_hat_data_grid_user_guide/x_site_replication
 
 :fuseVersion: JBoss Fuse 6.3.0 Rollup 12

upgrading/topics/rhsso/changes-74.adoc

@@ -0,0 +1,104 @@
+== RH SSO 7.4
+
+The following changes have occurred from {project_name} 7.3 to {project_name} 7.4.
+
+=== Upgrade to EAP 7.3
+
+The {project_name} server was upgraded to use EAP 7.3 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.3 server. For example, the Infinispan component version is now 9.3.1.Final.
+
+==== Configuration changes
+
+There are a few configuration changes in the standalone(-ha).xml and domain.xml files. Follow the Upgrading the {project_name} server section to handle the migration of configuration files automatically.
+
+==== Cross-Datacenter replication changes
+
+You will need to upgrade {jdgserver_name} to version {jdgserver_version}. The older version may still work, but it is not tested so it is not guaranteed to work.
+
+=== Authentication flows changes
+
+We did some refactoring and improvements related to the authentication flows, which requires attention during migration.
+
+==== REQUIRED and ALTERNATIVE executions not supported at same authentication flow
+
+Previously, it was possible to have REQUIRED and ALTERNATIVE executions in the same authentication flow at the same level. There were some issues with this approach and we did the refactoring in the Authentication SPI, which means that this is no longer valid. If ALTERNATIVE and REQUIRED executions are configured at the same level, the ALTERNATIVE executions are considered disabled.
+
+So when migrating to this version, your existing authentication flows will be migrated but retain the behavior of the previous version. If  an authentication flow contains ALTERNATIVE executions at the same level as REQUIRED executions, the ALTERNATIVE executions are added to the separate REQUIRED subflow.
+
+This strategy should ensure the same or similar behavior of the each authentication flow as in the previous version. However, you may review the configuration of your authentication flow and double check that it works as expected. This recommendation applies in particular for customized authentication flows with custom authenticator implementations.
+
+==== OPTIONAL execution requirement removed
+
+Regarding migration, the most important change is removing support for the OPTIONAL requirement from authentication executions and replacing it with the CONDITIONAL requirement, which allows more flexibility.
+
+OPTIONAL authenticators configured in the previous version are replaced with the CONDITIONAL subflows. These subflows have the Condition - User Configured condition configured as first execution, and the previously OPTIONAL authenticator (for example OTP Form) as second execution. For the user, the behavior during authentication matches the behavior of the previous version.
+
+==== SPI Changes
+
+Some changes exist in the Java Authentication SPI and Credential Provider SPI.
+
+The interface Authenticator is not changed, but you may be affected if you develop advanced authenticators that introduce some new credential types (subclasses of CredentialModel). Changes exist on the CredentialProvider interface and introduction of some new interfaces such as CredentialValidator.
+
+Also, you may be affected if your authenticator supported the OPTIONAL execution requirement. It is recommended that you double check the latest authentication examples in the server development guide for more details.
+
+==== Freemarker template changes
+
+Changes exist in the freemarker templates. You may be affected if you have your own theme with custom freemarker templates for login forms or some account forms, especially for the forms related to OTP. We recommend that you review the changes in the Freemarker templates in this version and align your templates according to it.
+
+=== User credentials changes
+
+We added more flexibility around storing user credentials. Among other things, every user can have multiple credentials of the same type, such as multiple OTP credentials. Some changes exist in the database schema in relation to that, however the credentials from the previous version are updated to the new format. Users can still log in with the passwords or OTP credentials defined in the previous version.
+
+=== New optional client scope
+
+We have added a microprofile-jwt optional client scope to handle the claims defined in the MicroProfile/JWT Auth Specification. This new client scope defines protocol mappers to set the username of the authenticated user to the upn claim and to set the realm roles to the groups claim.
+
+=== Improved handling of user locale
+
+A number of improvements have been made to how the locale for the login page is selected, as well as when the locale is updated for a user. See the link:{adminguide_link}[{adminguide_name}] for more details.
+
+=== Legacy promise in JavaScript adapter
+
+You no longer need to set promiseType in the JavaScript adapter, and both are available at the same time. It is recommended to update applications to use native promise API (then and catch) as soon as possible, as the legacy API (success and error) will be removed at some point.
+
+=== Deploying Scripts to the Server
+
+Until now, administrators were allowed to upload scripts to the server through the {project_name} Admin Console and the RESTful Admin API. This capability is now disabled. Users should deploy scripts directly to the server. For more details, review the link:{developerguide_jsproviders_link}[{developerguide_jsproviders_name}].
+
+
+=== Client Credentials in the JavaScript adapter
+
+In the previous releases, developers were allowed to provide client credentials to the JavaScript adapter. For now on, this capability was removed, because client-side apps are not safe to keep secrets.
+Ability to propagate prompt=none to default IDP
+
+We have added a switch in the OIDC identity provider configuration named Accepts prompt=none forward from client to identify IDPs that are able to handle forwarded requests that include the prompt=none query parameter.
+
+Until now, when receiving an auth request with prompt=none, a realm would return a login_required error if the user is not authenticated in the realm without checking if the user has been authenticated by an IDP. From now on, if a default IDP can be determined for the auth request (either by the use of the kc_idp_hint query param or by setting up a default IDP for the realm) and if the Accepts prompt=none forward from client switch has been enabled for the IDP, the auth request is forwarded to the IDP to check if the user has been authenticated there.
+
+It is important to note that this switch is only taken into account if a default IDP is specified, in which case we know where to forward the auth request without having to prompt the user to select an IDP. If a default IDP cannot be determined, we cannot assume which one will be used to fulfill the auth request so the request forwarding is not performed.
+
+=== New Default Hostname provider
+
+The request and fixed hostname providers have been replaced with a new default hostname provider. The request and fixed hostname providers are now deprecated and we recommend that you switch to the default hostname provider as soon as possible.
+
+=== Deprecated or removed features
+
+Certain features have a change in status.
+
+==== Deprecated methods in token representation Java classes
+
+In the year 2038, an int is no longer able to hold the value of seconds since 1970, as such we are working on updating these to long values. In token representation there is a further issue.  An int will by default result in 0 in the JSON representation, while it should not be included.
+
+See the link:{apidocs_javadocs_link}[{apidocs_javadocs_name}] for further details on exact methods that have been deprecated and replacement methods.
+
+==== Uploading scripts
+
+Upload of scripts through admin rest endpoints/console is deprecated. It will be removed at a future release.
+
+=== Authorization Services Drools Policy
+
+The Authorization Services Drools Policy has been removed.
+

upgrading/topics/rhsso/changes.adoc

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