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.

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.