Web Services changes

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

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.

New Genero Web Services JSON library for working with JSON

Starting with FGLGWS 5.00, the Genero Web Services JSON library (json) has been added. This library provides classes and methods to perform:
  • JSON manipulation with a streaming API for JSON
  • Serialization of BDL variables in JSON

The json library provides an API with three classes: JSONWriter, JSONReader, and Serializer to stream JSON over HTTP.

Where before you may have used the JSON utility API (util.JSON,util.JSONObject,util.JSONArray) classes to perform JSON manipulation, the new json package provides an alternative. By contrast with the JSON utility API, the new json library does not load a JSON file into memory, but instead streams and serializes data over the network on the fly. This streaming method improves communication and performance, particularly when large JSON files need to be handled.

Tools that process JSON also use the new json class. The fglrestful tool has been enhanced to take advantage of the streaming methods of the new json class to generate code in the stub file.

For more information, go to The json package.

Changes to how WSRetCode attribute handles return status

Starting with FGLGWS 5.00, the high-level REST API attribute WSRetCode can be set to support the Swagger and OpenAPI specification for the "2XX" value, which is a specific code that can be set in the WSRetCode attribute. This specific code means that the REST web service can return any HTTP response status value from 200 to 299 dynamically at runtime.

In earlier versions you could only set an explicit return code in the function declaration. From version 5.00 onwards, the GWS supports both the older method and the new method using the 2XX value. For more information and examples using the attribute, see SetRestStatus and WSRetCode.

WSDescription attribute can be used on JSON schemas

Starting with FGLGWS 5.00, the high-level REST API attribute WSDescription can be used in user-defined BDL types in addition to REST function input and output parameters, added to support the use of JSON schemas in the Swagger and OpenAPI specification.

In earlier versions you could only set this attribute on REST function input and output parameters. From version 5.00 onwards, you can use the attribute in user-defined type with data types that use an ATTRIBUTES() clause. You can set the WSDescription attribute on type members to specify metadata information. For more information and examples using the attribute, see WSDescription

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.

New security.global.verifyserver entry in FGLPROFILE to support certificate validation process

Starting from 5.00.00, it is now possible to turn off certificate validation for requests for applications or services once the server has been validated.

This feature is intended for development purposes only; it allows you to disable the mechanism that checks the chain of trust for a certificate. To do this, set the FGLPROFILE security.global.verifyserver property to FALSE, which turns off certificate validation when requests are made for applications or services run with the HTTPS protocol.

For details, go to Security Configuration FGLPROFILE entries.

fglrestful oauth option changes

Starting with FGLGWS 5.00, the fglrestful tool --oauth option has just two settings ("yes" or "no") to specify if OAuth specification should be generated or not.

For more details, go to fglrestful.

New method GetIdRoles() for retrieving authorization roles

Starting from FGLGWS 5.00, the OAUTH API has a new method called OAuthAPI.GetIdRoles() to explicitly retrieve authorization roles.

Where previously you used OAuthAPI.GetIdScopes() to retrieve both the list of scopes and roles from an ID or access token provided by an Identity provider using OAuth2 Single sign-on, you now need to use the dedicated method to retrieve roles.

For details, go to OAuthAPI.GetIdRoles.

OpenIDConnect service supports OIDC_ROLES

Starting from FGLGWS 5.00, the Genero OpenIDConnect service now decodes ID tokens containing roles instead of scopes, and creates a new environment variable called OIDC_ROLES containing the list of roles.

Where previously you used OIDC_SCOPES to retrieve both the list of scopes and roles from an ID or access token provided by an Identity provider using OpenID Connect/OAuth2 Single sign-on, you now need to use the dedicated variable to retrieve roles.

For an example using OIDC_ROLES, refer to Retrieve roles and scopes in the Single Sign-On User Guide.

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.

The GeneroAccessService supports scopes set in configuration file

Starting from FGLGWS 5.00.02, the GeneroAccessService service can now secure web services from scopes set in the configuration file (xcf).

No action needs to be taken on your part, but if you want to secure legacy REST web services that do not define any WSScope attributes or that are written with the REST low-level API, then you can secure them by configuring the SCOPE element in the configuration file. The GeneroAccessService will verify if the access token provided by the client application has all the necessary scopes specified in the SCOPE element.

For more information about Single sign-on and the GIP, refer to the Single Sign-On User Guide. For more information about configuring scopes, refer to the SCOPE (for service) topic in the Genero Application Server User Guide.

fglwsdl oauth option added

Starting from FGLGWS 5.00.03, the fglwsdl tool --oauth option can be used to generate OAuth specification in the SOAP service call. The stub is generated with the IMPORT FGL OAuthAPI and requests use the OAuthAPI.CreateHTTPAuthorizationRequest() method to take the access token into account.

For more details, go to fglwsdl.

New OAuthAPI methods to use with SSO authentication for mobile apps accessing web services

Starting from FGLGWS 5.00.03, the OAuthAPI has two new dedicated methods for working with mobile apps accessing web services:
  1. First, you call the OAuthAPI.RetrievePasswordTokenForNativeApp(), using the client app’s client and secret credentials and the user credentials to get an access token, a refresh token, and the access token expiration date from the IdP. These must be stored in the OpenIdCResponseType record.
  2. When you call OAuthAPI.InitNativeApp() to initiate access to the web service, the OpenIdCResponseType record is passed in to refresh the token (when needed) without having to restart the application.

Where previously you used OAuthAPI.InitService() before calling any of the OAuthAPI methods, such as CreateHTTPAuthorizationRequest, to perform requests to the service, now you call OAuthAPI.RetrievePasswordTokenForNativeApp() and OAuthAPI.InitNativeApp() methods instead.

For details, go to OAuthAPI.RetrievePasswordTokenForNativeApp and OAuthAPI.InitNativeApp.

Using an identity provider's registration endpoint

Starting from FGLGWS 5.00.03, there are updates to how you manage and use the registration endpoint of an identity provider using the OpenID Connect/OAuth2 Single sign-on protocol.

If you have an application that is protected by an identity provider via OpenIDConnectServiceProvider and a registration endpoint has been set:
  • You can view the identity provider's registration endpoint using the ImportOAuth tool's --show option.
  • At runtime, an environment variable called OIDC_REGISTRATION_ENDPOINT will be available, and you can load it in your Genero application via fgl_getenv("OIDC_REGISTRATION_ENDPOINT"). For example, you might want to register or unregister an application with the identity provider. A valid access token is required to perform this procedure.

For more information about Single sign-on and managing registration endpoints, refer to the ImportOAuth page in the Single Sign-On User Guide.

New json.Serializer method for handling null values

Starting from FGLGWS 5.00.03, json.Serializer has a global option, allowNullAsDefault, to allow NULL values to be accepted during deserialization even if the JSON type is not explicitly specified. By default, allowNullAsDefault is 0.

Where previously you did not have an option to allow null values, you now can use the two new methods json.Serializer.setOption and json.Serializer.getOption to set options and retrieve values.

For details, go to Serializer options and json.Serializer methods.

Using the json_null="null" attribute with fglrestful

Starting from FGLGWS 5.00.03, the GWS uses json.Serializer for serialization/deserialization, which conforms to how nulls are handled in OpenAPI 3.0. A deserialization error is generated if "null" values ​​are passed without the json_null="null" attribute being explicitly set on BDL variable that allow nulls. The JSON OpenAPI documentation generated by fglrestful will represent json_null="null" using the nullable: true property.

For examples, go to Primitive and complex types with null values.

To learn more about the OpenAPI specification, refer to the OpenAPI documentation.

Summary of changes in JSON streaming from GWS v4 to v5

The classes util.JSON and GWS JSON API serve different purposes.

The util.JSON API is designed to convert program variable values to/from JSON data, similar to JSON handling in Python or JavaScript. util.json is more flexible and focuses on producing JSON output without strict adherence to schema rules.

The GWS JSON API is designed for streaming. Its json.Serializer class follows the rules of JSON Schema, and more specifically, the OpenAPI specification. Therefore, this API must ensure that the serialization of data is compliant with these standards, and that deserialization also follows the defined rules.

Table 1 summarizes the changes to the OpenAPI specification that may affect how you handle null values when migrating from version FGLGWS v4.01 to version FGLGWS v5.00 of the streaming class.

Table 1. Migration from GWS v4 to v5
Feature FGLGWS v4.01 FGLGWS v5.00 From FGLGWS 5.00.03
Serialization/deserialization of null values GWS used util.JSON for serialization util.JSON.parse() accepts null values for all types. The GWS uses json.Serializer, which conforms to how nulls are handled in OpenAPI 3.0.

json.Serializer will generate a deserialization error if "null" values ​​are passed without the json_null="null" attribute being explicitly set. This applies to:

  • complex types (object and array) from v5.00.00
  • primitive types (boolean, string, integer, and so on) from v5.00.03
  • json.Serializer.setOption and json.Serializer.getOption are added to change the serialization/deserialization rules (making it more relaxed)
  • allowNullAsDefault option is added to accept NULL values ​​by default even when no json_null="null" attribute is set.
  • fglrestful is enhanced to take json_null attribute and generate the "nullable" keyword in the OpenAPI documentation.
  • fglrestful is enhanced to generate json_null="null" when detecting the nullable : true keyword in JSON schemas.

Where before the GWS used util.JSON for serialization, now it uses json.Serializer. Therefore, you may need to review your code, setting the json_null="null" attribute on BDL variables to allow null values. Alternatively, you can set the allowNullAsDefault option to specify the default behavior for nulls even when there is no json_null="null" attribute set.

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.01.

Notable changes introduced in maintenance releases:
  • No particular change to consider.