<?xml version="1.0" encoding="UTF-8"?>

<chapter xml:id='chap-web-agents'

xmlns='http://docbook.org/ns/docbook' version='5.0' xml:lang='en'

xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'

xsi:schemaLocation='http://docbook.org/ns/docbook

xmlns:xlink='http://www.w3.org/1999/xlink'>

<title>Web Policy Agents ${agentsDocTargetVersion}</title>

<para>

This chapter concerns OpenAM web policy agents.

Web policy agents run in web servers and protect access to web pages.

</para>

<section xml:id="what-new-web-agents">

<title>New in Web Policy Agents ${agentsDocTargetVersion}</title>

<para>

No new features have been added since the release of 3.3.0.

</para>

</section>

<section xml:id="product-documentation">

<title>OpenAM Web Policy Agent Documentation</title>

<itemizedlist>

<para>

You can read the following additional

<link xlink:show="new" xlink:href="http://docs.forgerock.org/en/openam-pa/3.3.0/"

>product documentation for OpenAM policy agents 3.3.0</link>

online at <link xlink:show="new" xlink:href="http://docs.forgerock.org/" />.

</para>

<listitem>

<para>

<link xlink:href="http://docs.forgerock.org/en/openam-pa/3.3.0/web-release-notes/"

xlink:show="new">OpenAM Web Policy Agent 3.3.0 Release Notes</link>

</para>

</listitem>

<listitem>

<para>

<link xlink:href="http://docs.forgerock.org/en/openam-pa/3.3.0/web-install-guide/"

xlink:show="new">OpenAM Web Policy Agent 3.3.0 Installation Guide</link></para>

</listitem>

<listitem>

<para>

<link xlink:href="http://docs.forgerock.org/en/openam-pa/3.3.0/web-reference/"

xlink:show="new">OpenAM Web Policy Agent 3.3.0 Reference</link>

</para>

</listitem>

</itemizedlist>

</section>

<section xml:id="before-you-start-web-agents">

<title>Before You Install OpenAM Web Policy Agents</title>

<para>This section covers software and hardware prerequisites for installing

and running OpenAM web policy agents.</para>

<note>

<para>

The content of this section has not changed since the 3.3.0 release.

</para>

</note>

<para>If you have a special request to support a combination not listed here,

contact ForgeRock at <link xlink:href="mailto:info@forgerock.com"

>info@forgerock.com</link>.</para>

<section xml:id="java-requirements-web-agents">

<title>Web Agents Java Requirements</title>

<para> ForgeRock recommends the most recent update of the supported version of

Java to ensure you have the latest security fixes.</para>

<para>All web policy agents except those associated with <!--Varnish Cache and-->

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.</para>

<para>ForgeRock has tested this release with Oracle Java SE JDK.</para>

</section>

<section xml:id="browser-requirements-web-agents">

<title>Web Agents Browsers Tested</title>

<itemizedlist>

<para>ForgeRock has tested this web policy agent release with the following

web browsers.</para>

<listitem><para>Chrome release 16 and later</para></listitem>

<listitem><para>Firefox 3.6 and later</para></listitem>

<listitem><para>Internet Explorer 7 and later</para></listitem>

</itemizedlist>

</section>

<section xml:id="web-server-requirements-web-agents">

<title>Web Server Requirements</title>

<itemizedlist>

<para>Web policy agents support the following web servers.</para>

<listitem>

<para><?eval ${agentApacheSupport}?></para>

</listitem>

<listitem>

<para><?eval ${agentIISSupport}?></para>

</listitem>

<!-- Pending OPENAM-1182

<listitem>

<para><?eval ${agentSunWebServerSupport}?></para>

</listitem>

</itemizedlist>

</section>

<section xml:id="platform-requirements-web-agents">

<title>Web Agents Platform Requirements</title>

<para>Apache HTTP web policy agents have been tested on Linux 2.6 or later,

and on Oracle Solaris 10 or later. Apache HTTP web policy agents require

Apache Portable Runtime 1.3.x or later. You can check your installation by

running <command>httpd -v</command>. On some systems, the packaged version of

Apache HTTP server uses earlier versions of APR that are not compatible with

the current policy web agents.</para>

<para>The Microsoft IIS 6 web policy agent has been tested on Windows Server

2003.</para>

<para>The Microsoft IIS 7 web policy agent has been tested on Windows Server

2008 R2.</para>

<para>The Microsoft IIS 8 web policy agent has been tested on Windows Server

2012.</para>

<para>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.</para>

</section>

<section xml:id="hardware-requirements-web-agents">

<title>Web Agents Hardware Requirements</title>

<para>You can deploy OpenAM web policy agents on any hardware supported for

the combination of software required.</para>

<para>ForgeRock has tested this release on x86 and x64 based systems,

and also on Solaris SPARC systems.</para>

</section>

</section>

<section xml:id="upgrade-install">

<title>Upgrading &amp; Installing Web Policy Agents</title>

<para>

ForgeRock recommends that you update web policy agents to this release.

If you are installing OpenAM web policy agents for the first time,

you can use the same installation instructions as for 3.3.0.

</para>

<procedure xml:id="upgrade-from-earlier-release">

<title>To Upgrade From Web Policy Agents 3.3.0</title>

<step>

<para>

Back up the policy agent installation and configuration directories.

</para>

<para>

Also back up the configuration if it is stored centrally in OpenAM.

</para>

</step>

<step>

<para>

Redirect client traffic away from the protected application.

</para>

</step>

<step>

<para>

Stop the web server where the policy agent is installed.

</para>

</step>

<step>

<para>

Remove the old policy agent as described in the

<link xlink:show="new"

xlink:href="http://docs.forgerock.org/en/openam-pa/3.3.0/web-install-guide/"

><citetitle>Web Policy Agent Installation Guide</citetitle></link>.

</para>

<para>

If the uninstallation process has changed, refer to the version of the

<citetitle>Web Policy Agent Installation Guide</citetitle> that corresponds

to your web policy agent.

</para>

</step>

<step>

<para>

Install the new policy agent using the existing configuration.

</para>

</step>

<step>

<para>

Start the web server where the policy agent is installed.

</para>

<para>

For new features, the policy agent uses the default configuration

until you make changes.

</para>

</step>

<step>

<para>Validate that the policy agent is performing as expected.</para>

</step>

<step>

<para>

Allow client traffic to flow to the protected application.

</para>

</step>

</procedure>

<procedure xml:id="install-fresh">

<title>To Install Web Policy Agents</title>

<para>

If you have not yet installed and configured Web Policy Agents,

then install this release instead of 3.3.0.

</para>

<step>

<para>

Download and unzip the policy agents.

</para>

<para>

Find a link to the OpenAM download page from

<link xlink:show="new" xlink:href="http://forgerock.com/download-stack/" />.

</para>

</step>

<step>

<para>

Follow the instructions in the

<link xlink:href="http://docs.forgerock.org/en/openam-pa/3.3.0/web-install-guide/"

xlink:show="new"

><citetitle>OpenAM Web Policy Agent 3.3.0 Installation Guide</citetitle></link>.

</para>

</step>

</procedure>

</section>

<section xml:id="web-agent-compatibility">

<title>Web Policy Agent Compatibility</title>

<para>

This section concerns OpenAM Web Policy Agents ${agentsDocTargetVersion}.

</para>

<section xml:id="web-agent-major-changes">

<title>Important Changes to Web Policy Agent Functionality</title>

<itemizedlist>

<listitem>

<para>

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.

</para>

<itemizedlist>

<para>

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 to OpenAM 11.0.1 and web policy agents 3.3.1.

</para>

<listitem>

<para>

Policy agents configured to use subtree mode behave

as they did prior to 3.3.0.

</para>

</listitem>

<listitem>

<para>

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

(<link xlink:show="new"

xlink:href="https://bugster.forgerock.org/jira/browse/OPENAM-3509"

>OPENAM-3509</link>,

<link xlink:show="new"

xlink:href="https://bugster.forgerock.org/jira/browse/OPENAM-3667"

>OPENAM-3667</link>).

</para>

<para>

In order to match a trailing slash, your rule must end in a slash,

or a slash followed by a wildcard.

</para>

</listitem>

<listitem>

<para>

When policy agents are configured to use self mode,

trailing wildcards, except after <literal>?</literal>,

match zero or more characters.

</para>

</listitem>

<listitem>

<para>

When policy agents are configured to use self mode,

previously a trailing wildcard after a slash, <literal>/*</literal>,

matched one or more characters, whereas it now matches zero or more.

This means that a resource ending in <literal>/</literal>

previously would not match a rule ending in <literal>/*</literal>,

whereas it now does.

</para>

<para>

If you already have two rules to allow access,

one ending in <literal>/</literal> and the other in <literal>/*</literal>,

then you have nothing to do.

Only the latter rule is now required.

</para>

<para>

If however you have only rules ending in <literal>/*</literal>

and intend these to deny access to resources ending in <literal>/</literal>,

then add rules ending in <literal>/</literal>

specifically to deny access to resources ending in <literal>/</literal>.

</para>

</listitem>

<listitem>

<para>

When web policy agents are configured to use self mode,

trailing wildcards after <literal>?</literal>

match <emphasis>one</emphasis> or more characters.

This means that a resource with a trailing <literal>?</literal>

no longer matches a rule of the form <literal>/*?*</literal>,

whereas it would have matched with earlier versions.

</para>

<para>

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 <literal>/*?</literal>

before you upgrade OpenAM.

</para>

</listitem>

</itemizedlist>

<para>

This is the only compatibility change since release 3.3.0.

</para>

</listitem>

<listitem>

<para>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.</para>

<para>The cleanest upgrade path is to uninstall the previous version of

the IIS agent, and then install the new version of the IIS agent.</para>

</listitem>

<listitem>

<para>The IIS web policy agents no longer depend on third-party libraries.

They are now built and shipped as single Dynamic-Link Libraries (DLLs). </para>

</listitem>

<listitem>

<para>The IIS 6 agent, installed on older versions (pre R2) of Windows 2003,

may require the installation of Microsoft Core XML Services (MSXML) 6.0 and

any applicable service packs and updates. The IIS7 agent also requires

MSXML 6.0 or above. For installation instructions, see the <link xlink:show="new"

xlink:href="http://www.microsoft.com/en-us/download/details.aspx?id=3988"

><citetitle>Microsoft Download Center page for MSXML 6.0</citetitle></link>.</para>

</listitem>

<listitem>

<para>When SSL is used, the Linux/Solaris agents no longer include independent

NSS/NSPR libraries. They rely on the libraries included in the OS native

<filename>libxml2</filename> and <filename>openssl</filename> packages.

The package names may vary slightly, depending on release / distribution.</para>

</listitem>

<listitem>

<para>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,

<literal>com.forgerock.agents.ext.url.validation.level</literal>.</para>

</listitem>

<listitem>

<para>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.</para>

<para>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.</para>

<para>For web policy agents, set

<literal>com.sun.identity.agents.config.fetch.from.root.resource=false</literal>.</para>

</listitem>

</itemizedlist>

</section>

<section xml:id="web-agent-deprecated">

<title>Deprecated Functionality</title>

<para>

Support for Microsoft IIS 6 is deprecated,

and likely to be removed in a future release.

</para>

</section>

<section xml:id="web-agent-removed">

<title>Removed Functionality</title>

<itemizedlist>

<listitem>

<para>The web policy agent bootstrap property

<literal>com.forgerock.agents.ext.url.validation.disable</literal>

introduced in release 3.1.0 has been superseded by the bootstrap property

<literal>com.forgerock.agents.ext.url.validation.level</literal>.</para>

</listitem>

<listitem>

<para>Web policy agent support for Apache HTTP Server 2.0 is no longer

provided in this release.</para>

</listitem>

<listitem>

<para>Web policy agent support for Oracle iPlanet Web Proxy Server

(formerly Sun Java System Web Sun Proxy Server) is no longer provided

in this release.</para>

</listitem>

</itemizedlist>

</section>

</section>

<section xml:id="web-agent-issues">

<title>Web Policy Agents Fixes, Limitations, &amp; Known Issues</title>

<important>

<para>

OpenAM web policy agents 3.3.1 together with OpenAM 11.0.1

address backward compatibility with earlier agents.

For details, make you read <xref linkend="web-agent-major-changes" />.

</para>

</important>

<para>

OpenAM web policy agent issues are tracked at

<link xlink:show="new"

xlink:href="https://bugster.forgerock.org/jira/browse/OPENAM" />.

</para>

<section xml:id="web-agent-fixes">

<title>Key Fixes</title>

<para>

The following bugs were fixed in release ${agentsDocTargetVersion}.

For details, see the

<link xlink:show="new"

xlink:href="https://bugster.forgerock.org/jira/browse/OPENAM"

>OpenAM issue tracker</link>.

</para>

<!-- List generated at 11:09:58 20140227 using http://bugster.forgerock.org/jira/rest/api/2/search?jql=project+%3D+OpenAM+AND+component+%3D+"web+agents"+AND+fixVersion+%3D+"Agents-3.3.1"+AND+resolution+%3D+Fixed+AND+labels+%3D+release-notes&startAt=0&maxResults=500&fields=summary-->

<itemizedlist>

<listitem><para><link xlink:href="https://bugster.forgerock.org/jira/browse/OPENAM-3667" xlink:show="new">OPENAM-3667</link>: Agent removes trailing / from the URL</para></listitem>

<listitem><para><link xlink:href="https://bugster.forgerock.org/jira/browse/OPENAM-3334" xlink:show="new">OPENAM-3334</link>: WPA might crash when REST service returns com.sun.identity.idsvcs.GeneralFailure exception</para></listitem>

<listitem><para><link xlink:href="https://bugster.forgerock.org/jira/browse/OPENAM-3215" xlink:show="new">OPENAM-3215</link>: Apache Web Agents do not handle notifications - OS independent issue</para></listitem>

</itemizedlist>

</section>

<section xml:id="web-agent-limitations">

<title>Limitations</title>

<itemizedlist>

<listitem>

<para>Web policy agents for IIS do not support Web gardens nor

multi-process mode.</para>

</listitem>

<listitem>

<para>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

<filename>/path/to/web_agents/apache2x_agent/lib</filename> directory.

SELinux expects most library files to be configured with a

<literal>lib_t</literal> label; you can set that up with the

<command>chcon -t lib_t /path/to/web_agents/apache2x_agent/lib/*.so</command>

and <command>semanage fcontext -a -t lib_t /path/to/web_agents/apache2x_agent/lib/*.so</command>

commands.</para>

</listitem>

</itemizedlist>

</section>

<section xml:id="web-agent-known-issues">

<title>Known Issues</title>

<para>

The following important known issues remained open

at the time release ${agentsDocTargetVersion} became available.

For details and information on other issues, see the

<link xlink:show="new"

xlink:href="https://bugster.forgerock.org/jira/browse/OPENAM"

>OpenAM issue tracker</link>.

</para>

<!-- List generated at 15:27:51 20140225 using http://bugster.forgerock.org/jira/rest/api/2/search?jql=project+%3D+OpenAM+AND+component+%3D+"web+agents"+AND+resolution+%3D+Unresolved+AND+labels+%3D+release-notes&startAt=0&maxResults=500&fields=summary-->

<itemizedlist>

<listitem><para><link xlink:href="https://bugster.forgerock.org/jira/browse/OPENAM-2974" xlink:show="new">OPENAM-2974</link>: agentadmin should allow to configure multiple instances for the same agent on the same host</para></listitem>

<listitem><para><link xlink:href="https://bugster.forgerock.org/jira/browse/OPENAM-1927" xlink:show="new">OPENAM-1927</link>: Silent Installation does not work for Apache2.4/Suse11</para></listitem>

<listitem><para><link xlink:href="https://bugster.forgerock.org/jira/browse/OPENAM-1889" xlink:show="new">OPENAM-1889</link>: Sun Web Server policy agent: Wrong password in combination with naming service failover causes internal error on OpenAM</para></listitem>

<listitem><para><link xlink:href="https://bugster.forgerock.org/jira/browse/OPENAM-1521" xlink:show="new">OPENAM-1521</link>: Cookie Hijacking Prevention does not work properly under FireFox</para></listitem>

<listitem><para><link xlink:href="https://bugster.forgerock.org/jira/browse/OPENAM-1520" xlink:show="new">OPENAM-1520</link>: Apache 2.2 WPA 3.0.4.5 causes Apache to hang</para></listitem>

<listitem><para><link xlink:href="https://bugster.forgerock.org/jira/browse/OPENAM-1503" xlink:show="new">OPENAM-1503</link>: Cookies configured in OpenAM not reset after logout</para></listitem>

<listitem><para><link xlink:href="https://bugster.forgerock.org/jira/browse/OPENAM-889" xlink:show="new">OPENAM-889</link>: Agent should recover if the admin session gets invalid</para></listitem>

<listitem><para><link xlink:href="https://bugster.forgerock.org/jira/browse/OPENAM-404" xlink:show="new">OPENAM-404</link>: Policy agent should remove duplicate response headers</para></listitem>

<listitem><para><link xlink:href="https://bugster.forgerock.org/jira/browse/OPENAM-308" xlink:show="new">OPENAM-308</link>: IIS6 Policy Web Agent doesn't support multiple sites correctly</para></listitem>

</itemizedlist>

</section>

</section>

</chapter>