SSO 4.01 upgrade guide

These topics describe product changes you must be aware of when upgrading to version 4.01.

Important:

This is an incremental upgrade guide that covers only topics related to the Single sign-on version specified in the page title. Check prior upgrade guides if you migrate from an earlier version, and complete the migration tasks for all versions between your existing version and the target version in order. Make sure to also read about the new features for this version.

Corresponding new features page: SSO 4.01 new features.

Previous upgrade guides with single sign-on information can be found in the Genero Application Server User Guide.

Support for RFC 8693 in the Genero Identity Provider (GIP) creation of OAuth ID and access tokens with scopes

Starting with FGLGWS 4.01.02 onwards, the GIP follows the standard RFC 8693 as the default method when creating OAuth ID and access tokens with the scope parameter.

Prior to FGLGWS 4.01.02, GIP created a JSON Web Token (JWT) with a "scopes" element defined as a JSON array for the list of scopes. Now, according to the RFC 8693 standard, the JWT has a "scope" element defined as a string with the scopes in a space-separated list.

No action needs to be taken on your part, but if you have previously used the GIP to authenticate users launching applications and you want to use the new scope member, ensure that the OpenID Connect service provided as part of the GWS package uses FGLGWS 4.01.02 or higher.

To change the default mode to the old method for exchanging scopes, set the IDP specification entry in fglprofile to oidc.token.scopes=false.

For more information about GIP, see the Genero Identity Provider (GIP) pages.

New option oidc.accesstoken.decode for decoding access tokens with roles and scopes

Starting with FGLGWS 4.01.04 onwards, the FGLGWS OpenID Connect service configuration provides a new oidc.accesstoken.decode option in file $FGLDIR/web_utilities/services/openid-connect/res/configuration; to be used when configuring Single sign-on, in order to decode roles and scopes sent by identity providers in the access token.

To ensure that all roles and scopes are retrieved, you need to configure for the decoding of the access token by setting the option oidc.accesstoken.decode=true (default is false):

For more information, see Retrieve roles and scopes.

Changes to the OpenIDConnect service configuration

Starting from FGLGWS 5.00.02, 4.01.07, and 3.21.02, two parameters of the Genero OpenIDConnect service configuration ($FGLDIR\web_utilities\services\openid-connect\res\configuration) have changes:

  • The oidc.logout.id_token_hint parameter, used in the logout request sent to the provider, has been replaced by oidc.logout.identifier. The new parameter supports the values "id_token_hint", "client_id", or an empty (" ") value. The default value is "id_token_hint".
  • The oidc.logout.post_redirect parameter, used to send the post redirect uri in the logout request, now needs a string value instead of the boolean value true/false on previous versions. The default value is now "post_logout_redirect_uri".

No action needs to be taken on your part, but if you have previously used a custom OpenIDConnect configuration file and you want to use it when upgrading FGLGWS version, ensure that you review your configuration for these parameters.

For more information on OpenID Connect Single sign-on, go to OpenID Connect/OAuth2 SSO.

New resource added for GIP StarterApp access

Starting with FGLGWS versions 4.01.10, and 3.21.04, you can update the res.gip.access.control resource from NOBODY to ALL to grant access to the StarterApp for its initial launch. This resource is defined in the GAS configuration file (as.xcf).

After setting up the GIP, remember to reset the resource back to NOBODY to restrict access and prevent users from rerunning the StarterApp. In production, ensure that the resource is also set to NOBODY for the same reason.

For more details about methods to configure access for the StarterApp, go to Configure the primary Genero Identity Provider. For more information on using the resource, refer to the ACCESS_CONTROL page in the Genero Application Server User Guide.

Changes in earlier versions

Make sure to check the upgrade notes of earlier versions, to not miss changes introduced in maintenance releases. For more details, refer to the upgrade guides in the Genero Application Server User Guide.