Notes on prerequisites, fixes, and known issues for the ForgeRock® Microgateway.

Multiple OIDC Providers Can Use the Same clientID

In OpenID Connect with multiple client registrations, the same clientId can now be used for multiple registrations if if the issuer for each registration is different.

The clientId must be unique in the context of a single issuer.

In the OAuth2ClientFilter login service URI, specify both the clientId and the issuer name.

For more information, see "OAuth2ClientFilter" in the Configuration Reference and "ClientRegistration" in the Configuration Reference, "Issuer" in the Configuration Reference.

Deterministic ECDSA for JWT Signatures

When elliptic curve keys are used for signing, and Bouncy Castle is installed, by default JWTs are signed with a deterministic ECDSA. In previous releases, JWTs were signed with a non-deterministic ECDSA, which is less secure.

The new system property org.forgerock.secrets.preferdeterministicecdsa is by default true. To use the less secure algorithm, set the property to false.

JDBC Data Source Configured Independently of Container

JDBC data sources can now be set up independently of the web container configuration. In previous releases, JDBC data sources were configured at the web container level.

For more information, see JdbcDataSource in the Configuration Reference.

NoOpAuditService Provided by Default

A NoOpAuditService now provides an empty audit service to the top-level heap and its child routes. When an AuditService is not defined, there is, by default, no auditing for the configuration.

For more information, see "Default Audit Service" in the Configuration Reference and "NoOpAuditService" in the Configuration Reference.

The following improvements were introduced in this release:

ResourceException Not Logged at Error Level when AM Returns 401

Previously, if the user's SSO session had expired or become otherwise invalid and was used in a request to Microgateway, calling the AM session info endpoint to get session status would return a 401 response. This 401 response was valid but ended up being logged by Microgateway at Error level, which was misleading, and would generate a large amount of additional logging data.

Microgateway now logs an error message only when the response from an AM session info endpoint is not a 401. Microgateway still logs it as a debug message to show that it was a 401 response.

Correct Maintenance of Cookies With sameSite Flag

Cookies that arrive at Microgateway with the sameSite flag set are correctly maintained.

Ping Endpoint

A ping endpoint is available after Microgateway startup to check whether Microgateway is available. When Microgateway is installed and running as described in "Starting and Stopping the Microgateway" in the User Guide, the endpoint is at http://microgateway.example.com:8080/openig/ping.

Warning If Decoded Secret Starts or Ends in a Non-ASCII Character

Microgateway logs a warning when the decoded value of a BASE64-encoded secret starts or ends with a non-ASCII character.

If a text editor adds a carriage return to the end of a plain string value before it is encoded, non-ASCII characters can be added to the BASE64-encoded value. When the decoded value is used as part of a username/password exchange, it can then cause an authentication error.

New Functions for URL-safe and Filename-safe Encoding and Decoding

The functions encodeBase64url and decodeBase64url are added to facilitate URL-safe and filename-safe encoding and decoding.

For information, see "encodeBase64url" in the Configuration Reference and "decodeBase64url" in the Configuration Reference.

Global Log Level Configurable Through A Variable

To make it easier to deploy Microgateway without modifying the default configuration, the global log level is now defined as a variable in the default logback.xml. To change the global log level, set an environment variable or system property.

Infinite Loop Prevention in Single Sign-On

The SingleSignOnFilter has been adapted to prevent an infinite loop when a final redirect is returned without an AM session cookie name.

For information, see "SingleSignOnFilter" in the Configuration Reference, and "CrossDomainSingleSignOnFilter" in the Configuration Reference.

JwtSession Property for Skew Allowance

The property skewAllowance has been added to the JwtSession to manage the validity period of JWTs.

For information, see "JwtSession" in the Configuration Reference.

This release of the Microgateway includes the following important changes:

Default Value of Skew Allowance in JwtSession

The default skew allowance in JwtSession has been reduced from 2 minutes to zero, and a property to configure the skew allowance has been added in JwtSession.

For information, see "JwtSession" in the Configuration Reference.

KeyStore and KeyStoreSecretStore Default Type Based On Keystore Extension

Oracle recommends the use of PKCS12 keystores. From Java 9, Oracle has provided more support for PKCS12. From Java 11, Oracle has changed the default keystore to PKCS12.

Following this lead, the default type for KeyStore and KeyStoreSecretStore is now based on the keystore extension. If the keystore extension is not recognized, the default type is PKCS12. In previous releases, the default type was the one used by the platform.

To ensure backward-compatibility, where keys are generated using a non-PKCS12 type (for example, JKS), specify type in KeyStore or storeType in KeyStoreSecretStore.

For information, see "KeyStore" in the Configuration Reference and "KeyStoreSecretStore" in the Configuration Reference.

This release of the Microgateway includes the following important change:

gracefulStop In ScheduledExecutorService

When gracefulStop is true, the ScheduledExecutorService now removes submitted jobs and attempts to end running jobs, after respecting the gracePeriod. In previous releases, when gracefulStop was true, it did not remove or end jobs.

For other information about the ScheduledExecutorService, see ScheduledExecutorService, in the Identity Gateway Configuration Reference.