Notes on prerequisites, fixes, and known issues for the ForgeRock® Token Validation Microservice.
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 Token Validation Microservice (TVMS) is delivered as part of the ForgeRock Identity Platform to introspect and validate OAuth 2.0 access_tokens in service-to-service deployments. For information about the features of TVMS, see the User Guide.
1.1. New Features
1.1.1. New Features in TVMS 1.0.2
The following new features were introduced in this release:
- 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.preferdeterministicecdsais by default
true. To use the less secure algorithm, set the property to
1.1.2. New Features in TVMS 1.0.1
No new features were introduced in this release.
1.1.3. New Features in TVMS 1.0.0
No new features were introduced in this release.
1.2. Product Improvements
This section lists improvements introduced in TVMS.
1.2.1. Product Improvements in TVMS 1.0.2
- Correct Maintenance of Cookies With
Cookies that arrive at TVMS with the
sameSiteflag set are correctly maintained.
- Ping Endpoint
A ping endpoint is available after TVMS startup to check whether the service is available. When TVMS is installed and running as described in "Starting and Stopping TVMS" in the User Guide, the endpoint is at
- Warning If Decoded Secret Starts or Ends in a Non-ASCII Character
TVMS 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
decodeBase64urlare added to facilitate URL-safe and filename-safe encoding and decoding.
- Global Log Level Configurable Through A Variable
To make it easier to deploy TVMS 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.
1.2.2. Product Improvements in TVMS 1.0.1
No improvements were introduced in this release.
1.2.3. Product Improvements in TVMS 1.0.0
No improvements were 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 TVMS.
If you have a request to support a component or combination not listed here, contact ForgeRock at email@example.com.
2.1. Downloading the TVMS Software
Download the product software from the ForgeRock BackStage download site:
TVMS .zip file,
2.2. Java Requirements
The following table lists supported Java versions:
|Oracle JDK||11 or later versions|
|OpenJDK||11 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.
If you use AM, AM version 6 or later is required.
The examples in the TVMS User Guide use AM, and assume that it is reachable on
Chapter 3. Compatibility With Other Releases
This chapter describes important changes to existing functionality, deprecated functionality, and removed functionality in TVMS.
3.1. Important Changes to Existing Functionality
This section lists important changes to existing functionality in TVMS.
3.1.1. Important Changes in TVMS 1.0.2
- 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
typein KeyStore or
3.1.2. Important Changes in TVMS 1.0.1
- gracefulStop In ScheduledExecutorService
true, the ScheduledExecutorService now removes submitted jobs and attempts to end running jobs, after respecting the
gracePeriod. In previous releases, when
gracefulStopwas true, it did not remove or end jobs.
3.1.3. Important Changes in TVMS 1.0.0
No important changes to existing functionality were made in this release.
3.2. Deprecated Functionality
There is no deprecated functionality in TVMS, as defined in "ForgeRock Product Stability Labels".
3.3. Removed Functionality
This section lists removed functionality in TVMS, as defined in "ForgeRock Product Stability Labels".
3.3.1. Removed Functionality in TVMS 1.0.2
No functionality was removed in TVMS 1.0.2.
3.3.2. Removed Functionality in TVMS 1.0.1
No functionality was removed in TVMS 1.0.1.
3.3.3. Removed Functionality in TVMS 1.0.0
No functionality was removed in TVMS 1.0.0.
Chapter 4. Fixes, Limitations, and Known Issues
This chapter lists the status of key issues and limitations in TVMS. TVMS issues are tracked at https://bugster.forgerock.org/jira/browse/MICSVC.
4.1. Key Fixes
This section lists key fixes in TVMS.
4.1.1. Key Fixes in TVMS 1.0.2
4.1.2. Key Fixes in TVMS 1.0.1
4.1.3. Key Fixes in TVMS 1.0.0
No important issues were fixed in this release.
This section lists limitations that apply to TVMS.
4.2.1. Limitations in TVMS 1.0.2
- CacheTimeout For The JwkSetSecretStore Cannot Be Disabled Or Lower Than 10 Seconds
cacheTimeoutproperty cannot be disabled in the JwkSetSecretStore. The minimum value is 10 seconds. If a lower value is set, the
cacheTimeoutis forced to 10 seconds.
- Streaming Mode Not Available
The 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.
- TVMS Scripts Can Access Anything in Their Environment (OPENIG-3274)
TVMS scripts are not sandboxed, but instead have access to anything in their environment. You must make sure that the scripts that TVMS 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.
CsvAuditEventHandleris used to log audit events, the log file is overwritten if it is rotated before the file suffix,
rotationFileSuffix, changes. By default,
rotationFileSuffixis defined as a date in the format
Log files are rotated when one of the following limits is reached:
Set the log rotation parameters so that the log is not likely to rotate before
- For Mutual Authentication in HTTPS Cannot Specify Which Certificate to Present (OPENIG-221)
TVMS can check server certificates for HTTPS. However, for mutual authentication, the client certificate must be the first certificate in the KeyStore.
Chapter 5. Documentation Changes
The following table lists important changes to the documentation:
Examples of how to introspect access tokens from the the ForgeRock Identity Cloud have been added to the User Guide.
The Configuration Reference has been added to the documentation set, and the Reference section removed from the User Guide.
Information about the ProtectionFilter is added in "Provided Objects" in the Configuration Reference. The filter was available in previous versions of TVMS but was not documented.
Update to the lists of important changes, fixes, limitations, and known issues in the Release Notes.
The first release of TVMS.
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 Label||Version Numbers||Characteristics|
Version: x[.0.0] (trailing 0s are optional)
Version: x.y[.0] (trailing 0s are optional)
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.
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.
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.
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.
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.
This feature or interface was deprecated in a previous release and has now been removed from the product.
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 and undocumented features or interfaces can change without notice. If you depend on one of these features or interfaces, contact ForgeRock support or email firstname.lastname@example.org 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 on ForgeRock's support offering, including support plans and service level agreements (SLAs), visit https://www.forgerock.com/support.
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.