GAS 4.01 upgrade guide

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

Important:

This incremental upgrade guide covers only topics related to the Genero Application Server (GAS) 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: GAS 4.01 new features.

Previous upgrade guide: GAS 4.00 upgrade guide

Session idle time

The gasadmin session --idle-time option is introduced to provide information on a session's idle state. It gives you the number of seconds since last user activity on applications running in a session. Based on this, you can, for example, decide if a session can be stopped. For more information on using this feature, see Example: Idle session.

Gasadmin commands --dispatcher option no longer available

The --dispatcher option is no longer provided with these commands:
  • gasadmin reset-log
  • gasadmin session

Where before you may have needed to use the -d option to specify the dispatcher, for example to close a session:

gasadmin session --close-session d98290172c8f7c0d861db329f1ce6597 -f as1.xcf 
          -d isapidispatch
You must now omit the -d option:
gasadmin session --close-session d98290172c8f7c0d861db329f1ce6597 -f as1.xcf
The command is run on the admin port (TCP_ADMIN_PORT) used by the dispatcher for this purpose. With the option -f you can specify the configuration file where the port is set; otherwise, the default GAS configuration file is used. In the example the as1.xcf contains the admin port used by the dispatcher, so the gasadmin uses the port to connect to the dispatcher to close the session.
The gasadmin session --whoami option is introduced to provide information on the dispatcher. 
gasadmin session --whoami -f as1.xcf
This command will return the kind of dispatcher you are communicating with: httpdispatch, fastcgidispatch, or isapidispatch.

See gasadmin tool.

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

Starting from GAS 4.01.02 and FGLGWS 4.01.02, 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.

Changes to how messages are sent to connected users

Starting with GAS version 4.01.02, the gasadmin session --broadcast-message is desupported. This command now displays a message to use the gasadmin send-message command instead, and it exits with a status code of 1.

The gasadmin send-message command provides enhanced functionality that allows an administrator of the GAS to send messages to connected users on the specified applications and sessions, or to connected user on all sessions running in the GAS.

For more information see Send administrative messages to user agents.

Changes to how sessions are closed

Starting from GAS version 4.01.02, the gasadmin session --close-session and gasadmin session --close-all-sessions commands are desupported.

They are replaced by the gasadmin close-session and gasadmin close-all-sessions commands. These commands provide functionality that allow an administrator of the GAS to close specified applications and sessions, or to close all sessions running in the GAS gracefully. The commands also have options to send a message or an end URL to the user agents on closing the sessions.

For more information see gasadmin.

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

Starting from FGLGWS 4.01.04 and GAS 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.

Argument added to gasadmin gar --list-archives command

Starting from GAS 3.21.02, GAS 4.01.07, and GAS 5.00.02, the gasadmin gar --list-archives command is enhanced to take an argument with options to display information for the deployed archives you specify. Previous to this, the command displayed information for all archives deployed on the GAS.

For more information see gasadmin.

Argument added to gasadmin gar --clean-archives command

Starting from GAS 3.21.02, GAS 4.01.07, and GAS 5.00.02, the gasadmin gar --clean-archives command is enhanced to take an argument with options to specify the undeployed archives you want removed. Previous to this, the command cleaned/removed all undeployed archives on the GAS.

For more information see gasadmin.

Changes to gasadmin gar --list-archives command output

Starting from GAS 3.21.02, GAS 4.01.07, and GAS 5.00.02, the gasadmin gar --list-archives command has enhancements to the output listing applications and services available in the GAS. The layout of the display has been improved for better readability.

For more information, go to List deployed archives.

Changes to the OpenIDConnect service configuration

Starting from GAS and FGLGWS versions 3.21.02, 4.01.07, and 5.00.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 option to list session ids in the gasadmin session command

Starting from GAS 3.21.02, GAS 4.01.07, and GAS 5.00.02, the gasadmin session command has been enhanced with an option, --list-session-ids, to output just a list of identifiers of the active sessions. No proxy details are output, such as the names of the applications or services, as in the output from the gasadmin session --list-sessions command.

For more information on gasadmin session commands and examples, go to gasadmin.

New option to count sessions in the gasadmin session command

Starting from GAS 3.21.02, GAS 4.01.07, and GAS 5.00.02, the gasadmin session command has been enhanced with an option, --count-sessions, to return a count of the number of active sessions (applications and services).

For more information on gasadmin session commands and examples, go to gasadmin.

Changes to the IIS server configuration for authentication

Starting from GAS 3.21.02, GAS 4.01.07, and GAS 5.00.02, it is recommended that you set the Manage Pipeline mode application pool setting to "Integrated" instead of "Classic". Where previously you used "classic", and now your application relies on an authentication token passed from IIS to the runtime, you may find this process breaks your application. This is due to the new architecture in IIS (introduced in IIS 7), which works in an integrated way with different IIS modules.

By setting to "Integrated", now the IIS will switch context to whatever IIS and ASP.NET modules it needs to call to handle application requests. However, be sure to test your existing applications for compatibility in Integrated mode before upgrading application pools in a production environment to Integrated mode.

For more information on IIS configuration, go to Create application pool. For more information on Microsoft® recommendations for use of integrated mode, refer to Learn IIS.

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, see GAS 4.00 upgrade guide.

Notable changes introduced in maintenance releases:

  • The change to gasadmin session --list command to display fglrun processes started in the current session, and the change to the gasadmin --version command to include the date and time the GAS package was built. These changes are also available since GAS 4.01.01.
  • The support for HTTP/2 when you configure your web server to use the HTTP/2 protocol, also available since GAS 4.01.00.
  • The deprecation of SPDY which is replaced by the HTTP/2 protocol.
  • How the USER_AGENT timeout value is halved when sent to the Genero Browser Client, also available since GAS 4.01.00.
  • The new entry oidc.app.start.mode for setting the OpenID Connect service application starting mode, also available in GAS 4.01.00 and FGLGWS 4.01.00.
    Important:

    With GAS 4.01.00 and FGLGWS 4.01.00, the default starting mode changes from "cookie" to "gnonce".