Notes covering prerequisites, fixes, known issues for OpenAM web policy agents. OpenAM provides open source Authentication, Authorization, Entitlement and Federation software.
Chapter 1. Web Policy Agents 3.3
1.1. What's New
1.1.1. Major New Features in Web Policy Agents 3.3.0
Important
This release contains fixes that resolve security issues within web policy agents. It is strongly recommended that you update to this release to make your deployment more secure, and to take advantage of important functional fixes. ForgeRock customers can contact support for help and further information.
All of the web policy agents have been updated to include support for Internet Protocol version 6 (IPv6) support, in addition to support for IPv4.
Web policy agents now encrypt the value of the
com.sun.identity.agents.config.certdb.passwordproperty (OPENAM-2479).Web policy agents debug logs now show the full REST URL accessed during the bootstrap process (OPENAM-2397).
Web policy agents can perform naming URL validation during the bootstrap phase, and can fail over from one OpenAM service to another (OPENAM-1258, OPENAM-1270). Configure these capabilities by using the following bootstrap properties.
com.forgerock.agents.ext.url.validation.default.url.setIndicates order of service URLs for failover
com.forgerock.agents.ext.url.validation.levelControls the extent of naming URL validation
com.forgerock.agents.ext.url.validation.ping.intervalSets seconds between validation requests against the naming URL
com.forgerock.agents.ext.url.validation.ping.miss.countSets threshold of validation failures after which to fail over
com.forgerock.agents.ext.url.validation.ping.ok.countSets threshold of validation successes after which to fail back to the first URL in the
default.url.setlist
See Section 1.1, "Bootstrap Configuration Properties" in the OpenAM Web Policy Agent 3.3 Reference for details.
Web policy agents now allow you to configure the naming of the URL validation net-connect timeout (OPENAM-1257).
Web policy agents now support IPv6 for notenforced IP addresses (OPENAM-1256).
A web policy agent is now available for Apache HTTPD Server 2.4 (OPENAM-1195).
Web policy agents now let you enable and disable Cache-Control headers for unauthenticated sessions (OPENAM-1087).
Web policy agents now let you preserve POST data when working with URI-based load balancing (OPENAM-980).
Web policy agents now let you configure whether to do an HTTP 302 redirect after processing the LARES POST (OPENAM-936).
Web policy agents now let you configure whether to URL encode the session cookie sent with the LARES POST using the boolean property
com.forgerock.agents.cdsso.cookie.urlencode(OPENAM-915).Web policy agents can now conditionally redirect users based on the incoming request URL (OPENAM-849).
Web policy agents now support the Expires attribute on cookies (OPENAM-815).
Web policy agents can now mark persistent cookies as HTTPOnly, to prevent scripts and third-party programs from accessing the cookies (OPENAM-804).
The IIS 7 web policy agents now has support for HTTP Basic authentication and password replay, thereby better supporting Microsoft OWA and SharePoint (OPENAM-773).
Web policy agents now allow use of regular expressions in Not Enforced URLs (OPENAM-772). In addition, regular expressions are supported for logout URLs and for rejecting access to invalid URLs.
Web policy agents can now forward injected attributes to Not Enforced URLs (OPENAM-770). Set
com.sun.identity.agents.config.notenforced.url.attributes.enable=truein the web policy agent profile as described in Section 1.2, "Agent Configuration Properties" in the OpenAM Web Policy Agent 3.3 Reference.
1.1.2. Major New Features in Web Policy Agents 3.3.1
No new features have been added since the release of 3.3.0.
1.1.3. Major New Features in Web Policy Agents 3.3.3
No new features have been added since the release of 3.3.1.
1.1.4. Major New Features in Web Policy Agents 3.3.4
Web Policy Agents 3.3.4 is a maintenance release that resolves a number of issues, including security issues.
It is strongly recommended that you update to this release to make your deployment more secure, and to take advantage of important functional fixes.
ForgeRock customers can contact support for help and further information.
The following new settings have been added to this release:
OPENAM-4265. Improved IIS site support. If the agent module is enabled for a site that does not have a corresponding
Instance_{siteid}directory, the request will not be interrupted by the agent and will continue to other IIS modules, including.net. For more information, see OPENAM-4265.OPENAM-4888. Introduces one new setting in the bootstrap file:
com.forgerock.agents.nss.shutdown = on | off. Default ison(not set) and indicates that the agent tries to close NSS connections. For more information, see OPENAM-4888.
1.2. Before You Install Web Policy Agents
This section covers software and hardware prerequisites for installing and running Web Policy Agents.
1.2.1. Web Agents Java Requirements
ForgeRock recommends the most recent update of the supported version of Java to ensure you have the latest security fixes.
All web policy agents except those associated with Microsoft IIS require a Java 6 or 7 runtime environment for installation. ForgeRock recommends the most recent update of Java 6 or 7 to ensure you have the latest security fixes.
ForgeRock has tested this release with Oracle Java SE JDK.
1.2.2. Web Agents Browsers Tested
ForgeRock has tested this web policy agent release with the following web browsers.
Chrome release 16 and later
Firefox 3.6 and later
Internet Explorer 7 and later
1.2.3. Web Server Requirements
Web policy agents support the following web servers.
Apache HTTP Server 2.2, 2.4
Microsoft IIS 7, 8
Oracle iPlanet Web Server 7.0 (also known as Sun Web Server)
1.2.4. Web Agents Platform Requirements
Apache HTTP web policy agents run on Linux 2.6.18 or later, and on Oracle Solaris 10 or later.
The Microsoft IIS 7 Web Policy Agent has been tested on Windows Server 2008 R2.
The Microsoft IIS 8 Web Policy Agent has been tested on Windows Server 2012.
Before installing web policy agents on Linux, make sure the system can run gcc 4.4.7. Also
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. Also, libstdc++.so.6 must be available and it must supportGLIBCXX_3.4andCXXABI_1.3. You can check this by running the following commands:strings libstdc++.so.6 | grep GLIBCXX_3andstrings libstdc++.so.6 | grep CXXABI_1.Before installing web policy agents on Solaris 10, make sure you have applied the latest shared library patch for C++, at least 119963-16 on SPARC, or 119964-12 on x86.
1.2.5. Web Agents Hardware Requirements
You can deploy Web Policy Agents on any hardware supported for the combination of software required.
ForgeRock has tested this release on x86 and x64 based systems, and also on Solaris SPARC systems.
1.2.6. Special Requests
If you have a special request regarding support for a combination not listed here, contact ForgeRock at info@forgerock.com.
1.3. Upgrading & Installing Web Policy Agents
ForgeRock recommends that you update web policy agents to this release. If you are installing Web Policy Agents for the first time, you can use the same installation instructions as for 3.3.0.
Back up the policy agent installation and configuration directories.
Also back up the configuration if it is stored centrally in OpenAM.
Redirect client traffic away from the protected application.
Stop the web server where the policy agent is installed.
Remove the old policy agent as described in the Web Policy Agent Installation Guide.
If the uninstallation process has changed, refer to the version of the Web Policy Agent Installation Guide that corresponds to your web policy agent.
Install the new policy agent using the existing configuration.
Start the web server where the policy agent is installed.
For new features, the policy agent uses the default configuration until you make changes.
Validate that the policy agent is performing as expected.
Allow client traffic to flow to the protected application.
If you have not yet installed and configured Web Policy Agents, then install this release instead of 3.3.0.
Download and unzip the policy agents.
Find a link to the OpenAM download page from http://forgerock.com/download-stack/.
Follow the instructions in the OpenAM Web Policy Agent 3.3.0 Installation Guide.
1.4. Web Policy Agent Compatibility
This chapter covers both major changes to existing functionality, and also deprecated and removed functionality.
1.4.1. Important Changes to Web Policy Agent Functionality
The following functionality has been changed in Web Policy Agents 3.3:
1.4.1.1. Important Changes to Functionality in Web Policy Agents 3.3.0
IIS web policy agents no longer rely on the Windows registry to determine where to find configuration settings. Instead, IIS agents determine the relative location of their configuration properties files based on the location of the web policy agent DLL, and on the Site ID set by IIS at runtime.
The cleanest upgrade path is to uninstall the previous version of the IIS agent, and then install the new version of the IIS agent.
Naming URL validation was introduced after release 3.0.4. The initial implementation of naming URL validation for web policy agents enabled validation by default. Naming URL validation is now fully disabled by default. You can adjust this setting by using the bootstrap configuration property,
com.forgerock.agents.ext.url.validation.level.The default policy evaluation mode for new policy agent profiles is now self rather than subtree, in order to better scale for large numbers of policy rules.
Upgrade does not change existing policy agent profile configurations, however. If you want to adopt the new default setting for existing policy agents, you must change the setting manually.
For web policy agents, set
com.sun.identity.agents.config.fetch.from.root.resource=false.
1.4.1.2. Important Changes to Functionality in Web Policy Agents 3.3.1
Consistency has been improved in how OpenAM policy rules match resources. Policy rules are now interpreted more consistently in line with the documentation, and more consistently across platforms and across self and subtree modes. Before you upgrade, consider how these changes affect policy rules.
Although the changes introduced by the improvements affect mainly edge cases, they do impact deployments relying on previous, inconsistent behaviors. The following points describe how OpenAM and policy agents behave following upgrade from OpenAM 11.0.0 and web policy agents 3.3.0 to OpenAM 11.0.1 and web policy agents 3.3.1 or later.
Policy agents configured to use subtree mode behave as they did prior to 3.3.0.
If you created your policies with OpenAM 11.0.0 and web policy agents 3.3.0, then note that trailing slashes are no longer stripped from resource names (OPENAM-3509, OPENAM-3667).
In order to match a trailing slash, your rule must end in a slash, or a slash followed by a wildcard.
When policy agents are configured to use self mode, trailing wildcards, except after
?, match zero or more characters.When policy agents are configured to use self mode, previously a trailing wildcard after a slash,
/*, matched one or more characters, whereas it now matches zero or more. This means that a resource ending in/previously would not match a rule ending in/*, whereas it now does.If you already have two rules to allow access, one ending in
/and the other in/*, then you have nothing to do. Only the latter rule is now required.If however you have only rules ending in
/*and intend these to deny access to resources ending in/, then add rules ending in/specifically to deny access to resources ending in/.When web policy agents are configured to use self mode, trailing wildcards after
?match one or more characters. This means that a resource with a trailing?no longer matches a rule of the form/*?*, whereas it would have matched with earlier versions.To match the behavior of previous releases, when using self mode with resources having empty query strings, add additional rules without trailing wildcards as in
/*?before you upgrade OpenAM.
This is the only compatibility change since release 3.3.0.
1.4.1.3. Important Changes to Functionality in Web Policy Agents 3.3.3
On Linux, library requirements have changed. Make sure the system can run gcc 4.4.7. Also
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. Also, libstdc++.so.6 must be available and it must supportGLIBCXX_3.4andCXXABI_1.3. You can check this by running the following commands:strings libstdc++.so.6 | grep GLIBCXX_3andstrings libstdc++.so.6 | grep CXXABI_1.
1.4.1.4. Important Changes to Functionality in Web Policy Agents 3.3.4
OPENAM-4265 introduces improved IIS site support. If the agent module is enabled for a site that does not have a corresponding
Instance_{siteid}directory, the request will not be interrupted by the agent and will continue to other IIS modules, including.net.This change however does not add support for multiple sites and/or multiple processes in IIS. We only support one configuration/site per agent dll (instance). Also, directories should be removed from the
web_agentsdirectory.OPENAM-4629 introduces two net settings. The first is
com.forgerock.agents.init.retry.wait, which sets the wait time (in seconds) between retries. Default (not set) value is 0.The second setting is
com.forgerock.agents.init.retry.wait, which sets the wait time (in seconds) between retries. Default (not set) value is 0.Set these properties to non-zero to have the Agents retry connecting to OpenAM on startup.
Note that if
Hot-Swap Enabled = no, then both properties have no value.OPENAM-4888 introduces one new setting in the bootstrap file:
com.forgerock.agents.nss.shutdown = on | off. Default ison(not set) and indicates that the agent tries to close NSS connections.
1.4.2. Deprecated Functionality
Support for Microsoft IIS 6 is deprecated, and likely to be removed in a future release.
1.4.3. Removed Functionality
The web policy agent bootstrap property
com.forgerock.agents.ext.url.validation.disableintroduced in release 3.1.0 has been superseded by the bootstrap propertycom.forgerock.agents.ext.url.validation.level.Web policy agent support for Apache HTTP Server 2.0 is no longer provided in this release.
Web policy agent support for Oracle iPlanet Web Proxy Server (formerly Sun Java System Web Proxy Server) is no longer provided in this release.
1.5. Web Policy Agents Fixes, Limitations, & Known Issues
This chapter covers the status of key issues and limitations at release of Web Policy Agents.
1.5.1. Key Fixes
The following bugs were fixed in Web Policy Agents 3.3. For details, see the OpenAM issue tracker.
1.5.1.1. Key Fixes in Web Policy Agents 3.3.0
OPENAM-3062: WebAgents do not handle notifications - caches not being flushed
OPENAM-2952: WPA might crash in conditional login parser module
OPENAM-2898: WPA does not set Expires attribute in all cookie reset modules
OPENAM-2741: Web policy agent is not clearing profile/session/response headers and cookies
OPENAM-2706: IIS is crashed by using one level wildcard to not enforced URL list
OPENAM-2457: IIS7 policy agent might crash inside request header modifier
OPENAM-2244: Web Policy Agent might crash inside its reference counted pointer implementation
OPENAM-2182: Apache PA will crash when Post Data Preservation is enabled and POST data is empty
OPENAM-2135: IIS and SJSWS policy agents should not require Host header as per HTTP/1.0 specification
OPENAM-2125: IIS7 policy agent might crash reading POST data
OPENAM-1838: IIS7 policy agent might crash when HOST header is not available
OPENAM-1673: IIS6 policy agent crash on IIS application pool restart
OPENAM-1568: Apache Policy Agent on Windows crash inside NSS/NSPR cleanup
OPENAM-1541: Policy Agents need to be consistent in HTTP response codes when post data preservation cache entry is expired (or not available)
OPENAM-1523: Policy Agent fails to locate OpenAM server cookie value
OPENAM-1510: Policy Agent may crash with remote audit log enabled
OPENAM-1448: IIS6 policy agent returns http 415 error when used with SOAP web-services and custom headers
OPENAM-1344: Wrong library being loaded by Apache 2.4 policy agent
OPENAM-1339: Empty audit log message for Windows policy agents
OPENAM-1271: webagent namingUrl validation fails if datastore auth module is not configured within auth-chain of agent realm
OPENAM-1264: OpenAM Web Agent crashes while cleaning Agent Config
OPENAM-1208: IIS6 policy agent stuck in a loop on a session refresh advice
OPENAM-1190: IIS6 policy agent erroneously overwrites http headers
OPENAM-1178: IIS6 policy agent does not set proper status code on 403/500 responses in IIS6 log
OPENAM-1176: memory leaks in libamsdk
OPENAM-1166: IIS6 policy agent does not set Content-Type on redirect
OPENAM-1159: IIS7 policy agent crash on unresolvable naming service hostname
OPENAM-1118: Policy agent on Linux core dumps on disabled or invalid notifications
OPENAM-1099: IIS7 policy agent crash on empty LARES response
OPENAM-1015: "Invalid pointer" in agent's cleanup_properties()
OPENAM-1011: IIS7 agent unneeded logging fills up agent log file
OPENAM-845: Semicolon (;) appended to HTTP_HEADER values in IIS7 agent after implementing fix for OPENAM-437
OPENAM-834: logout url functionality not working as expected
OPENAM-693: PA should not SIGSEGV if the agent configuration is invalid
OPENAM-690: Unprotected IIS Websites Stopped Working
OPENAM-672: IIS crashes with WebAgent
OPENAM-618: Agent for multi-process servers fails if OpenAM is running in SSL mode with NSPR error -8023
OPENAM-617: Invalid properties in the agent profile causes the PA to SIGSEGV
OPENAM-329: Apache 2.2 stop responding when debug log rotation is enabled in Policy Agent
1.5.1.2. Key Fixes in Web Policy Agents 3.3.1
Important
Starting with policy agents version 3.3.1 and OpenAM version 11.0.1, Web Policy Agents address backward compatibility with earlier agents. For details, make sure that you read Section 1.4.1, "Important Changes to Web Policy Agent Functionality".
OPENAM-3667: Agent removes trailing / from the URL
OPENAM-3334: WPA might crash when REST service returns com.sun.identity.idsvcs.GeneralFailure exception
OPENAM-3215: Apache Web Agents do not handle notifications - OS independent issue
1.5.1.3. Key Fixes in Web Policy Agents 3.3.3
OPENAM-4391: WPA does not remove consecutive forward slashes from request URI resulting in invalid policy evaluations
OPENAM-4390: WPA might fail to sort (reorder) query parameters resulting in invalid policy evaluation
OPENAM-4048: Web policy agent might fail to parse request url when pathinfo is found in uri string (with pathinfo removed)
OPENAM-2969: Basic policy to allow HTTP GET fails on root resource
1.5.1.4. Key Fixes in Web Policy Agents 3.3.4
OPENAM-889: Agent should recover if the agent session gets invalid
OPENAM-3325: IIS7 PA might crash when logout url is not available
OPENAM-3692: WPA build script should not depend on products.xml
OPENAM-4166: Notification queue processor does not start in custom apache mpm configuration
OPENAM-4265: Support for multiple app pools within a single IIS site/server instance
OPENAM-4285: WPA local audit log file is not rotating
OPENAM-4414: Apache Policy Agent does not complete cleanup / logout
OPENAM-4428: IIS7 WPA post data preservation module does not return HTTP 501 error for POST with invalid Content-Type
OPENAM-4629: Web policy agent 3.3.3 fails to connect to OpenAM when http starts first, doesn't continuously try to reconnect
OPENAM-4851: SJSWS WPA notification processor exits with incorrect SAF exit code
OPENAM-4888: Apache WPA might fail to recycle its worker process when any other Apache HTTPD module is using NSS/NSPR
OPENAM-5068: WPA ignores notenforced.url.attributes.enable parameter while clearing http headers/cookies
OPENAM-5288: WPA might fail to connect to IPv6 only host with PR_ADDRESS_NOT_AVAILABLE_ERROR error
1.5.2. Limitations
Web policy agents for IIS do not support Web gardens nor multi-process mode.
If you are running an Apache Web agent on RHEL 6 (CentOS 6), and are also running SELinux in enforcing mode, Apache may fail to restart with a 'Permission denied' message, with a pointer to a file in the
/path/to/web_agents/apache2x_agent/libdirectory.SELinux expects most library files to be configured with a
lib_tlabel; you can set that up with thechcon -t lib_t /path/to/web_agents/apache2x_agent/lib/*.soandsemanage fcontext -a -t lib_t /path/to/web_agents/apache2x_agent/lib/*.socommands.
1.5.3. Known Issues
The following important known issues remained open at the time each release became available. For details and information on other issues, see the OpenAM issue tracker.
1.5.3.1. Known Issues in Web Policy Agents 3.3.0
OPENAM-3257: Web Agent denies access to all resources after accessing root resource multiple times
OPENAM-2974: agentadmin should allow to configure multiple instances for the same agent on the same host
OPENAM-2969: Basic policy to allow HTTP GET fails on root resource
OPENAM-2471: IIS/SJSWS agent enforces access to agent logout URL
OPENAM-1927: Silent Installation does not work for Apache2.4/Suse11
OPENAM-1889: Sun Web Server policy agent: Wrong password in combination with naming service failover causes internal error on OpenAM
OPENAM-1521: Cookie Hijacking Prevention does not work properly under FireFox
OPENAM-1520: Apache 2.2 WPA 3.0.4.5 causes Apache to hang
OPENAM-1503: Cookies configured in OpenAM not reset after logout
OPENAM-889: Agent should recover if the admin session gets invalid
OPENAM-404: Policy agent should remove duplicate response headers
OPENAM-308: IIS6 Policy Web Agent doesn't support multiple sites correctly
1.5.3.2. Known Issues in Web Policy Agents 3.3.1
OPENAM-2974: agentadmin should allow to configure multiple instances for the same agent on the same host
OPENAM-1927: Silent Installation does not work for Apache2.4/Suse11
OPENAM-1889: Sun Web Server policy agent: Wrong password in combination with naming service failover causes internal error on OpenAM
OPENAM-1521: Cookie Hijacking Prevention does not work properly under FireFox
OPENAM-1520: Apache 2.2 WPA 3.0.4.5 causes Apache to hang
OPENAM-1503: Cookies configured in OpenAM not reset after logout
OPENAM-889: Agent should recover if the admin session gets invalid
OPENAM-404: Policy agent should remove duplicate response headers
OPENAM-308: IIS6 Policy Web Agent doesn't support multiple sites correctly
1.5.3.3. Known Issues in Web Policy Agents 3.3.3
OPENAM-2974: agentadmin should allow to configure multiple instances for the same agent on the same host
OPENAM-1927: Silent Installation does not work for Apache2.4/Suse11
OPENAM-1889: Sun Web Server policy agent: Wrong password in combination with naming service failover causes internal error on OpenAM
OPENAM-1521: Cookie Hijacking Prevention does not work properly under FireFox
OPENAM-1520: Apache 2.2 WPA 3.0.4.5 causes Apache to hang
OPENAM-1503: Cookies configured in OpenAM not reset after logout
OPENAM-889: Agent should recover if the admin session gets invalid
OPENAM-404: Policy agent should remove duplicate response headers
OPENAM-308: IIS6 Policy Web Agent doesn't support multiple sites correctly
1.5.3.4. Known Issues in Web Policy Agents 3.3.4
OPENAM-4360: WPA does not create agent profile automatically when OpenAM is running with HTTPS
OPENAM-3875: 'Encode URL's Special Characters' in Web Agent does not consistently encode the / charater
OPENAM-2974: agentadmin should allow to configure multiple instances for the same agent on the same host
OPENAM-1927: Silent Installation does not work for Apache2.4/Suse11
OPENAM-1889: Sun Web Server policy agent: Wrong password in combination with naming service failover causes internal error on OpenAM
OPENAM-1521: Cookie Hijacking Prevention does not work properly under FireFox
OPENAM-1520: Apache 2.2 WPA 3.0.4.5 causes Apache to hang
OPENAM-1503: Cookies configured in OpenAM not reset after logout
OPENAM-404: Policy agent should remove duplicate response headers
OPENAM-308: IIS6 Policy Web Agent doesn't support multiple sites correctly
1.6. Documentation Updates
The following table tracks changes to the documentation set following the release of Web Policy Agents 3.3:
| Date | Description |
|---|---|
| 2013-11-08 |
Initial release of Web Policy Agents 3.3.0. |
| 2014-04-28 |
Maintenance release of Web Policy Agents 3.3.1. |
| 2014-08-29 |
Maintenance release of Web Policy Agents 3.3.3. |
| 2015-02-25 |
Maintenance release of Web Policy Agents 3.3.4. |
| 2016-04-13 |
Reorganization of Web Policy Agents 3.3 documentation, combining 3.3.0, 3.3.1, 3.3.3 and 3.3.4 release notes. |
Chapter 2. How to Report Problems & Provide Feedback
If you have questions regarding OpenAM policy agents which are not answered by the documentation, there is a mailing list which can be found at https://lists.forgerock.org/mailman/listinfo/openam where you are likely to find an answer.
If you have found issues or reproducible bugs within OpenAM 3.3 policy agents, report them in https://bugster.forgerock.org.
When requesting help with a problem, include the following information:
Description of the problem, including when the problem occurs and its impact on your operation
Description of the environment, including the following information:
Machine type
Operating system and version
Web server or container and version
Java version
OpenAM policy agent and version
Any patches or other software that might be affecting the problem
Steps to reproduce the problem
Any relevant access and error logs, stack traces, or core dumps
Chapter 3. Support
You can purchase OpenAM support subscriptions and training courses from ForgeRock and from consulting partners around the world and in your area. To contact ForgeRock, send mail to info@forgerock.com. To find a partner in your area, see http://forgerock.com/partners/find-a-partner/.