Notes covering new features, fixes and known issues for ForgeRock® Access Management Java agents. ForgeRock Access Management provides open source authentication, authorization, entitlement and federation software.

Java Agents 5.7 is a major release that introduces new features, functional enhancements and fixes.

• Added Debug File Rotation Properties

  Java Agents 5.7 adds properties for rotating debug log files by size and time, and limiting the number of rotated debug log files to retain.

  For more information, see "Debug and Metric Properties" in the User Guide.

• Added SSO Token Compatibility Properties

  Java Agents 5.7 adds properties for allowing use of SSO tokens, which can be exchanged for JWTs, therefore allowing a mixture of older and newer agents in a deployment.

  For more information, see Enabling Support for Exchanging SSO Tokens in the User Guide.

• Added Autonomous "Fallback" Mode

  Java Agents 5.7 adds a com.forgerock.agents.config.fallback.mode bootstrap property, which enables the agents to run in an autonomous, "fallback" mode, independently of an AM instance.

  The agents will allow access as defined by not-enforced rules, and block access to everything else.

  For more information, see "Autonomous "Fallback" Mode" in the User Guide.

• Added Ability to Specify Cookie and Header Values in Not-enforced Rules

  Java Agents 5.7 adds the ability to specify cookie and header values in not-enforced rules, and combine them with HTTP methods.

  For more information, see Not-Enforced URI Processing Properties in the User Guide.

• Added Ability to Include Reason for Authentication in Custom Redirection Login Mode

  Java Agents 5.7 adds the ability to add a parameter with a value that includes the reason authentication is required. The parameter is included in the URL used when the agent redirects to a custom URL for authentication, and can be used to provide additional feedback to the user.

  For more information, see Login URL Properties in the User Guide.

• Added Support for Jetty Base Path

  The Jetty Java Agent 5.7 adds support for specifying the Jetty base path (the equivalent to the JETTY_BASE environment variable for Jetty) during the agent installation process.

  For more information, see "Installing the Jetty Java Agent" in the User Guide.

• Added Support for Redirecting to AM's Success URL

  Java Agents 5.7 support redirecting the end user to the success URL configured in the AM authentication service they used to authenticate.

  For more information, see the Redirect to AM's Success URL property in Login Processing Properties in the User Guide.

• Added Support for Customizing Authentication Error Messages

  By default, after an authentication failure error, Java agents return an HTTP 400 message regardless of the reason that caused the failure in the first place.

  Java Agents 5.7 lets you redirect the end user to a specific URL or URI, as well as customize the error message based on the reason, if required. For more information, see "Authentication Failure Notification" in the User Guide.

• Added Support for Configuring the Authentication Tracking Cookie

  Java agents use a cookie for tracking the progress of authentication with AM.

  By default, the agent uses one cookie to track all authentication requests. If the number of concurrent requests is large enough, the cookie may exceed the browser size limit and requests will fail.

  Java Agents 5.7 lets you configure the agent so it creates one cookie for each authentication request to AM. For more information, see the Authentication Tracking Cookie Name (org.forgerock.agents.authn.cookie.name) property in Cookie Properties in the User Guide.

• Added Support for Public AM URLs

  Java Agents 5.7 includes a new bootstrap property, org.forgerock.agents.public.am.url, that specifies the public URL of the AM instance.

  Use this property only if:

  • The agent is using the custom login redirection mode (custom login pages using SSO tokens).

  • The custom login pages are not in the same domain as the agent, and there is a proxy, firewall, or any other technology that remaps URLs between AM and the custom login pages.

  Consider an example where the traffic between AM and the agent happens through the example-internal.com network, but the custom login pages are on the example-external.com domain. In this case, you would configure https://openam.example-external.com:8443/openam as the public AM URL.

  For more information, see AM Public URL in the User Guide.

• Added Property Aliasing

  Java Agents 5.7 introduces aliases for configuration and bootstrap properties.

  For more information, see "About Java Agent Properties" in the User Guide.

• OpenAM

• AM versions earlier than 5.5.

• AMAGENTS-2648: Space Characters in UID aren't encoded.

• AMAGENTS-3050: JASPA - Need to redirect a standard page instead of FORBIDDEN when nonce is missing in jwt/cookie

• AMAGENTS-3517: JASPA: Fix validate call which is broken for restricted tokens

• CDSSO Domain List Restrictions for WildFly and JBoss

  Cookie support in WildFly and JBoss has been implemented so that only one cookie can be set with a certain name. This prevents setting the same cookie for multiple domains.

  Configuring the CDSSO Doimain List policy agent property with more than one cookie domain may result in redirection loops.

  To work around this issue, perform the following steps:

  1. Navigate to Realms > Realm Name > Applications > Agents > Java > Agent Name > SSO.

  2. Remove all cookie domains from the CDSSO Domain List (com.sun.identity.agents.config.cdsso.domain) property.

  3. Navigate to Realms > Realm Name > Applications > Agents > Java > Agent Name > Global.

  4. Configure any required entries in the Agent Root URL for CDSSO (sunIdentityServerDeviceKeyValue) property.

  The Java agent will set the cookie domain based on the requested resource.

• CDSSO Domain List Restrictions for Tomcat

  Tomcat 8.0.x introduced a new cookie processor, org.apache.tomcat.util.http.Rfc6265CookieProcessor, that became the default cookie processor on Tomcat 8.5.x.

  Due to the new cookie processor's cookie validation checks, configuring domains with leading dots (.) in the CDSSO Cookie Domain List property (com.sun.identity.agents.config.cdsso.domain) may result in the following issues:

  • Java agents returning HTTP 403 errors.

  • Tomcat server logging messages similar to the following:

    ERROR: AmFilter: Error while delegating to inbound handler: CDSSO Result Task Handler, access will be denied
    java.lang.IllegalArgumentException: An invalid domain [.example.com] was specified for this cookie
    at org.apache.tomcat.util.http.Rfc6265CookieProcessor.validateDomain(Rfc6265CookieProcessor.java:183)
    at org.apache.tomcat.util.http.Rfc6265CookieProcessor.generateHeader(Rfc6265CookieProcessor.java:125)
    at org.apache.catalina.connector.Response.generateCookieString(Response.java:989)
    at org.apache.catalina.connector.Response.addCookie(Response.java:937)
    at org.apache.catalina.connector.ResponseFacade.addCookie(ResponseFacade.java:386)
    at com.sun.identity.shared.encode.CookieUtils.addCookieToResponse(CookieUtils.java:412)
    ...

  To work around this issue, perform one of the following actions:

  • Configure the legacy cookie processor implementation, org.apache.tomcat.util.http.LegacyCookieProcessor, in your Tomcat server. Refer to the documentation for your version of Tomcat for more information.

  • Ensure the domains entered in the CDSSO Cookie Domain List property start with a number or a letter. For example:

    Valid configuration

    com.sun.identity.agents.config.cdsso.domain[0]=example.com
    com.sun.identity.agents.config.cdsso.domain[1]=123company.com

    Invalid configuration

    com.sun.identity.agents.config.cdsso.domain[0]=.example.com
    com.sun.identity.agents.config.cdsso.domain[1]=.mycompany.com

• The agentadmin Command Shows Warning Messages When Using JDK 11

  The agentadmin command may show warning messages similar to the following when using JDK 11:

  WARNING: An illegal reflective access operation has occurred
      WARNING: Illegal reflective access by org.forgerock.openam.sdk.com.google.inject.internal.cglib.core.$ReflectUtils$1 ...
      WARNING: Please consider reporting this to the maintainers of org.forgerock.openam.sdk.com.google.inject.internal.cglib.core.$ReflectUtils$1
      WARNING: Use --illegal-access=warn to enable warnings of further illegal reflective access operations
      WARNING: All illegal access operations will be denied in a future release

  You can safely ignore these messages.

• No issues were open at the time of the release.