Web Services changes

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.

New Genero Web Services JSON library for working with 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

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.

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.