Web Services changes

There are changes in support of web services in Genero 4.01.

Security note: OpenSSL 3.0 LTS support

Starting with FGLGWS 3.21.01, 4.01.05 and 5.00.00, OpenSSL 3.0 LTS is required for encryption and security.

Because OpenSSL 1.1.1 goes EOL in September 2023 (external link), it is now mandatory to use OpenSSL 3.0 LTS to get the latest security fixes.

When installing an FGLGWS package, OpenSSL 3.0 libs will be provided in FGLDIR, if no OpenSSL 3.0 exists on the system.

Starting with OpenSSL 3.0, the SHA-1 digest algorithm is no longer supported by default. The OpenSSL 3.0 libs provided in FGLDIR still have SHA-1 digest activated by default. If you want to enable SHA-1 with the system OpenSSL 3.0 libs, use a command such as update-crypto-policies --set DEFAULT:SHA1 in order to use SHA-1. However, the SHA-1 digest algorithm is no longer recommended, because it is increasingly vulnerable as computers become more and more powerful. If you are using SHA-1 with GWS crypto APIs, consider moving to SHA-256 or to a stronger secure hash algorithm.

See GWS Security for more details about security and encryption with GWS.

Get OpenSSL from third-party vendors for Windows

OpenSSL libraries are provided in the FGLGWS package; however, starting with FGLGWS 3.21.03, 4.01.08 and 5.00.03 if you want to install more recent OpenSSL libraries from third-party vendors, you must do the following on your Windows® system:
  • Go to an official OpenSSL library vendor. OpenSSL recommends Shining Light Productions (external link) for OpenSSL libraries for Windows.
  • Download the OpenSSL libraries from there.
  • By default, GWS will look for the OpenSSL libraries in the $FGLDIR\bin directory unless you have also specified OPENSSL_MODULES to look in another path. Copy the following libraries into your $FGLDIR\bin directory.
    • libcrypto-3-x64.dll
    • libssl-3-x64.dll
    • legacy.dll
  • Verify that the installation has worked by running the command fglpass -Vssl; it should return the version of the OpenSSL libraries.

See GWS Security for more details about security and encryption with GWS.

Security Note: sameSite HTTP cookie attribute

When using HTTP cookies, make sure to check the sameSite attribute usage.

For more details, see Changes to how GWS handles cookies and Single sign-on (OpenID Connect, SAML, and GIP) sameSite security.

fglrestful network options to support proxy and HTTP authentication

Starting with FGLGWS 4.01, the fglrestful tool supports new network options. Log in and password options have been added for proxy and/or HTTP authentication when using the tool to request OpenAPI documentation on the network.

For more details, see fglrestful.

WSParam and WSQuery support complex types

Starting with FGLGWS 4.01, the high-level REST API attributes WSParam and WSQuery can be set on parameters defined as records or arrays. For example, in earlier versions you could only set these attributes on primitive Genero BDL types, such as STRING or INTEGER. From version 4.01.00, onwards the GWS supports serialization of records and arrays based on the default OpenAPI specification for serialization. For more information and examples using record and arrays as parameters, see WSParam and WSQuery.

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

From 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 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 OpenIDConnectServiceProvider.xcf and the GeneroAccessService.xcf delivered in the Genero Web Services package under $FGLDIR/web_utilities/services use FGLGWS 4.01.02 or higher. The OpenIDConnectService and GeneroAccessService services have been enhanced to handle both the old and new methods for exchanging scopes.

For more information about GIP, see the Genero Application Server User Guide.

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

From FGLGWS 4.01.04 onwards, the GWS 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 the Retrieve roles and scopes page in the Genero Application Server User Guide.

New security.global.options entry in FGLPROFILE to allow legacy OpenSSL 1 options

Starting from FGLGWS 3.21.02, 4.01.06, and 5.00.00, it is now mandatory to use OpenSSL 3.0 LTS to get the latest security fixes. This change is due to OpenSSL 1.1.1 going EOL in September 2023 (external link).

To ease your migration from OpenSSL 1 to OpenSSL 3, the FGLPROFILE option security.global.options can be used to set OpenSSL 1 options to connect to a legacy server.

For details, go to Security Configuration FGLPROFILE entries.

New fglwsdl option -SSLOptions to support legacy OpenSSL 1 options

Starting from FGLGWS 3.21.02, 4.01.06, and 5.00.00, it is now mandatory to use OpenSSL 3.0 LTS to get the latest security fixes. This change is due to OpenSSL 1.1.1 going EOL in September 2023 (external link).

The fglwsdl tool supports the option (-SSLOptions) to set OpenSSL 1 options when connecting to a legacy server.

For more details, go to fglwsdl.

Change to OAuthAPI.GetIDSubject returns

Starting from FGLGWS 3.21.02 and 4.01.06, the OAuthAPI.GetIDSubject function returns the subject identifier of an ID token in a string instead of an integer.

If you have previously used the function, review your code and ensure that the variable that affects the return value is of type STRING.

For details, go to OAuthAPI.GetIDSubject.

New security.global.certificate.selfsigned.preload entry in FGLPROFILE

Starting from FGLGWS 3.21.02, 4.01.07, and 5.00.02, there is an option to preload the global self-signed certificate and private key used for HTTPS connections. Typically, the certificate and key is loaded at the first HTTPS request. If you find the GWS computation of the certificate and key takes too long, you can speed things up by setting the security.global.certificate.selfsigned.preload = TRUE to preload the certificate and key at the start of the application instead of at the first HTTPS connection.

For more information on web service security configuration, go to Security Configuration FGLPROFILE entries.

Changes to the OpenIDConnect service configuration

Starting from FGLGWS 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, refer to the 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 Web services changes in BDL 4.00.

Notable changes introduced in maintenance releases: