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
- 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, go to 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, go to 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, go to 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, refer to 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, refer to 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_hintparameter, used in the logout request sent to the provider, has been replaced byoidc.logout.identifier. The new parameter supports the values "id_token_hint", "client_id", or anempty(" ") value. The default value is "id_token_hint". - The
oidc.logout.post_redirectparameter, 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.
Discontinued support for OCSP
We are discontinuing support for the Online Certificate Status Protocol (OCSP) due to the decision by several Certificate Authorities to phase out support for this protocol in web services. However, please note that the OCSP functionality will remain intact within our product, allowing you to continue using this feature as part of your secure communications.
For more information on OCSP, go to Enable OCSP.
Restored HandleRequest() behavior for root-level query-only requests
The behavior of com.WebServiceEngine.HandleRequest() for root‑level, query‑only requests has been restored to match versions prior to 5.01.02 and 4.01.09. The sequence of changes is as follows:
| Version | Behavior |
|---|---|
| Before v5.01.02 and v4.01.09 | Query‑only requests to the REST service root path (for example,
/service?abc) were treated as non‑REST and fell back to low‑level handling (status
1). |
| v5.01.02 and v4.01.09 | These requests were interpreted as REST requests. Because no operation exists on the service
root path, the engine returned error −35 instead of using the low‑level
handler. |
| Now with v4.01.11, v5.01.06, and v6.00.02 | The previous fallback behavior has been restored. Root‑level query‑only requests again fall back to low‑level handling when no REST operation matches. |
This restoration ensures compatibility with existing applications that depend on low‑level handling of root‑level query‑only requests.
For more details and examples, go to com.WebServiceEngine.HandleRequest
Improved communication protocol between GAS and GWS
The communication protocol between the Genero Application Server (GAS)
and the Genero Web Service (GWS) processes has been updated to improve reliability, specifically to
ensure that no connections are lost when the GWS process needs extra time to stop or restart. Prior
to this update, if the GWS process needed time to stop, connections could be lost or requests could
be sent before the service was ready. The protocol was enhanced so that gwsproxy
now ensures fglrun is ready to receive the next request before proceeding.
To ensure you are using this improved communication protocol between the GAS and your GWS applications, ensure you are using the following version pairs (or greater):
-
FGLGWS 4.01.11 and GAS 4.01.08
Response body allowed on a PATCH operation
Starting from FGLGWS 4.01.11, a WSPatch operation can declare a response
body.
Where previously the compiler rejected a PATCH function whose return value was not a header, raising error -9129, that function now compiles.
Existing code needs no change. A PATCH function that returns its values as headers with the WSHeader attribute continues to work.
For details, go to HTTP verbs and attributes.
External DTD of XML request and response bodies
Starting from FGLGWS 4.01.11, the web services engine no longer fetches the external document type definition (DTD), or any other external entity, of an XML request or response body that it parses.
This change improves security by preventing XML external entity
processing, which could cause the server to fetch from a network address or a file on the server.
This applies to SOAP and REST services and clients, and to the com methods that read
an XML body, such as com.HttpServiceRequest.readXmlRequest and com.HttpServiceRequest.beginXmlRequest.
The engine now ignores the external DTD and the external parameter entities of a body, without
raising an error. The attribute default values declared there no longer apply. If the body
references an entity that only the external DTD declares, the engine either replaces the reference
with an empty value or fails to parse the body. On macOS and iOS with a libxml2 version older than 2.13, the attribute default values
declared inside the body's <!DOCTYPE> no longer apply either.
After upgrading, review any service or client whose XML bodies rely on an external DTD.
For details, go to DomDocument Features and StaxReader Features.
load-external-dtd feature of the XML classes
Starting from FGLGWS 4.01.11, the xml.DomDocument and
xml.StaxReader classes have a load-external-dtd feature, which
defines whether a parse fetches the external DTD of a document.
The feature is TRUE by default, so existing
programs fetch external DTDs as before.
An xml.DomDocument that sets enable-html-compliancy to TRUE, then
back to FALSE before loading XML, now follows the load-external-dtd feature like any
other document. Previously, it fetched the external DTD without applying its attribute default
values.
After upgrading, review any program that parses XML from a source that you do not control, such as a
response from a third party or a file that a user uploads, and set load-external-dtd
to FALSE for those documents.
For details, go to DomDocument Features and StaxReader Features.
Changes to how GWS handles an invalid HTTP request
Starting from FGLGWS 4.01.11, when a Web Services server application receives a request that is not valid HTTP, the server responds to the client with an HTTP error status, and the application keeps running.
Where previously such a request put the server into an invalid
state, and every later call failed with the same error, the application now goes on processing
requests.
For such a request, com.WebServiceEngine.ProcessServices() and
com.WebServiceEngine.HandleRequest() return status -5
instead of -8.
com.WebServiceEngine.GetHTTPServiceRequest() still raises error -15565.
After upgrading, review any request loop that tests for -8, and handle -5 there.
For details, go to com.WebServiceEngine.ProcessServices.
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, go to Web services changes in BDL 4.00.
- Support for validating filenames in WSAttachments. The high-level REST
WSAttachmentattribute has an option to verify filenames in received files using a regular expression pattern, also available in FGLGWS 4.01.00. - Changes to default IP version used by a GWS client. The default IP version is now IPv4, also available in FGLGWS 4.01.00.
- fglwsdl -xmlname option added to generate variables named with XMLName, also available in FGLGWS 4.01.00.
- Dynamic loading of zlib library for data compression, also available in FGLGWS 4.01.03.