<?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 http://docbook.org/xml/5.0/xsd/docbook.xsd'

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

xmlns:xinclude='http://www.w3.org/2001/XInclude'>

<title>Web Policy Agents <?eval ${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 <?eval ${webAgentsDocTargetVersion}?></title>

<itemizedlist>

<listitem>

<para>A new web policy agent, Varnish, has been added. Varnish is a unique policy

agent that does not require the Java environment and it has a unique set of

instructions for the agentadmin command. Varnish also uses a directory

called vmods. This is the location where you will need to handle any required

installation or Varnish updates, and it requires the user to have administrative

rights to update this directory for changes to take effect.</para>

</listitem>

<listitem>

<para>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. <!--include in the notes when

AME-1134 is closed, which includes removing unused libraries.--></para>

<para>IPv6 replaces IPv4 to fix the problems of IPv4 address exhaustion. The new

protocol version increases the number of available internet addresses by using

128-bit addresses instead of the 32-bit addresses of IPv4.</para>

</listitem>

<listitem>

<variablelist>

<para>Web policy agents can perform naming URL validation during the

bootstrap phase, and can fail over from one OpenAM service to another

(<link xlink:href="https://bugster.forgerock.org/jira/browse/OPENAM-1258"

xlink:show="new">OPENAM-1258</link>). Configure these capabilities by

using the following bootstrap properties.</para>

<varlistentry>

<term><literal>com.forgerock.agents.ext.url.validation.default.url.set</literal></term>

<listitem>

<para>Indicates order of service URLs for failover</para>

</listitem>

</varlistentry>

<varlistentry>

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

<listitem>

<para>Controls the extent of naming URL validation</para>

</listitem>

</varlistentry>

<varlistentry>

<term><literal>com.forgerock.agents.ext.url.validation.ping.interval</literal></term>

<listitem>

<para>Sets seconds between validation requests against the naming URL</para>

</listitem>

</varlistentry>

<varlistentry>

<term><literal>com.forgerock.agents.ext.url.validation.ping.miss.count</literal></term>

<listitem>

<para>Sets threshold of validation failures after which to fail over</para>

</listitem>

</varlistentry>

<varlistentry>

<term><literal>com.forgerock.agents.ext.url.validation.ping.ok.count</literal></term>

<listitem>

<para>Sets threshold of validation successes after which to fail back to

the first URL in the <literal>default.url.set</literal> list</para>

</listitem>

</varlistentry>

</variablelist>

<para>See <link

xlink:href="agent-install-guide#web-bootstrap-configuration-properties"

xlink:role="http://docbook.org/xlink/role/olink"><citetitle>Bootstrap

Configuration Properties</citetitle></link> for details.</para>

</listitem>

<listitem>

<para>Web policy agents now allow you to configure the naming of the URL

validation net-connect timeout (<link

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

xlink:show="new">OPENAM-1257</link>).</para>

</listitem>

<listitem>

<para>Web policy agents now support IPv6 for notenforced IP addresses

(<link xlink:href="https://bugster.forgerock.org/jira/browse/OPENAM-1256"

xlink:show="new">OPENAM-1256</link>).</para>

</listitem>

<listitem>

<para>A web policy agent is now available for Apache HTTPD Server 2.4 (<link

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

xlink:show="new">OPENAM-1195</link>).</para>

</listitem>

<listitem>

<para>Web policy agents now let you enable and disable Cache-Control

headers for unauthenticated sessions (<link

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

xlink:show="new">OPENAM-1087</link>).</para>

</listitem>

<listitem>

<para>Web policy agents now let you preserve POST data when working with

URI-based load balancing (<link

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

xlink:show="new">OPENAM-980</link>).</para>

</listitem>

<listitem>

<para>Web policy agents now let you configure whether to do an HTTP 302

redirect after processing the LARES POST (<link

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

xlink:show="new">OPENAM-936</link>).</para>

</listitem>

<listitem>

<para>Web policy agents now let you configure whether to URL encode the

session cookie sent with the LARES POST using the boolean property

<literal>com.forgerock.agents.cdsso.cookie.urlencode</literal> (<link

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

xlink:show="new">OPENAM-915</link>).</para>

</listitem>

<listitem>

<para>Web policy agents can now conditionally redirect users based on the

incoming request URL (<link

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

xlink:show="new">OPENAM-849</link>).</para>

</listitem>

<listitem>

<para>Web policy agents now support the Expires attribute on cookies (<link

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

xlink:show="new">OPENAM-815</link>).</para>

</listitem>

<listitem>

<para>Web policy agents can now mark persistent cookies as HTTPOnly, to

prevent scripts and third-party programs from accessing the cookies

(<link

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

xlink:show="new">OPENAM-804</link>).</para>

</listitem>

<listitem>

<para>The IIS 7 web policy agents now has support for HTTP Basic

authentication and password replay, thereby better supporting Microsoft

OWA and SharePoint (<link

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

xlink:show="new">OPENAM-773</link>).</para>

</listitem>

<listitem>

<para>Web policy agents now allow use of regular expressions in Not

Enforced URLs (<link

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

xlink:show="new">OPENAM-772</link>). In addition, regular expressions are

supported for logout URLs and for rejecting access to invalid URLs.</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>

<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>All web policy agents except Microsoft IIS web agents require Java for

installation. ForgeRock recommends the most recent release of Java 6 or later

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 doc and testing

<listitem>

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

<para>In this release, this web policy agent is not at feature parity with

the other web policy agents and is lacking some fixes. In particular,

this policy agent has the following known issues.</para>

<!-- List generated at 09:21:20 20130215 using http://bugster.forgerock.org/jira/rest/api/2/search?jql=id%20in%20%28%22OPENAM-2180%22%2C%20%22OPENAM-2178%22%2C%20%22OPENAM-2177%22%2C%20%22OPENAM-1889%22%2C%20%22OPENAM-1701%22%2C%20%22OPENAM-1523%22%29&startAt=0&maxResults=500&fields=summary-->

<itemizedlist>

<listitem><para><link xlink:href="https://bugster.forgerock.org/jira/browse/OPENAM-2180" xlink:show="new">OPENAM-2180</link>: Missing bootstrap file in WPA for SJSWS 7 should indicate this in error message</para></listitem>

<listitem><para><link xlink:href="https://bugster.forgerock.org/jira/browse/OPENAM-2178" xlink:show="new">OPENAM-2178</link>: SJSWS 7 agent debug log size parameter does not behave correctly for values below 3000</para></listitem>

<listitem><para><link xlink:href="https://bugster.forgerock.org/jira/browse/OPENAM-2177" xlink:show="new">OPENAM-2177</link>: SJSWS does not handle PDP cache expiration correctly</para></listitem>

<listitem><para><link xlink:href="https://bugster.forgerock.org/jira/browse/OPENAM-1889" xlink:show="new">OPENAM-1889</link>: 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-1701" xlink:show="new">OPENAM-1701</link>: Internal exception is thrown upon login to WPA when c66encode is set to false</para></listitem>

<listitem><para><link xlink:href="https://bugster.forgerock.org/jira/browse/OPENAM-1523" xlink:show="new">OPENAM-1523</link>: Policy Agent fails to locate OpenAM server cookie value</para></listitem>

</itemizedlist>

<para>This web policy agent has been tested only on 64-bit versions of

Solaris.</para>

</listitem>

<listitem>

<para><?eval ${agentSunProxyServerSupport}?></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>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.</para>

</section>

</section>

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

<title>Web Policy Agent Compatibility</title>

<para>This section concerns OpenAM Web Policy Agents

<?eval ${webAgentsDocTargetVersion}?>.</para>

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

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

<itemizedlist>

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

</listitem>

</itemizedlist>

</section>

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

<title>Deprecated Functionality</title>

<para>The following functionality is deprecated in OpenAM Web Policy Agents

<?eval ${webAgentsDocTargetVersion}?>, and is likely to be removed in a

future release.</para>

<itemizedlist>

<listitem>

<para>Web policy agent support for Sun Proxy Server <!--and Sun Web Server-->

is deprecated. Support for <!--these web servers--> Sun Proxy Server is likely to be removed in a

future release.</para>

</listitem>

</itemizedlist>

</section>

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

<title>Removed Functionality</title>

<para>No functionality has been removed in OpenAM Web Policy Agents

<?eval ${webAgentsDocTargetVersion}?>.</para>

</section>

</section>

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

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

<para>OpenAM web policy agent issues are tracked at <link xlink:show="new"

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

>https://bugster.forgerock.org/jira/browse/OPENAM</link>.</para>

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

<title>Key Fixes</title>

<para>The following bugs were fixed in release

<?eval ${webAgentsDocTargetVersion}?>. For details, see the <link

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

>OpenAM issue tracker</link>.</para>

<para>TODO</para>

</section>

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

<title>Limitations</title>

<para>OpenAM web policy agents do not currently support IPv6.</para>

</section>

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

<title>Known Issues</title>

<para>The following important known issues remained open at the time

release <?eval ${webAgentsDocTargetVersion}?> 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>

<para>TODO</para>

</section>

</section>

</chapter>