GAS 3.20 upgrade guide

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

Important:

This version of GAS is desupported, use a more recent version of the product.

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 3.20 new features.

Previous upgrade guide: GAS 3.10 upgrade guide

TCP_ADMIN_PORT provides a port for GAS administration tasks

TCP_ADMIN_PORT is a new element in the GAS configuration file. If your GAS version is 3.20.07 or later, you need to be aware of this new element. It provides a port for GAS administration tasks. If you are using an as.xcf without this element, there is no need to add it. The default TCP admin port is set internally to 6999. If you need to set the port, you may need to add the element to the as.xcf.

It is necessary to set this port, for example, if you have several GAS running on the same machine. Then you need to ensure that you set a unique port for each GAS. Also ensure you select a different port to that used for application access. For more information on configuring multiple dispatchers for TCP admin port, see Configure multiple dispatchers.

GBC in application path

The means to provide a Genero Browser Client (GBC) in the application path is introduced. See Provide the GBC in the application path.

With 3.20, you can package a GBC in the gbc directory of the application path. This is the path specified by the PATH element in the application xcf file. The GAS first looks for the GBC in APPDIR/gbc. If this directory exists and it contains a GBC installation, this GBC is used. If the gbc directory is not set, the GAS then uses the standard GBC_LOOKUP_PATH lookup mechanism.

What does this mean for your upgrade to 3.20? It allows you to provide a GBC to use in the application path's gbc directory independent of the GAS configuration.

Deployment portal has been replaced with Deployment App

The legacy deployment portal service has been replaced with the Deployment App (DeploymentApp). If you used the deployment portal to deploy and manage your applications and GBC clients, you will need to move to using this application. For information on how to access and use it, see Deploying and securing applications and Web services page in Single Sign-On User Guide.

Changes to the deployment service under GIP

The deployment service is now protected by Genero Identity Provider (GIP) pages in Single Sign-On User Guide. To access it requires a valid access token with the scope "deployment". The service URL has changed too. If you previously used the deployment service on the GAS at base URL /ws/r/services/DeploymentService to manage your Genero applications, you will need to use this new URL, /ws/r/admin/GeneroDeploymentService instead. For more information on how to access and use it, see Deploying and securing applications and Web services page in Single Sign-On User Guide.

Changes to ImportOAuth tool for getopt support

The ImportOAuth tool command supports getopt parsing of its command-line arguments. The use of the tool has therefore changed for GAS 3.20.06. Command options are specified with double dash (--) instead of single dash (-), and the URL of the IdP is no longer placed after the import option but instead must be placed at the end after the profile endpoint.

For example, in GAS 3.10 and earlier, the syntax for ImportOAuth was:

fglrun ImportOAuth -import IdP_URL  
         -authz IdP_oauth_authorize_endpoint 
         -token IdP_oauth_access_token_endpoint 
         -logout IdP_logout_endpoint 
         -profile IdP_user_profile_endpoint

From GAS 3.20.06, the syntax for ImportOAuth is:

fglrun ImportOAuth --import 
        --authz IdP_oauth_authorize_endpoint 
        --token IdP_oauth_access_token_endpoint 
        --logout IdP_logout_endpoint 
        --profile IdP_user_profile_endpoint
        IdP_URL

For help using the tool, run the command:

fglrun ImportOAuth -h

For further details about the ImportOAuth command, see The ImportOAuth program page in Single Sign-On User Guide.

ImportOAuth keys option

Starting with GAS version 3.20.14, the ImportOAuth command includes the --keys option.

If you are using ImportOAuth to register tokens and endpoints for OAuth authentication from an identity provider such as Instagram or Facebook, it is recommended to specify the option --keys to fetch the endpoint for the public key to validate ID tokens. It is recommended to include the --keys option to avoid access errors to Genero applications.

For more information on the OpenID Connect service tool ImportOAuth, see The ImportOAuth program page in Single Sign-On User Guide.

Changes to ImportIdP tool for getopt support

The ImportIdP tool command supports getopt parsing of its command-line arguments. The use of the tool has therefore changed. The command option is specified with double dash (--) instead of single dash (-).

For example, in GAS 3.10 and earlier, the syntax for ImportIdP was:

fglrun ImportIdP -import SAML_IdP_url

From GAS 3.20.06, the syntax for ImportIdP is:

fglrun ImportIdP --import SAML_IdP_url

For help using the tool, run the command:

fglrun ImportIdP -h

For further details about the ImportIdP command, see The ImportIdP program page in Single Sign-On User Guide.

Filenames with locale-specific characters supported in file transfer

Starting with FGLGWS 3.20.11 and GAS 3.20.13 there is full support for file transfer with filenames set on any locale. This update allows you to specify filenames with locale-specific characters in your application file transfers.

Important:

Apache

If you have configured mod_proxy_fcgi in your Apache server, ensure application URLs are not escaped by setting proxy-fcgi-pathinfo=unescape. For more details, see Configure FastCGI for Apache 2.4.

If you are using any older combinations of FGLGWS and GAS, file transfer only works for filenames with ASCII characters.

Enhancement for GIP command line tools

Starting with FGLGWS version 3.20.11, GAS version 3.20.14, and GIP version 1.00.11 there are changes to how you use commands:

GetToken
DeployGar
DeployGbc

For more information about the commands, see the Single Sign-On User Guide. These commands are now run from a script. For example, if previously you ran the "GetToken" command as:

fglrun $FGLDIR/web_utilities/services/gip/bin/gettoken/GetToken.42r client_credentials --help

You can now run it directly as:

GetToken client_credentials --help

GetToken is located in $FGLDIR/web_utilities/services/gip/bin/gettoken. DeployGar and DeployGbc are located in the $FGLDIR/web_utilities/services/gip/bin/deploy directory. You need to include these paths in your PATH environment variable to run the commands from any directory.

Tip:

Run the script file $FGLDIR/web_utilities/services/gip/envidp.sh to ensure the PATH is set correctly to run the commands.

OpenID Connect service Oauth exchange format definition

Starting with GAS version 3.20.14 and FGLGWS 3.20.14, you can configure the OpenID Connect service provided in the GWS to perform the exchange of OAuth authentication in url-encoded (default) format or JSON.

You can set the entry oidc.oauth.request.format in the configuration file located in $FGLDIR/web_utilities/services/openid-connect/res/configuration to ensure the service exchanges tokens in the format required by the identity provider.

Note:

This applies only when using the OpenID Connect service (provided in GWS as OpenIDConnectServiceProvider.xcf) performing OAuth authentication with identity providers for Genero applications. This does not apply if you are using an identity provider supporting the OpenID Connect authentication protocol.

For more information see Set exchange format for OAuth ID token page in Single Sign-On User Guide.

OpenID Connect service application starting mode

Starting with GAS 3.20.14 and FGLGWS 3.20.14, you can configure the mode OpenID Connect service will use to verify the identity of a client before starting an application. The OpenID Connect service is provided as part of the GWS package.

To change the default mode, set the entry oidc.app.start.mode in the OpenID Connect service configuration file to use either a cookie or "gnonce" (genero number once). The configuration file is located at $FGLDIR/web_utilities/services/openid-connect/res/configuration.

For more information on configuring the application starting mode, see Configure application starting mode page in Single Sign-On User Guide.

SPDY deprecated

This protocol is now deprecated. The HTTP/2 protocol, which is derived from the SPDY protocol, replaces it. If you have used SPDY prior to this, it is recommended to configure your web server to use the HTTP/2 protocol instead. For more information on working with HTTP/2, see Apache: Configure for HTTP/2 or IIS: Configure for HTTP/2.

HTTP/2 upgrade

Starting with GAS version 3.20.18, we recommend you configure your web server to use the HTTP/2 protocol. Most major browsers now support HTTP/2. When configuring your web server, allow the client browser to define the preferred protocol; this will allow the GAS to work with services that may not need the HTTP/2 protocol. For more information on working with HTTP/2, see Apache: Configure for HTTP/2 or IIS: Configure for HTTP/2.

Changes to gasadmin --list command to display pids

Starting with GAS version 3.20.19, the gasadmin session --list command is enhanced to display a list of fglrun processes ids started in the current session by the uaproxy or gwsproxy. Also the gasadmin --version command now includes the date and time of when the GAS package was built.

For more information see gasadmin tool.

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

Starting at GAS 3.20.20 and FGLGWS 3.20.17, 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 3.20.17, 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 3.20.17 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 in Single Sign-On 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, see GAS 3.10 upgrade guide.

Notable changes introduced in maintenance releases:

The change in the default value for REQUEST_RESULT from 60 seconds to 45 seconds.
The change in the SESSION_COOKIE definition to include the SameSite attribute.
The recommendation to set the attribute SameSite to "strict" in web services using HTTP cookies, also available since GAS 3.20.13.
How the USER_AGENT timeout value is halved when sent to the Genero Browser Client, also available since GAS 3.20.09.
The removal of the Alias directive in Apache 2.4 Web server and other changes introduced in the configuration.