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

Preface

ForgeRock Identity Platform™ serves as the basis for our simple and comprehensive Identity and Access Management solution. We help our customers deepen their relationships with their customers, and improve the productivity and connectivity of their employees and partners. For more information about ForgeRock and about the platform, see https://www.forgerock.com.

Chapter 1. What's New

The ForgeRock Microgateway is delivered as part of the ForgeRock Identity Platform as a standalone Identity Gateway, optimized to run in containerized environments.

The Microgateway shares a common core with ForgeRock Identity Gateway, and the majority of features are common to both Microgateway and IG. For information about the features of the Microgateway, see the User Guide. For information about features that are shared with IG, see the IG Documentation. The following features in IG are not provided in this release of Microgateway:

  • Delivery as a WAR file, Microgateway is delivered in a ZIP file only

  • SAML

  • WebSocket protocol

  • User-Managed Access (UMA)

  • Server-Sent Events (SSE)

  • Token Transformation, with the TokenTransformationFilter

  • Studio and Freeform Studio

1.1. New Features

1.1.1. New Features in Microgateway 1.0.2

The following new features were introduced in this release:

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.

1.1.2. New Features in Microgateway 1.0.1

There were no new features introduced this release.

1.1.3. New Features in Microgateway 1.0.0

There were no new features introduced this release.

1.2. Product Improvements

1.2.1. Product Improvements in Microgateway 1.0.2

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.

1.2.2. Product Improvements in Microgateway 1.0.1

There were no improvements introduced in this release.

1.2.3. Product Improvements in Microgateway 1.0.0

There were no improvements introduced in this release.

1.3. Security Advisories

ForgeRock issues security advisories in collaboration with our customers and the open source community to address any security vulnerabilities transparently and rapidly. ForgeRock's security advisory policy governs the process on how security issues are submitted, received, and evaluated as well as the timeline for the issuance of security advisories and patches.

For details of all the security advisories across ForgeRock products, see Security Advisories in the Knowledge Base library.

Chapter 2. Before You Install

This chapter describes the requirements for running Microgateway.

Tip

If you have a request to support a component or combination not listed here, contact ForgeRock at info@forgerock.com.

2.1. Downloading Microgateway Software

Download the software from the ForgeRock BackStage download site:

  • Microgateway .zip file, Microgateway-1.0.2.zip

2.2. Java Requirements

The following table lists supported Java versions:

JDK Requirements
VendorVersions
Oracle JDK11 or later versions
OpenJDK11 or later versions

For the latest security fixes, ForgeRock recommends that you use the most recent update.

2.3. Authorization Server Requirements

Use an OAuth 2.0 authentication server, such as ForgeRock Access Management. For information about downloading and using AM, see AM's Release Notes.

To use AM OAuth 2.0 authentication server, use at least AM version 6. To use OAuth 2.0 Mutual TLS, use at least AM version 6.5.1. For more information, see "ConfirmationKeyVerifierAccessTokenResolver" in the Configuration Reference and Validating OAuth 2.0 Access Tokens Obtained Through mTLS, in the IG Gateway Guide.

2.4. Third-Party Software Required for Encryption

To use RSASSA-PSS for signature encryption in the JwtBuilderFilter, install Bouncy Castle. For information, see The Legion of the Bouncy Castle.

Chapter 3. Compatibility With Other Releases

This chapter describes important changes to existing functionality, deprecated functionality, and removed functionality.

3.1. Important Changes to Existing Functionality

3.1.1. Important Changes to Existing Functionality in Microgateway 1.0.2

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.

3.1.2. Important Changes to Existing Functionality in Microgateway 1.0.1

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.

3.1.3. Important Changes to Existing Functionality in Microgateway 1.0.0

No important changes to existing functionality were made in this release.

3.2. Deprecated Functionality

This section lists deprecated functionality, as defined in "ForgeRock Product Stability Labels".

Deprecated Configuration Settings
Configuration Object Deprecated Settings Replacement Settings

SqlAttributesFilter

dataSource as a JNDI lookup name

Replaced by dataSource as a JdbcDataSource configuration object


3.3. Removed Functionality

This section lists removed functionality, as defined in "ForgeRock Product Stability Labels".

3.3.1. Removed Functionality in Microgateway 1.0.2

No functionality was removed in Microgateway 1.0.2.

3.3.2. Removed Functionality in Microgateway 1.0.1

No functionality was removed in Microgateway 1.0.1.

3.3.3. Removed Functionality in Microgateway 1.0.1

No functionality was removed in this release.

Chapter 4. Fixes, Limitations, and Known Issues

Microgateway issues are tracked at https://bugster.forgerock.org/jira/browse/OPENIG. This chapter covers the status of key issues and limitations in this release.

4.1. Key Fixes

4.1.1. Key Fixes in Microgateway 1.0.2

The following important issues were fixed in this release:

  • MICSVC-122: JAVA_HOME can't be defined in env.sh

  • MICSVC-135: TV: scope field is different when validating a stateless access token

  • OPENIG-3755: IG's decodeBase64 function returns null on JWTs generated by IG or AM

  • OPENIG-4037: Global decorators declared in a route cannot refer to decorators declared in the same route

  • OPENIG-4048: Update Jackson Databind to 2.10

4.1.2. Key Fixes in Microgateway 1.0.1

The following important issues were fixed in Microgateway 1.0.1:

  • OPENIG-3820: Path/QueryString with %encoded values are forwarded in a decoded way

  • OPENIG-3822: Fix Welcome page name product and documentation URL

4.1.3. Key Fixes in Microgateway 1.0.0

There were no important issues fixed in this release.

4.2. Limitations

This release of the Microgateway includes the following limitations:

CacheTimeout For The JwkSetSecretStore Cannot Be Disabled Or Lower Than 10 Seconds

The cacheTimeout property cannot be disabled in the JwkSetSecretStore. The minimum value is 10 seconds. If a lower value is set, the cacheTimeout is forced to 10 seconds.

Streaming Mode Not Available

The ReverseProxyHandler and ClientHandler cannot stream responses from a proxied application to the user agent. Responses are processed in non-streaming mode only, after the entire entity content is available. Consequently, only the non-streaming mode is available, which does not support Server-Sent Events (SSE) or very large files.

SamlFederationHandler Doesn't Support Filtering (OPENIG-3275)

The SamlFederationHandler does not support filtering. Do not use a SamlFederationHandler as the handler for a Chain.

More generally, do not use this handler when its use depends on something in the response. The response can be handled independently of Microgateway, and can be null when control returns to Microgateway. For example, do not use this handler in a SequenceHandler where the postcondition depends on the response.

Microgateway Scripts Can Access Anything in Their Environment (OPENIG-3274)

Microgateway scripts are not sandboxed, but instead have access to anything in their environment. You must make sure that the scripts that Microgateway loads are safe.

Log File of Audit Events Can be Overwritten (OPENIG-813)

The log file of audit events can be overwritten when the log file is rotated.

When CsvAuditEventHandler is used to log audit events, the log file is overwritten if it is rotated before the file suffix, rotationFileSuffix, changes. By default, rotationFileSuffix is defined as a date in the format _yyyy-MM-dd.

Log files are rotated when one of the following limits is reached: maxFileSize, rotationInterval, or rotationTimes.

Set the log rotation parameters so that the log is not likely to rotate before rotationFileSuffix changes.

CookieFilter Is Not JwtSession Compatible (OPENIG-458)

The CookieFilter heap object stores a java.net.CookieManager reference in the session, so that cookies are linked to the HTTP session. This behavior is not compatible with the use of a JwtSession.

SAML Fails With Incorrect User-Defined Mapping (OPENIG-234)

When the user defined mapping is incorrectly set, missing SAML assertions produce an infinite loop during authentication attempts.

For Mutual Authentication in HTTPS Cannot Specify Which Certificate to Present (OPENIG-221)

Microgateway can check server certificates for HTTPS. However, for mutual authentication, the client certificate must be the first certificate in the KeyStore.

4.3. Known Issues

This release includes the following known issues:

  • MICSVC-122: JAVA_HOME can't be defined in env.sh

  • OPENIG-659: CryptoHeaderFilter - error on handling header value with incorrect length

Chapter 5. Documentation Changes

The following table lists important changes to the documentation:

Documentation Changes
ReleaseDateDescription

1.0.2

November 2019

The Configuration Reference has been added to the documentation set, and the Reference section removed from the User Guide.

1.0.1

August 2019

Addition of a User Guide to the documentation set.

Update to the lists of important changes, fixes, limitations, and known issues in the Release Notes.

1.0.0

July 2019

The first release of Microgateway.


Appendix A. Release Levels and Interface Stability

This appendix includes ForgeRock definitions for product release levels and interface stability.

A.1. ForgeRock Product Release Levels

ForgeRock defines Major, Minor, Maintenance, and Patch product release levels. The release level is reflected in the version number. The release level tells you what sort of compatibility changes to expect.

Release Level Definitions
Release LabelVersion NumbersCharacteristics

Major

Version: x[.0.0] (trailing 0s are optional)

  • Bring major new features, minor features, and bug fixes

  • Can include changes even to Stable interfaces

  • Can remove previously Deprecated functionality, and in rare cases remove Evolving functionality that has not been explicitly Deprecated

  • Include changes present in previous Minor and Maintenance releases

Minor

Version: x.y[.0] (trailing 0s are optional)

  • Bring minor features, and bug fixes

  • Can include backwards-compatible changes to Stable interfaces in the same Major release, and incompatible changes to Evolving interfaces

  • Can remove previously Deprecated functionality

  • Include changes present in previous Minor and Maintenance releases

Maintenance, Patch

Version: x.y.z[.p]

The optional .p reflects a Patch version.

  • Bring bug fixes

  • Are intended to be fully compatible with previous versions from the same Minor release


A.2. ForgeRock Product Stability Labels

ForgeRock products support many features, protocols, APIs, GUIs, and command-line interfaces. Some of these are standard and very stable. Others offer new functionality that is continuing to evolve.

ForgeRock acknowledges that you invest in these features and interfaces, and therefore must know when and how ForgeRock expects them to change. For that reason, ForgeRock defines stability labels and uses these definitions in ForgeRock products.

ForgeRock Stability Label Definitions
Stability LabelDefinition

Stable

This documented feature or interface is expected to undergo backwards-compatible changes only for major releases. Changes may be announced at least one minor release before they take effect.

Evolving

This documented feature or interface is continuing to evolve and so is expected to change, potentially in backwards-incompatible ways even in a minor release. Changes are documented at the time of product release.

While new protocols and APIs are still in the process of standardization, they are Evolving. This applies for example to recent Internet-Draft implementations, and also to newly developed functionality.

Legacy

This feature or interface has been replaced with an improved version, and is no longer receiving development effort from ForgeRock.

You should migrate to the newer version, however the existing functionality will remain.

Legacy features or interfaces will be marked as Deprecated if they are scheduled to be removed from the product.

Deprecated

This feature or interface is deprecated and likely to be removed in a future release. For previously stable features or interfaces, the change was likely announced in a previous release. Deprecated features or interfaces will be removed from ForgeRock products.

Removed

This feature or interface was deprecated in a previous release and has now been removed from the product.

Technology Preview

Technology previews provide access to new features that are considered as new technology that is not yet supported. Technology preview features may be functionally incomplete and the function as implemented is subject to change without notice. DO NOT DEPLOY A TECHNOLOGY PREVIEW INTO A PRODUCTION ENVIRONMENT.

Customers are encouraged to test drive the technology preview features in a non-production environment and are welcome to make comments and suggestions about the features in the associated forums.

ForgeRock does not guarantee that a technology preview feature will be present in future releases, the final complete version of the feature is liable to change between preview and the final version. Once a technology preview moves into the completed version, said feature will become part of the ForgeRock platform. Technology previews are provided on an “AS-IS” basis for evaluation purposes only and ForgeRock accepts no liability or obligations for the use thereof.

Internal/Undocumented

Internal and undocumented features or interfaces can change without notice. If you depend on one of these features or interfaces, contact ForgeRock support or email info@forgerock.com to discuss your needs.


Appendix B. Getting Support

ForgeRock provides support services, professional services, training through ForgeRock University, and partner services to assist you in setting up and maintaining your deployments. For a general overview of these services, see https://www.forgerock.com.

ForgeRock has staff members around the globe who support our international customers and partners. For details, visit https://www.forgerock.com, or send an email to ForgeRock at info@forgerock.com.

ForgeRock publishes comprehensive documentation online:

  • The ForgeRock Knowledge Base offers a large and increasing number of up-to-date, practical articles that help you deploy and manage ForgeRock software.

    While many articles are visible to community members, ForgeRock customers have access to much more, including advanced information for customers using ForgeRock software in a mission-critical capacity.

  • ForgeRock product documentation, such as this document, aims to be technically accurate and complete with respect to the software documented. It is visible to everyone and covers all product features and examples of how to use them.

Read a different version of :