Notes covering prerequisites, fixes, known issues for ForgeRock® Access Management web agents. ForgeRock Access Management provides authentication, authorization, entitlement, and federation software.

• Web Agents 5.6.3 is the latest release targeted for Web Agents 5.6.x deployments, and can be downloaded from the ForgeRock Backstage website.

  See the list of fixes here.

• Changes to the Custom Login Redirection Mode

  Previous versions of Web Agents included the the Exchange SSO Token for JWT (com.forgerock.agents.accept.ipdp.cookie) property, which was used to convert SSO tokens into ID tokens during the custom login redirection mode.

  Web Agents 5.6.3 makes this property legacy, and includes a new property to replace it, Accept SSO Token (com.forgerock.agents.accept.sso.token).

  For more information about the new property, see Accept SSO Token (Not yet in the AM console)^[5] in the User Guide.

• There are no new features in this release, only bug fixes.

• Disable Validation of the aud and nonce JWT Claims

  During an authentication request, AM creates a JWT that contains, among others, the end user's session and the aud claim. This claim is set to the agent profile of the agent that made the request. When AM returns the JWT to the end user's user-agent, it appends to the request a nonce parameter, which is a one-time-usable random string that is understood by both AM and the agent that made the authentication request.

  When the agent receives a request to access a protected resource and the end user's user-agent attaches the JWT and the nonce parameter to the request, the agent checks that both the audience of the JWT (the aud claim) and the value of the nonce parameter are appropriate. For example, it checks that the value of the aud claim is the name of its own agent profile.

  In environments where several agents protect the same application, this validation poses a problem; even if the JWT is valid and contains a valid session, an agent cannot validate a JWT created for a different agent since the audience and the nonce would not match. Therefore, the agent redirects the end user for authentication again.

  Web Agents 5.6.2 introduces the following advanced properties to disable the validation of the aud and nonce claims represented in the JWT:

  • com.forgerock.agents.jwt.aud.whitelist. Configure a comma-separated list of agent profile IDs that the agent will accept as valid values for the aud claim.

    Use this property, for example, when your agents are configured with different agent profiles yet they are protecting the same application.

    Configuring this property disables nonce validation.

  • com.forgerock.agents.jwt.aud.disable. Set this property to 1 to stop the agent from validating both the aud and nonce claims.

    Note

    Agents should validate as many claims as possible for security reasons. Configure this property only if the com.forgerock.agents.jwt.aud.whitelist property is not suitable for your environment.

  For more information, see General Properties in the User Guide.

• Allow Agents to Refresh Session's Idle Timeout When Configured in SSO-only Mode

  Sessions in AM have an idle timeout after which they expire. In general, when users access protected resources through an agent, the agent requests a policy decision on behalf of that user, which resets the idle timeout.

  If the agent is configured in SSO-only mode, the session may unexpectedly expire in AM due to idle timeout before the user has finished accessing the application.

  To force the agent to refresh the users' session idle timeout when the user performs an action, Web Agents 5.6.2 includes the new com.forgerock.agents.call.session.refresh property.

  For more information, see Profile Properties in the User Guide.

• New Configuration Option for the org.forgerock.openam.agents.config.allow.custom.login Property

  Web Agents 5.6.2 adds a new configuration option for the org.forgerock.openam.agents.config.allow.custom.login property that appends a goto=original_request_url parameter to the redirect URL.

  For more information, see "Custom Login Redirection Mode" in the User Guide.

• There are no new features in this release.

• Support for Public AM URLs

  Web Agents 5.6.1.0 includes a new property, com.forgerock.agents.public.am.url, that specifies the public URL of the AM to redirect to. Use this property in environments where custom login pages are in a network that can only access AM using a proxy, a firewall, or any other technology that remaps the AM URL to one accessible by the custom login pages.

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

• Support for Converting SSO Tokens into OpenID Connect JWTs

  Web Agents 5.6.1.0 includes a new property, com.forgerock.agents.accept.ipdp.cookie, that specifies whether the agent should convert SSO tokens (iPlanetDirectoryPro cookies) present on requests into OpenID Connect JWTs.

  Set this property when your end users access resources protected by both Web Agents 4.x (which use SSO tokens) and 5.x (which use OpenID Connect JWTs). Converting the SSO token to a JWT will ensure a seamless experience to the user without additional redirection or re-authentication.

  For more information, see Profile Properties in the User Guide.

Web Agents 5.6.0 is a minor release that includes new platform support, bug fixes, and a new feature:

• Added Support for Distributed Policy Evaluation

  Web Agents 5.6.0 introduces a policy cache, which builds upon the existing policy decision cache.

  When enabled, web agents download and store details about policies from AM, and use them to make authorization decisions without having to contact AM each time. This reduces the agents' callbacks to AM and can increase the performance of the agents.

  Important

  This functionality is a Technology Preview.

  For more information, see "Caching Capabilities" in the User Guide.

• Support for TLSv1.3 added

  Web Agents 5.6 introduces support for TLSv1.3. OpenSSL 1.1.1 or later is required to support this protocol.

  For more information about supported OpenSSL versions, see "OpenSSL Requirements".

• AMAGENTS-2720: Request for a Cache for SSO tokens, to allow Agent 5+ to use only cookies

• There are no new feature improvements in this release, only bug fixes.

• Changes in MIME-Encoding of HTTP Header Values

  Earlier versions of Web Agents MIME-encoded HTTP header values if said values were multi-byte unicode strings.

  Web Agents 5.6.2 introduces a new advanced property, com.forgerock.agents.header.mime.encode, that controls whether the agent should MIME-encode the value of the HTTP headers, and when.

  The default value of the new property honors the behavior of previous releases.

  For more information, see Miscellaneous Header-Related Properties in the User Guide.

• Re-Introduction of goto Parameter for Custom Login Redirect

  Web Agents 5.6.2.0 has re-introduced the goto parameter for custom login redirects in IPDP mode.

  To set this feature, set the following properties:

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

  • com.forgerock.agents.accept.ipdp.cookie=1 (or 2), where 1 enables the feature to accept IPDP cookies, or 2 accepts IPDP cookies and realms.

• New Option to Change Advice Format Value

  Web agents 5.6.2.0 introduces a new property, com.forgerock.agents.advice.b64.url.encode=1, which changes the advice format XML, sent as part of the composite advice by the agent to AM. When the property is enabled, the advice is sent as base64url-encoded data.

  For more information, see AMAGENTS-2973: Create option to Change Advice Format Value

• There are no new improvements in this release, only bug fixes.

• There are no new improvements in this release, only bug fixes.

• There are no new improvements in this release, only bug fixes.

• OpenAM

• AM versions earlier than 5.5.

• Property and Value Pairs Set as Advanced Properties Are the Source of Truth

  Web Agents 5.6.3 take properties and value pairs set as advanced properties as the source of truth for that property. Earlier versions of the agents used the value in the property as the source of truth.

  For example, if you configure the value of the JWT Cookie Name property in the AM UI, but you also configure org.forgerock.openam.agents.config.jwt.name=myJWT as an advanced property, the agent now uses the latter, even if both are configured.

• There are no major changes in functionality in this release, other than bug fixes.

• There are no major changes in functionality in this release, other than bug fixes.

• There are no major changes in functionality in this release, other than bug fixes.

• Changes to the agentadmin --V Command

  Earlier versions of Web Agents included the agentadmin --V command, which you can use to validate an agent instance configuration.

  As part of the validation process, the agentadmin command ensures that the core init and shutdown agent sequences are working as expected. In some situations, this check made the agent instance unresponsive, causing unexpected service outages.

  Web Agents 5.6.1.0 does not execute the init and shutdown sequences when using the --V option. To run them, use the --Vi option instead.

  For more information, see "Command-Line Tool Reference" in the User Guide.

• Fully Qualified Domain Name Checking Off by Default

  The com.sun.identity.agents.config.fqdn.check.enable is now set to false by default. This default value was changed for the 5.6.0 release and differs from previous releases, which was set to true. The change better aligns local configurations to be consistent with centralized profiles, which has FQDN checking off by default.

• No functionality has been deprecated in this release.

• No functionality has been deprecated in this release.

• No functionality has been deprecated in this release.

• No functionality has been deprecated in this release.

• No functionality has been deprecated in this release.

• No functionality has been deprecated in this release.

• No components were removed in this release.

• No components were removed in this release.

• No components were removed in this release.

• No components were removed in this release.

• No components were removed in this release.

• No components were removed in this release.

• AMAGENTS-1610: If we set a property in the Custom Properties, it should overwrite value from other part of GUI

• AMAGENTS-2711: Fix nginx agent authentication under http/2 connections

• AMAGENTS-2728: Agent5 will not redirect to AMPostAuthProcessInterface.POST_PROCESS_LOGIN_SUCCESS_URL value

• AMAGENTS-3163: Web Agent audit log lines entries are truncated at 4096 bytes

• AMAGENTS-3205: Allow to set SameSite cookie attribute in web agent

• AMAGENTS-3303: Fallback mode does not work reliably

• AMAGENTS-3368: Webagent on 32bit windows platform will crash while opening existing log file which is close to (or over) 2GB in size

• AMAGENTS-3382: (WPA) Redirect loop is possible in custom login mode 1/2 because invalid sso cookie is not removed

• AMAGENTS-3404: Webagent 5 should display/log Cookie header value in validate_token

• AMAGENTS-2976: NEU Attribute fetch does not work unless there is cached data already.

• AMAGENTS-3056: The agent does not invalidate session before redirecting to logout

• AMAGENTS-3096: Realm argument within validator description negates the required slash

• AMAGENTS-3134: Invalid configuration of postdata.preserve.dir leads to crash / segmentation fault

• AMAGENTS-1370: port XHOST forwarding into web agents (apache agent & iis)

• AMAGENTS-2510: Agent5 running in SSO only mode is not using session response TTL values for its cache entry

• AMAGENTS-2699: Use whitelist to determine if jwt audience is allowed for agent

• AMAGENTS-2762: Agent is not mime-encoding specific UTF-8 header value

• AMAGENTS-2816: WPA5 is using hardcoded socket read timeout value for Windows SSL handshake processing module

• AMAGENTS-2840: WebAgent performs AM user REST call, although not needed

• AMAGENTS-2842: Re-introduce goto parameter handling for custom login redirect in web agent.

• AMAGENTS-2885: session SDK REST call to /users?_fields does not handle 404/400 as a valid rest/user json response

• AMAGENTS-2910: Not enforce requests containing particular cookie or header

• AMAGENTS-2975: Agent 5 not encoding # sign

• AMAGENTS-2982: Integer overflow error in http_request_serialise_host

• AMAGENTS-2998: Cannot access allowed site with agent using http

• AMAGENTS-3006: Drop of 25% in mean request per second time for Rest Fixed Performance Test for IIS platform

• AMAGENTS-3036: Windows CNG hashing code is not compatible with Windows 2008R2

• AMAGENTS-3095: Agent crashes parsing json object over 4096 bytes

• AMAGENTS-2816: WPA5 is using hardcoded socket read timeout value for Windows SSL handshake processing module

• AMAGENTS-2798: Seg Fault when custom login=true but login.url is empty

• AMAGENTS-2678: sso cookie is not found on custom-login-response and requires us to customize the service url

• AMAGENTS-2684: Create arg on Validator to not initiate validate_worker_init_shutdown.

• AMAGENTS-2702: If an sso token is presented, optimise agent flow by oauth2 token exchange

• AMAGENTS-215: FQDN checking should be turned off by default - Web agent local file

• AMAGENTS-1264: Update IIS agent Basic Auth support for JwtPasswordReplay

• AMAGENTS-1861: Agent 5 crash in websocket_handshake on Solaris SPARC

• AMAGENTS-2175: Erroneous size data in log messages on 32bit SPARC Solaris 10 WebAgent

• AMAGENTS-2188: Replace use of non-threadsafe strerror

• AMAGENTS-2199: Port override does not work properly when agent is behind load balancer

• AMAGENTS-2407: Agent is resetting CDSSO session cookie on authn redirect with policy advice available

• AMAGENTS-2456: WPA for Windows does not support OpenSSL 1.1.x

• 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. You can safely ignore these messages:

  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

• AMAGENTS-2720: Request for a Cache for SSO tokens, to allow Agent 5+ to use only cookies. Note: This fix works with AM 6 or later.

• AMAGENTS-3382: (WPA) Redirect loop is possible in custom login mode 1/2 because invalid sso cookie is not removed. Note: This fix works with AM 6 or later.

• Remote Audit Logging May Decrease Throughput

  Testing has found that use of remote audit logging may impact performance throughput due to the large number of requests sent from the web agent to AM.

• There are no known limitations or workarounds in this release.

• There are no known limitations or workarounds in this release.

• There are no known limitations or workarounds in this release.

• There is no deprecated functionality in this release.

• There are no new known issues in this release.

• There are no new known issues in this release.

• There are no new known issues in this release.

• There are no new known issues in this release.

• AMAGENTS-456: URL Comparison Case Sensitivity Check does not work for policies

• AMAGENTS-523: The files created during installation (e.g agent.conf) have the wrong permissions

• AMAGENTS-1584: Error message is confusing if using a different realm for obtaining the ID token compared with the SSO token

• AMAGENTS-2164: When setting audit log location to REMOTE there is a huge drop in performance

• AMAGENTS-2617: Build machine value is missing in version output for centos 7 nginx builds

• AMAGENTS-456: URL Comparison Case Sensitivity Check does not work for policies

• AMAGENTS-523: The files created during installation (e.g agent.conf) have the wrong permissions

• AMAGENTS-1584: Error message is confusing if using a different realm for obtaining the ID token compared with the SSO token

• AMAGENTS-2164: When setting audit log location to REMOTE there is a huge drop in performance

• AMAGENTS-2617: Build machine value is missing in version output for centos 7 nginx builds