Web Services changes

Security note: OpenSSL 3.0 LTS support

Starting with FGLGWS 3.10.23, 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, 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.

New Genero Web Services JSON library (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 API (util.JSON) methods to perform JSON manipulation, the new json class by contrast does not load a JSON file into memory, but instead streams and serializes JSON 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. For example, 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

The JSONOneOf and JSONSelector attributes replace JSONSchemaOneOf and JSONSchemaSelector

Starting from FGLGWS 5.00, the high-level REST API attributes JSONOneOf and JSONSelector can be used to validate against different JSON schemas in the OpenAPI document of a REST web service.

These attributes rename the existing attributes JSONSchemaOneOf and JSONSchemaSelector. If you have previously used JSONSchemaOneOf and JSONSchemaSelector and you want to use the new attributes, ensure you are using FGLGWS 5.00 or greater.

For details, go to JSONOneOf and JSONSelector.

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.

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.

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

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.