Notes covering prerequisites, fixes, known issues for ForgeRock® Access Management web policy agents. ForgeRock Access Management provides authentication, authorization, entitlement, and federation software.
Preface
Read these release notes before you install the Web Policy Agent.
The information contained in these release notes cover prerequisites for installation, known issues and improvements to the software, changes and deprecated functionality, and other important information.
About ForgeRock Identity Platform™ Software
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
Before you install AM web policy agents or update your existing web policy agent installation, read these release notes.
Certificate Verification depth for OpenSSL Configurable
Web Policy Agent 4.1.1 includes a new property,
org.forgerock.agents.config.cert.verify.depth, to specify the certificate verification depth when OpenSSL is enabled.For more information, see Encryption Properties in the Web Policy Agent Guide.
New Environment Variable to Support Load Balancers Without Session Stickiness
When the AM servers are configured behind a load balancer that does not support session stickiness, the web policy agent login sequence may fail, resulting in the following issues:
Web policy agents returning HTTP 403 errors.
Web policy agents logging error messages, such as
invalid session,session was not obtained, orget_config failed.
Web Policy Agent 4.1.1 includes a new environment variable,
AM_AGENT_REST_LOGIN, to allow the agent to authenticate to AM servers configured behind a load balancer that does not support session stickiness.For more information, see "Configuring Web Policy Agent Environment Variables" in the Web Policy Agent Guide.
Pattern-Match Policy Delegation
In environments where protected URLs are dynamic, the web agent's policy decision cache may not receive hits on subsequent policy validations. For example, a request to the resource at
http://www.example.com/myApp?param1=truewould not match a request forhttp://www.example.com/myApp?param1=true¶m2=trueeven though the base URL is the same.In these cases, the web agent may need to contact AM frequently for policy evaluation, which may cause a performance impact on both the agent and AM.
Although this is the expected behavior, Web Policy Agent 4.1.1 includes a new advanced property,
org.forgerock.agents.config.policy.rule, that allows the web agent to match an inbound request from an authenticated user against a regular expression stored alongside a policy decision in the policy cache. If there is a match, the web agent replays the policy decision without contacting AM.For more information, see Miscellaneous Custom Properties in the Web Policy Agent Guide.
Support for CDSSO Environments Without Sticky Load Balancing
Web Policy Agent 4.1.1 adds a new environment variable,
AM_AGENT_KEY, to help the login process in CDSSO environments without sticky load balancing.When configured, web agents store CDSSO data encrypted and zipped into the
X-AMAGENT-TXcookie. Any web agent in the environment can decrypt the cookie and satisfy the CDSSO request.For more information, see "Configuring Web Policy Agent Environment Variables" in the Web Policy Agent Guide.
Support for OpenSSL 1.1.0 Added
Web Policy Agent 4.1.1 for Unix and Linux supports OpenSSL 1.1.0 libraries. For more information about OpenSSL supported versions, see "Supported OpenSSL Versions".
Cookie Reset Support for Cookie Paths
The Cookie Reset Name List (
com.sun.identity.agents.config.cookie.reset) property now supports specifying the cookie path of the cookie to be reset.For more information, see Cookie Reset Properties in the Web Policy Agent Guide.
Support for Windows Server 2016 Added
Web Policy Agent 4.1.x now supports Apache HTTP Server and Microsoft IIS web servers on Windows Server 2016. For more information about supported web servers, see "Web Policy Agents Platform Requirements".
New NGINX Plus Policy Agent
Web Policy Agent 4.1 includes a new policy agent that supports NGINX Plus web servers. For more information, see "Web Policy Agents Platform Requirements" and "Installing Web Policy Agents in NGINX Plus" in the Web Policy Agent Guide.
The NGINX Plus policy agent supports regular expressions to improve conditional login URL redirection. For more information, see the Regular Expression Conditional Login URL property on "Configuring Access Management Services Properties" in the Web Policy Agent Guide.
Improved Logging and Caching
Web Policy Agents 4.1 have re-engineered logging and agent policy caching functionality for improved stability and performance.
New JSON-Formatted Response Properties
Additional properties for controlling JSON-formatted responses are available in Web Policy Agents 4.1.
For more information, see JSON-Formatted Response Properties in the Web Policy Agent Guide.
New Garbage Collector Statistics Log
Garbage collector statistics for all policy agent instances in the container are written into the new
/web_agents/type/log/agent.logfile.For more information, see "Configuring Web Policy Agent Environment Variables" in the Web Policy Agent Guide.
32-bit and 64-bit Web Policy Agent Package for IIS
New in Web Policy Agent 4.1 for IIS, there is only one downloadable package that supports both 32-bit and 64-bit IIS application pools.
Added Support for Windows built-in Secure Channel API
Web policy agents installed on Windows operating systems now use the built-in Secure Channel API for SSL/TLS communications with AM by default.
For more information, see Encryption Properties in the Web Policy Agent Guide.
Relative URL Support in Access Denied Property
You can now specify a relative path in the
com.sun.identity.agents.config.access.denied.urlproperty.For more information, see General Properties in the Web Policy Agent Guide.
The agentadmin Command Now Returns Status Codes on Failure
If running the agentadmin command in a script, you can now check the return value to determine if the command succeeded.
For more information, see agentadmin(1) in the Web Policy Agent Guide.
Added Support for PKCS#12/PFX Client Certificate Files
On Windows operating systems you can now specify a PKCS#12/PFX client certificate file in the
com.forgerock.agents.config.cert.fileproperty.For more information, see Encryption Properties in the Web Policy Agent Guide.
Chapter 2. Before You Install
This chapter covers software and hardware prerequisites for installing and running web policy agent software.
ForgeRock supports customers using the versions specified here. Other versions and alternative environments might work as well. When opening a support ticket for an issue, however, make sure you can also reproduce the problem on a combination covered here.
2.1. Web Policy Agents Platform Requirements
The following table summarizes platform support.
| Operating Systems | OS Versions | Web Servers & Versions | |||||
|---|---|---|---|---|---|---|---|
|
|
| |||||
|
| ||||||
|
|
| |||||
|
| ||||||
|
| ||||||
|
|
| |||||
|
|
| |||||
|
| ||||||
|
| ||||||
|
|
| |||||
[a] The Apache HTTP Server Project does not offer binary releases for Microsoft Windows. The ForgeRock Apache HTTP Server policy agent for Windows was tested against the binaries offered by Apache Lounge. | |||||||
The following table summarizes OpenSSL support for SSL and TLS connections.
| Operating Systems | OpenSSL Versions | ||||
|---|---|---|---|---|---|
| OpenSSL 1.0.x, OpenSSL 1.1.0 | ||||
| Microsoft Windows Server | OpenSSL 1.0.x [a] | ||||
| OpenSSL 0.9.8, OpenSSL 1.0.x, OpenSSL 1.1.0 | ||||
| IBM AIX | OpenSSL 0.9.8, OpenSSL 1.0.x, OpenSSL 1.1.0 | ||||
[a] On Windows operating systems, the policy agents use the native Windows SSL libraries by default. | |||||
Note
OpenSSL 1.1.0 is supported for Web Policy Agent 4.1.1 only
OpenSSL 1.0.2 is required to support TLSv1.2
Before installing web policy agents on your platform, also make sure that the system meets the following requirements:
- Linux Systems
Before installing web policy agents on Linux, make sure the system can run gcc 4.4.7.
libc.so.6must be available and it must support the GLIBC_2.3 ABI. You can check this by running the following command: strings libc.so.6 | grep GLIBC_2.Web Policy Agents on Linux systems require a minimum of 135 megabytes of free disk space at all times. If the amount of free space drops below this threshold, a warning similar to the following appears in the
agent.logfile:[Fri Nov 11 10:02:10.138732 2016] [amagent:error] [pid 4350:tid 140545949357888] amagent_init() status: no space left on device [Fri Nov 11 10:02:10.138981 2016] [:emerg] [pid 4350:tid 140545949357888] AH00020: Configuration Failed, exiting am_log_init() free disk space on the system is only 116703232 bytes, required 134900080 bytes
- Microsoft Windows Systems
Before installing the IIS 7 web policy agent on Microsoft IIS 7 or IIS 8, make sure that the optional Application Development component of Web Server (IIS) is installed. In the Windows Server 2012 Server Manager for example, Application Development is a component of Web Server (IIS) | Web Server.
Web Policy Agents on Windows systems require a minimum of 1.07 gigabytes of free disk space at all times. If the amount of free space drops below this threshold, a warning similar to the following appears in the
agent.logfile:2016-11-10 10:12:10.291 +0000 ERROR [10716:9348] am_shm_create(): free disk space on the system is only 528949248 bytes, required 1073627136 bytes 2016-11-10 10:12:10.291 +0000 ERROR [10716:9348] get_memory_segment(): shared memory error: blocks
After making more disk space available, you will need to restart the web policy agent.
Failure to free up disk space and restart the web policy agent may result in errors similar to the following:
2016-11-10 10:19:43.610 +0000 ERROR [3764:9348] OpenAMHttpModule(): agent init for site 1 failed (error: -31)
2.2. Special Requests
If you have a special request regarding support for a combination not listed here, contact ForgeRock at info@forgerock.com.
Chapter 3. Changes and Deprecated Functionality
This chapter covers both major changes to existing functionality, and also deprecated and removed functionality.
3.1. Important Changes to Web Policy Agent Functionality
Procedure to Enable SSL for Windows Agents Changed
Earlier versions of the web policy agents used the
org.forgerock.agents.config.secure.channel.disableproperty to determine whether to use OpenSSL or the native Windows libraries for SSL communications.This property is no longer used and web policy agents 4.1.1 use the native Windows libraries for SSL communications by default. Perform the following steps to enable OpenSSL:
Set the
AM_SSL_SCHANNELenvironment variable tofalseand restart the IIS or Apache server.Ensure the OpenSSL libraries are available. For more information, see "OpenSSL DLL Locations on 32-bit and 64-bit Windows" in the Web Policy Agent Guide or "OpenSSL Libraries Location by Operating System" in the Web Policy Agent Guide .
Changes to the
org.forgerock.agents.config.keepalive.disablePropertyWeb Policy Agents 4.1.1 behave as if the
org.forgerock.agents.config.keepalive.disableproperty is set tofalsewhen notifications are disabled.For more information, see Miscellaneous Custom Properties in the Web Policy Agent Guide.
Incoming request URL no longer showing in the
gotoparameter in CDSSO modeWeb Policy Agents 4.1.1 in CDSSO mode no longer show the incoming request URL in the
gotoparameter when redirecting to AM for authentication.To show the incoming request URL, set the
org.forgerock.agents.config.cdsso.original.url.redirect.paramcustom property to the name of the query parameter that should contain it, such as,mycustomgoto, and the agent will add the new query parameter to the redirection URL.For more information, see Miscellaneous Custom Properties in the Web Policy Agent Guide.
UTF-8 strings in headers are now MIME-encoded
Web Policy Agents now base64-encode UTF-8 strings in headers, then wrap the string as described in RFC 2047:
encoded-word = "=?" charset "?" encoding "?" encoded-text "?="
For example, given a UTF-8 username, such as
ɗëɱø, Web Policy Agents will:Encode the string in base64 format:
yZfDq8mxw7g=.Wrap the base64-encoded string as per RFC 2047:
=?UTF-8?B?yZfDq8mxw7g=?=.
Unencoded URLs are now passed to AM
Web Policy Agents no longer encode paths before passing them to AM for policy evaluation. AM will receive the path with the same formatting as provided by the user agent.
For example, given a URL containing UTF-8 characters, such as
http://www.example.com/bon/café, Web Policy Agents will pass this exact string to AM.AM performs its own URL encoding, so to match the example above the policy would need to be configured with the following as a resource:
http://www.example.com/bon/caf%C3%A9You may need to add additional resource specifiers to handle the raw URL strings that are now passed on from Web Policy Agents 4.1 and newer.
Re-Implemented Properties for Forward Proxy Configuration
Properties for configuring a forward proxy for communication from the web policy agent to AM have been re-implemented. They were previously removed in Web Policy Agent 4.0.0.
For information on the properties, see Forward Proxy Custom Properties in the Web Policy Agent Guide.
New Swap Size Requirements on Solaris 11 x86
Web Policy Agent 4.1 requires that the amount of swap size on Solaris 11 x86 is configured to be at least as large as the amount of available RAM.
32-bit and 64-bit Application Pools Support on IIS
Web Policy Agent 4.1 now supports 32-bit and 64-bit application pools on the same IIS environment.
3.2. Deprecated Functionality
No features are deprecated in this release.
3.3. Removed Functionality
The following agent configuration properties are no longer required:
com.forgerock.agents.nss.shutdowncom.sun.identity.agents.config.profilename
Chapter 4. Web Policy Agents Fixes, Limitations, and Known Issues
4.1. Key Fixes
4.1.1. Key Fixes in 4.1
AMAGENTS-269: For remote audit logining need to be done additional configuration in OpenAM
AMAGENTS-262: Update cookie reset properties to reflect new behaviour of AMAGENTS-247
AMAGENTS-181: Memory leak in case of network connection failure
AMAGENTS-256: Could not find a way to use a client certificate file with IIS
OPENAM-1769: agentadmin should return exit codes other then 0
AMAGENTS-125: "agentadmin.exe --d" command not working
AMAGENTS-223: redirect loop if 'com.sun.identity.agents.config.access.denied.url' is set to absolute URL
OPENAM-8486: WPA interactive installator can't correctly read provided Apache configuration path
OPENAM-8681: RFE: Support com.sun.identity.agents.config.forward.proxy.* in WPA 4
AMAGENTS-32: Audit logging in WPA 4.0.0 includes requests for not enforced URLs
AMAGENTS-47: Agent truncates filtered HTTP POST body
AMAGENTS-95: Improve Agent error handling of AM responses after OPENAM-8910
AMAGENTS-103: Agent4 does not work well with mod_autoindex generated pages
AMAGENTS-105: IIS Agent Crash at read of log variable after destruction by another thread at application pool recycle
AMAGENTS-119: Windows Apache Agent crashes under load when constantly recycled
AMAGENTS-121: Web Agent not updating headers when AM Session Attributes are changed
AMAGENTS-130: IIS agent can crash in get_request_url method
AMAGENTS-132: WPA is not able to recover from XML parser error
AMAGENTS-135: WPA4 running on Schannel might not read complete HTTP response body
AMAGENTS-140: WPA is not using agents.config.polling.interval configuration property
AMAGENTS-147: Agentadmin stops in OpenAM server validation phase
AMAGENTS-164: Agent with remote audit logger enabled and a little more than 4K messages agent will crash
AMAGENTS-173: WPA4 on AIX does not work with a new logger
AMAGENTS-176: WPA4/3.x does not support policy.evaluation.application config property
AMAGENTS-177: WebAgent 4 not enforced URL cannot take path with 'exception'
AMAGENTS-186: first agent process should delete and recreate shared memory files
AMAGENTS-207: Accessing the agent logout URL without session will cause a redirect
AMAGENTS-208: Agent returns HTTP 500 internal error on logout page if com.sun.identity.agents.config.logout.url map is empty
AMAGENTS-209: Notification does not end up removing session from cache if first apache bucket contains less than 6 bytes
AMAGENTS-221: Location response header not set when 'com.sun.identity.agents.config.access.denied.url' is used
AMAGENTS-229: protocol/port/host override don't work with Post Data Preservation
AMAGENTS-257: IIS Agent crash in remove_from_freelist
AMAGENTS-52: WPA on Windows should be able to use Schannel for SSL/TLS communication
AMAGENTS-118: Delayed or missing log file entries possible in certain situations
AMAGENTS-19: IIS agent should support mixed 32 and 64 bit application pools
AMAGENTS-266: Agent recycle shutdown of shared memory occurs before all workers have finished
AMAGENTS-264: Deadly embrace in log buffer handling with IIS recycling
AMAGENTS-248: Agent might crash with misleading error when server is running out of disk space
AMAGENTS-123: CDSSO session token cleared when hitting denied URL
AMAGENTS-214: agent.log is set to debug level and it is not possible to change it
AMAGENTS-193: Web Policy agent overrides Apache access control directives, Need to be documented
AMAGENTS-27: WPA4 needs a configurable option to bypass POST data inspection
AMAGENTS-252: WPA crashes on Solaris 11 if the swap size is not the same as the amount of RAM
OPENAM-8261: Improve documentation of indexed / mapped configuration attributes
OPENAM-3888: Possibility to disable redirect behaviour of the Policy Agents
OPENAM-8904: OpenAM did not follow RFC 2616 and RFC 2047
AMAGENTS-249: IIS Agent crash in purge of expired items or waiting for live readers when cache is shutting down in another thread
AMAGENTS-172: WPA4 does not handle oversized log messages properly
AMAGENTS-169: RFE: Don't depend on Apache's 'pathinfo'
AMAGENTS-93: RFE: file permissions and/or ownership of log files should be configurable
AMAGENTS-42: Percent encoded hash (#) (%23) is handled incorrectly during policy evaluation
AMAGENTS-26: Attributes Processing does not map multiple values
OPENAM-8428: WPA records audit logs to a local file although "Audit Log Location" is set to REMOTE
AMAGENTS-24: Non-enforced URL validation should be lazy
OPENAM-8328: WPA can't recognize custom access-denied page when there is GOTO parameter
AMAGENTS-70: WPA4 Fetch attributes for Not enforced URL not entirely working
AMAGENTS-68: invalid cookie causes 403 instead of redirect to login page
AMAGENTS-246: Performance drop when targeting two agents on single IIS
AMAGENTS-225: Under load remote audit logging produces many content length exceeded messages per batch
AMAGENTS-228: With Remote audit Logging message size should be in sync with OpenAM default acceptable value 16K
AMAGENTS-227: With Remote Audit logging, logging depends on time but not on buffer size which limits performance
AMAGENTS-231: Agent does not log banner message on startup
AMAGENTS-222: agent.conf has the wrong agent version
AMAGENTS-216: Agent is crashing on Windows with more than one worker in application pool
AMAGENTS-211: redirect location is not logged in case of access denied
AMAGENTS-144: Apache http server 2.2 crashes on Linux systems hosted on VirtualBox
AMAGENTS-192: New shared memory deletion code should handle fresh install
AMAGENTS-129: Policy agent crash caused by invalid user_offset in cache file
AMAGENTS-185: Possibility of hanging in ssl handshake when recycling
AMAGENTS-174: WPA4 agentadmin can not complete OpenAM server validation phase
OPENAM-8429: WPA audit log is not rotated when it reaches the size limit
AMAGENTS-133: WPA on Windows should use Schannel as default for its SSL/TLS communication
AMAGENTS-122: Agent Hangs during httpd restart on linux
OPENAM-8947: Web form submitted by a POST request is truncated by the Web Policy agent
OPENAM-8624: It is possible to silently install agent for site which already has one agent configured on Win2012
OPENAM-8656: It is possible to select not existing siteID on installation although installation fails - with no helpful message
AMAGENTS-59: Apache_v24_Linux_64bit_4.0.0 fails to install on Suse 12 SP1
OPENAM-8487: Parameter --changeOwner doesn't work in WPA silent installation
4.2. Limitations
The following limitations and workarounds apply to Web Policy Agent 4.1.1:
The NGINX Plus policy agent does not support the ignore path info properties:
com.sun.identity.agents.config.ignore.path.infocom.sun.identity.agents.config.ignore.path.info.for.not.enforced.list
Apache HTTP Server Authentication Functionality Not Supported
The web agent replaces authentication functionality provided by Apache, for example, the
mod_auth_*modules. Integration with built-in Apache httpd authentication directives, such asAuthName,FilesMatch, andRequireis not supported.
4.3. Known Issues
4.3.1. Known Issues in 4.1
OPENAM-2396: Agents should set 'amlbcookie' when running in CDSSO mode
AMAGENTS-509: 1 CPU used per w3wp process caught in loop in read_retry
AMAGENTS-431: Not Enforced URLs Are Being Protected by Policy Agent 4.x
AMAGENTS-382: Apache 's Error Document does not work on any directories except for document root
AMAGENTS-380: Installer fails with permissions error 0xb7 on IIS
AMAGENTS-357: Installation of IIS Agent with an application pool identity type of SpecificUser results in ACL update status: error
AMAGENTS-349: GET method can change into HEAD due to use of ap_method_name_of
AMAGENTS-322: FastCGI module results in post data missing after processing with agent
AMAGENTS-317: agentadmin --v can report 0.0 memory if there is no access to unistd.h on AIX
AMAGENTS-315: Agent fails to start with insufficient shared memory
AMAGENTS-310: Agents4 add well known port to goto URL when it did not exist in the original URL
AMAGENTS-292: SIGBUS due to alignment issues in hashes on SPARC
AMAGENTS-290: Login redirect loop in CDSSO enabled webagent
AMAGENTS-285: Agent logging LOG_ALLOW or LOG_DENY does not work
AMAGENTS-272: Bug in agent's net_client send/recv handling. It uses builtin/hardcoded AM_NET_POOL_TIMEOUT value of 4 sec
AMAGENTS-268: 'agentadmin --v' does not show OS architecture
AMAGENTS-267: not enforced IP processing broken
AMAGENTS-263: Performance degradation when audit shared memory resizes
AMAGENTS-258: If the Web agent Installation take more than 4 sec , it will throw "error validating OpenAM agent configuration"
AMAGENTS-254: Apache's ErrorDocument does not work with Agents 4.x
AMAGENTS-215: FQDN checking should be turned off by default - Web agent local file
AMAGENTS-178: Invert Not Enforced does not work if Not Enforced URLs list is empty
AMAGENTS-46: 4.x WPA not enforced pattern matching not consistent with 3.x
Chapter 5. Documentation Updates
The following table tracks changes to the documentation set following the release of AM Web Policy Agent 4.1.1:
| Date | Description |
|---|---|
| 2016-09-20 |
Reorganization of web policy agent documentation |
| 2016-12-02 |
4.1.0 Release |
| 2017-05-19 |
Web Policy Agents 4.1 documentation refresh, which includes the following updates:
|
| 2018-01-25 |
Web Policy Agents 4.1 documentation refresh, which includes the following updates:
|
| 2018-05-08 | Added IIS 8.5 to the list of supported platforms for Web Policy Agent 4.1.x. |
Appendix A. Getting Support
For more information or resources about AM and ForgeRock Support, see the following sections:
A.1. Accessing Documentation Online
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.
A.2. Using the ForgeRock.org Site
The ForgeRock.org site has links to source code for ForgeRock open source software, as well as links to the ForgeRock forums and technical blogs.
If you are a ForgeRock customer, raise a support ticket instead of using the forums. ForgeRock support professionals will get in touch to help you.
A.3. Getting Support and Contacting ForgeRock
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.