• Java Agents 5.0.1.1 Patch Release

  ForgeRock periodically issues patch releases with important fixes to bugs. Java Agents 5.0.1.1 is the latest patch release, targeted for Java Agents 5.0.1 deployments and can be downloaded from the ForgeRock BackStage website. To view the list of fixes in this release, see Java Agents 5.0.1.1.

  Note

  ForgeRock patch releases are aimed as a fast-track method to provide fixes to existing bugs. These fixes improve the functionality, performance and security of your deployment. No new features have been introduced.

  Java Agents 5.0.1 is available for download and can be found at the ForgeRock BackStage website.

Java Agents 5.0.1 is a maintenance release containing key fixes and a new feature:

• Support for Custom Redirection Login Pages

  Starting from 5.0.1, Java Agents introduce a custom redirection login mode that supports:

  • Environments that already have customized login pages that expect user sessions to be stored in SSO tokens instead of in OIDC JWTs, whether these are XUI login pages or not.

  • Environments configured so the users cannot access the AM servers directly.

  • Environments configured so the custom login pages are not part of AM's XUI.

  To support the custom redirection login mode, Java Agents 5.0.1 include the following properties:

  • org.forgerock.openam.agents.config.allow.custom.login

  • OpenAM Login URL com.sun.identity.agents.config.login.url (this property was removed in Java Agents 5, and it has been reinstated)

  • org.forgerock.openam.agents.config.conditional.custom.login.url

  For more information, see Section 1.4.10, "Redirection and Conditional Redirection" in the User Guide.

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

• Communication With AM Uses the OAuth 2.0 Authorization Framework

  Java agents and AM exchange OpenID Connect JSON web tokens (JWTs) containing the information required to authenticate clients and authorize access to protected resources. The former method of communication, platform lower-level (PLL) calls, is no longer used.

  To ensure integrity, AM signs the JWTs with the test key alias by default. To change the signing key, see Section 2.2, "Configuring Access Management Servers to Communicate With Java Agents" in the User Guide.

  Decoding JWTs into JSON objects is a CPU-intensive operation. To reduce the amount of processing required on each request, Java agents cache decoded JWTs. The following properties control the cache's behavior:

  • org.forgerock.openam.agents.config.jwt.cache.size

  • org.forgerock.openam.agents.config.jwt.cache.ttl.minutes

  For more information, see Section 1.4.11, "Caching Capabilities" and Profile Properties in the User Guide.

  Java Agents 5 also include a new property, JWT Cookie Name (org.forgerock.openam.agents.config.jwt.name), that specifies the name of the cookie that holds the JWT on the user's browser. By default, this property is set to the value of am-auth-jwt. For more information, see Profile Properties in the User Guide.

• New Container Versions Supported

  Java Agents 5 now support the following container versions:

  • Apache Tomcat 8.5

  • JBoss Enterprise Application Platform 7

  • Jetty 9

  • Wildfly 9 and 10.1

  The list of supported operating systems has also been updated. For more information on supported containers, see Section 2.1, "Platform Requirements".

• Support for JDK 8

  Java Agents 5 now support the following JDKs:

  • Oracle Java 8

  • IBM Java 8 (WebSphere only)

  • OpenJDK 8

  For more information about supported JDK versions, see Section 2.3, "Java Requirements".

• Continuous Security

  Because Java agents are the first point of contact between users and your business applications, they can collect inbound requests' cookie and header information which an AM server-side authorization script can then process.

  For example, you may decide that only incoming requests containing the InternalNetwork cookie can access the intranet outside working hours.

  Java agents introduce two properties related to continuous security:

  • Continuous Security Cookies (org.forgerock.openam.agents.config.continuous.security.cookies)

  • Continuous Security Headers (org.forgerock.openam.agents.config.continuous.security.headers)

  For more information about these properties, see Continuous Security Properties in the User Guide.

• New Active Session Cache Timeout Property

  Java Agents 5 include a new property, org.forgerock.openam.agents.config.active.session.cache.ttl.minutes, to specify the time interval in minutes after which an active session in the Java agent's cache expires.

  For more information about this property, see Policy Client Service Properties in the User Guide.

• Improvements to Not-Enforced Rules

  Not-Enforced rules now support:

  • Creating compound rules, specifying not-enforced URI and IP patterns in the same rule

  • Using netmask or IP range notation when configuring the Not-Enforced Client IP List property

  • Using regular expressions in not-enforced URI and IP rules

  • Filtering for HTTP methods in not-enforced URI and IP rules

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

• Improved POST Data Preservation

  The POST data preservation feature of the Java agents has improved security. The agent now:

  • Generates a random unique identifier as the dummy endpoint from which the client recovers the POST data. This identifier is then placed into an encrypted cookie and provided to the client, which protects it from being snooped.

  • Links the client session and the POST data using a one-time code. During authentication, the client is provided with a cookie containing the one-time code required to access the endpoint and recover the POST data. If the client cannot provide the code (because the cookie is missing) or the code differs from the one stored with the POST data, the Java agent denies access to the endpoint.

    Therefore, if a malicious user gets hold of the endpoint string, the agent will deny access to the endpoint to that user unless they can provide the one-time code.

  • Introduces two new configuration properties to manage the cache and mitigate against DoS attacks: PDP Maximum Number of Cache Entries and PDP Maximum Cache Size.

  For more information, see Section 1.4.8, "POST Data Preservation" and Post Data Preservation Properties in the User Guide.

• Improved Notification System

  To receive notifications from AM, earlier versions of the Java agent required the administrator to configure bi-directional communication through load balancers, firewalls, and proxy servers. Java Agents 5 simplify the configuration by using the WebSocket protocol to keep long-running connections open with AM.

  Listeners defined in the Agent Notification URL property (com.sun.identity.client.notification.url) are only relevant to the old notification system and can be removed.

  Java agents also include a new property, Web Socket Connection Interval, to configure the time interval after which the agent reopens its WebSocket connection to the AM site. This property ensures that WebSocket connections from agents are spread across the AM site.

  For more information, see Section 1.4.2, "Notification System" and Profile Properties in the User Guide.

• Improved Audit Logging

  Local and remote audit messages now adhere to the log structure common across the ForgeRock Identity Platform and support propagation of the transaction ID across the platform.

  For more information, see Section 4.2, "Configuring Audit Logging" in the User Guide.

• Improvements in Cross-Domain Single Sign-On

  Cross-domain single sign-on (CDSSO) includes the following improvements:

  • CDSSO now provides single sign-on (SSO) for AM and Java agents configured in the same DNS domain and across DNS domains.

    CDSSO is the default and only SSO mode for Java agents, which simplifies the configuration.

  • AM now provides CDSSO using the OAuth 2.0 protocol and the oauth2/authorize endpoint. The former method of providing SSO, CDCServlet, is no longer used.

  Due to these changes, the following properties are no longer used:

  • CDSSO Servlet URL (com.sun.identity.agents.config.cdsso.cdcservlet.url)

  • Cross Domain SSO (com.sun.identity.agents.config.cdsso.enable)

  • CDSSO Trusted ID Provider (com.sun.identity.agents.config.cdsso.trusted.id.provider)

  For more information and implementation details, see About Single Sign-On and Configuring Cross-Domain Single Sign-On in the ForgeRock Access Management Authentication and Single Sign-On Guide.

• OpenAM

• AM versions earlier than 5.5.

• agentapp.war Application Required

  Java Agents 5 require the agentapp.war application to be deployed alongside the agent. In previous versions, deploying the application was optional.

• Changes to Alternative Agent Port, Hostname, and Protocol Properties

  Configuring an alternative agent port, hostname, or protocol now requires adding an entry in the Agent Root URL for CDSSO property. Failure to do so may result in redirection loops or redirect_uri_mismatch errors.

• Agent Directories Renamed

  The following agent directories have been renamed:

  • /j2ee_agent/tomcat_v6_agent is now /java_agent/tomcat_agent

  • /j2ee_agent/jboss_v7_agent is now /java_agent/jboss_agent

  • /j2ee_agent/jetty_v61_agent is now /java_agent/jetty_agent

  • /j2ee_agent/weblogic_v10_agent is now /java_agent/weblogic_agent

  • /j2ee_agent/websphere_v61_agent is now /java_agent/websphere_agent

• Changes to Login, Logout, and Conditional Login Properties

  Earlier versions of the Java agent could configure a number of properties to customize the login and logout URLs that the agent uses when redirecting users. Moreover, you could configure conditional login rules to redirect incoming requests from specific domains to specific AM instances.

  These properties have changed in Java Agents 5 as follows:

  • Earlier versions of the Java agent authenticated users using the UI or XUI URL (which could also contain a mention of the CDCServlet in CDSSO flows). Therefore, login properties configured the URL to authenticate the user to a specific realm and a specific user data store. For example:

    https://openam.example.com:443/openam/UI/Login&realm=%2Fcustomers
    https://openam.example.com:443/openam/XUI/?realm=/customers#login/

    Logout properties could be configured similarly.

    Java Agents 5 authenticate to and log out users from the oauth2/authorize endpoint, which is not configurable. Therefore:

    • To specify the realm or authentication module to which users should authenticate to, or log out from, add a conditional redirection rule. For example:

      example.com|https://openam.example.com/openam/oauth2/authorize?realm=customers

    • The following login and logout properties have been removed from Java Agents 5:

      • OpenAM Login URL, com.sun.identity.agents.config.login.url

        Note

        This property has been reinstated in Java Agents 5.0.1.

      • Login URL Prioritized, com.sun.identity.agents.config.login.url.prioritized

      • Login URL Probe, com.sun.identity.agents.config.login.url.probe.enabled

      • Login URL Probe Timeout, com.sun.identity.agents.config.login.url.probe.timeout

      • OpenAM Logout URL, com.sun.identity.agents.config.logout.url

      • Logout URL Prioritized, com.sun.identity.agents.config.logout.url.prioritized

      • Logout URL Probe, com.sun.identity.agents.config.logout.url.probe.enabled

      • Logout URL Probe Timeout, com.sun.identity.agents.config.logout.url.probe.timeout

  • Conditional login and logout properties have changed:

    • OpenAM Conditional Logout URL, org.forgerock.openam.agents.config.conditional.logout.url, replaces com.sun.identity.agents.config.conditional.logout.url.

    • OpenAM Conditional Login URL, org.forgerock.openam.agents.config.conditional.login.url, replaces com.sun.identity.agents.config.conditional.login.url.

  • Earlier versions of the Java agent allowed configuring conditional login and logout redirection to several AM instances specified in the same list to balance login and logout operation across instances.

    Java Agents 5 allow one redirection URL per rule. Configure the URL of an AM site or, alternatively, a load balancer to balance connections.

  • Java Agents 5 let you configure conditional login and conditional logout redirection against any service or website in your environment.

  • Java Agents 5 conditional login and conditional logout properties let you specify domains, subdomains, and paths as the incoming request URL in each rule.

  For more information about conditional login and conditional logout, see Login URL Properties and Logout URL Properties in the User Guide.

• Changes to the Java Agent's Startup Sequence

  The following change has been made to the Java agent's startup sequence:

  • Earlier versions of the Java agent used the bootstrap property com.iplanet.am.naming.url to specify the URL of the AM instance(s) the agent connects to. This property could be used to balance agent connections between AM servers in a site.

    Java Agents 5 assembles AM's URL from properties, as follows:

    com.iplanet.am.server.protocol://com.iplanet.am.server.host:com.iplanet.am.server.port/com.iplanet.am.services.deploymentDescriptor

    The properties used to build AM's URL are configured during agent installation. To balance agent connections to an AM site, specify the load balancer's FQDN when you are prompted for the OpenAM server URL during installation. For example:

    ...
    -----------------------------------------------
    SUMMARY OF YOUR RESPONSES
    -----------------------------------------------
    JBoss home directory : /path/to/jboss/
    JBoss deployment mode: standalone
    Install agent as global module: true
    OpenAM server URL : http://openam.loadbalancer.com:8080/openam
    Agent URL : http://www.example.com:8080/agentapp
    Agent Profile name : JBossAgent
    Agent Profile Password file name : /tmp/pwd.txt
    ...
    

    The com.iplanet.am.naming.url property is no longer used.

  • Java agents now start up when AM is not available, denying all requests to protected and not-enforced resources until AM is available.

• There is no deprecated functionality in this release.

• Removed Support for the Identity Membership Environment Condition in Policies

  Java Agents 5 does not support policies configured with the Identity Membership(AMIdentityMembership) environment condition. Instead, configure the equivalent User & Group (Identity) subject condition. For more information, see the ForgeRock Access Management Authorization Guide.

• Removed Support for Several Container Versions

  Java Agents 5 does not support the following container versions:

  • Apache Tomcat 6

  • Jboss Application Server 7

  • IBM WebSphere Application Server 8

  • Oracle WebLogic Server 11g

  • Jetty 8

  For more information on supported containers, see Section 2.1, "Platform Requirements".

• Removed Support for Several Operating System Versions

  Java Agents 5 do not support the following operating system versions:

  • RedHat Enterprise Linux 5

  • CentOS 5

  • Oracle Linux 5

  • Ubuntu 12.04 LTS

  • Windows Server 2008

• Removed Support for JDK 7 and Earlier

  Java Agents 5 require JDK 8. For more information on supported JDK version, see Section 2.3, "Java Requirements".

• Removed Support for Configuring the Agent's Encryption Provider

  Java Agents 5 remove support for configuring the agent's encryption provider class, which now defaults to org.forgerock.openam.shared.security.crypto.AESWrapEncryption. Therefore, the Encryption Provider (com.iplanet.security.encryptor) property is no longer supported.

• Removed Support for the Java Authentication and Authorization Service (JAAS)

  Defining role-based access control of web resources using Java declarative security is not supported. Therefore:

  • The com.sun.identity.agents.config.filter.mode property no longer supports the J2EE_POLICY setting.

  • The following configuration properties are no longer supported:

    • Default Privileged Attribute (com.sun.identity.agents.config.default.privileged.attribute)

    • Privileged Attribute Type (com.sun.identity.agents.config.privileged.attribute.type)

    • Privileged Attributes To Lower Case (com.sun.identity.agents.config.privileged.attribute.tolowercase)

    • Privileged Session Attribute (com.sun.identity.agents.config.privileged.session.attribute)

    • Enable Privileged Attribute Mapping (com.sun.identity.agents.config.privileged.attribute.mapping.enable)

    • Privileged Attribute Mapping (com.sun.identity.agents.config.privileged.attribute.mapping)

    • WebAuthentication Available (com.sun.identity.agents.config.jboss.webauth.available)

• Removed agentadmin --migrate Option

  The --migrate early-access option has been removed from the agentadmin command.

  To upgrade Java agents, see Chapter 5, "Upgrading Java Agents" in the User Guide.

• Removed Properties

  Java Agents 5 remove support for the following configuration properties:

  • Agent Notification URL (com.sun.identity.client.notification.url)

  • CDSSO Clock Skew (com.sun.identity.agents.config.cdsso.clock.skew)

  • CDSSO Servlet URL (com.sun.identity.agents.config.cdsso.cdcservlet.url)

  • CDSSO Trusted ID Provider (com.sun.identity.agents.config.cdsso.trusted.id.provider)

  • Client Polling Period (com.iplanet.am.session.client.polling.period))

  • com.iplanet.am.naming.url

  • Cross Domain SSO (com.sun.identity.agents.config.cdsso.enable)

  • Default Privileged Attribute (com.sun.identity.agents.config.default.privileged.attribute)

  • Encryption Provider (com.iplanet.security.encryptor)

  • Enable Privileged Attribute Mapping (com.sun.identity.agents.config.privileged.attribute.mapping.enable)

  • Login URL Prioritized (com.sun.identity.agents.config.login.url.prioritized)

  • Login URL Probe ((com.sun.identity.agents.config.login.url.probe.enabled))

  • Login URL Probe Timeout (com.sun.identity.agents.config.login.url.probe.timeout)

  • Logout URL Prioritized (com.sun.identity.agents.config.logout.url.prioritized)

  • Logout URL Probe (com.sun.identity.agents.config.logout.url.probe.enabled)

  • Logout URL Probe Timeout (com.sun.identity.agents.config.logout.url.probe.timeout)

  • OpenAM Conditional Login URL, com.sun.identity.agents.config.conditional.login.url, replaced by org.forgerock.openam.agents.config.conditional.login.url

  • OpenAM Conditional Logout URL com.sun.identity.agents.config.conditional.logout.url, replaced by org.forgerock.openam.agents.config.conditional.logout.url

  • OpenAM Login URL (com.sun.identity.agents.config.login.url)

  • OpenAM Logout URL (com.sun.identity.agents.config.logout.url)

  • Policy Client Clock Skew (com.sun.identity.policy.client.clockSkew

  • Privileged Attribute Mapping (com.sun.identity.agents.config.privileged.attribute.mapping)

  • Privileged Attribute Type (com.sun.identity.agents.config.privileged.attribute.type)

  • Privileged Attributes To Lower Case (com.sun.identity.agents.config.privileged.attribute.tolowercase)

  • Privileged Session Attribute (com.sun.identity.agents.config.privileged.session.attribute)

  • Remote Log File Name (com.sun.identity.agents.config.remote.logfile)

  • SSO Cache Enabled (com.sun.identity.agents.config.amsso.cache.enable)

  • Web Service Authenticator (com.sun.identity.agents.config.webservice.authenticator)

  • Web Service Authorization Error Content File (com.sun.identity.agents.config.webservice.autherror.content)

  • Web Service Enable (com.sun.identity.agents.config.webservice.enable)

  • Web Service End Points (com.sun.identity.agents.config.webservice.endpoint)

  • Web Service Internal Error Content File (com.sun.identity.agents.config.webservice.internalerror.content)

  • Web Service Process GET Enable (com.sun.identity.agents.config.webservice.process.get.enable)

  • Web Service Response Processor (com.sun.identity.agents.config.webservice.responseprocessor)

  • WebAuthentication Available (com.sun.identity.agents.config.jboss.webauth.available)

  This is a comprehensive list of all the properties removed, some of which are mentioned in other places of these release notes.

  The properties are still available when creating a new agent profile in AM 5.5 to provide backwards-compatibility with earlier versions of the Java agent.

• AMAGENTS-1805: Log level is not hotswappable on java agents 5.0

• AMAGENTS-1626: JASPA: Realm parameter set for login url should also be passed into the goto URL

• AMAGENTS-1571: Alternative Agent Port Number not working in a LB env when sso cookie is present

• AMAGENTS-1537: Agent 5 does not have standard solution for custom login pages.

• AMAGENTS-1516: JASPA: password encryption via the admin tool throws an exception

• AMAGENTS-1482: Secure Web Sockets does not work on WildFly

• AMAGENTS-1422: Java Agent installer has a bug around XML parsing

• AMAGENTS-1441: Java Agent5 can not start with non-datastore module in default chain

• AMAGENTS-1453: JASPA 5 (java agent) redirection ( infinite ) loop in sunwCDSSOUriRedirect

The following important issues were fixed in this release:

• AMAGENTS-1247: The installer manipulates (i.e. damages) the host-manager web.xml file during install

• AMAGENTS-1146: Java agent is confused about secure cookie properties

• AMAGENTS-821: Jetty_v7 j2ee agent is not compatible with jetty 9+

• AMAGENTS-791: Tomcat installer allows install into Tomcats which don't support websockets

• AMAGENTS-783: Some valid special characters set as HTTP_HEADERs are not being encoded

• AMAGENTS-409: Cookie reset is failing on Java Agents

• AMAGENTS-374: JEE Agent 3.5.1 Install fails with WildFly 10.x and EAP 7

• AMAGENTS-364: agents.config.policy.evaluation.realm does not handle realm aliases

• AMAGENTS-170: Java agent installer to ignore Tomcat version

• AMAGENTS-104: J2EE agent installer uses an old endpoint /identity/authenticate which breaks with OpenAM 13

• AMAGENTS-83: When using a site logout page, OpenAM cookies do not get cleared when trying to logout

• 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 > J2EE > 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 > J2EE > 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 Apache Tomcat

  Apache Tomcat 8.0.x introduced a new cookie processor, org.apache.tomcat.util.http.Rfc6265CookieProcessor, that became the default cookie processor on Apache 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.

  • Apache 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 Apache Tomcat server. Refer to the documentation for your version of Apache 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 following important known issues remained opened at the time release 5 became available:

• AMAGENTS-1093: Weblogic Java agent adds an index.jsp file to the URL after authentication when a directory is requested

• AMAGENTS-896: When using local configuration and after setting log level to message we do not get any output in debug.out