Two quirks with openam web agents

Well, a few more actually. The following relate to v3.0.4 of the OpenAM Web Agent for Apache 2.2 on x86_64 Red Hat Enterprise 6 Linux communicating with OpenAM 9.5.4.

It goes without saying that all the changes noted here need a hard restart of the Apache web service before they’ll be effective. Some may also require a restart of the OpenAM application.

Most if not all of these issues may have been cleared up with OpenAM 10 and the newer 3.0.5 series of web agents. These newer versions are a bit too new right now for those of us working within a Fortune 200 framework.

NSS/NSPR Incompatibility

Timing is everything. Unfortunately for the OpenAM project Red Hat‘s implementation of NSS and NSPR in its recent operating system releases is slightly out of alignment with what some others, including the OpenAM developers, have accounted for AND (most importantly) Red Hat has decided to offer both mod_ssl (OpenSSL library dependent) mod_nss (nss library dependent) as options for serving up HTTPS. You can’t remove the nss libraries themselves, they’ve become too integral to the RHEL 6 system, but my preference has been to remove mod_nss and use mod_ssl where I need to do SSL locally on the server (various enterprise alternatives to running SSL on the local server exist, like F5’s BigIP LTM SSL off-loading feature).

As a result anyone deploying the v3.0.4 Apache 2.2 Web Agents on Red Hat Enterprise Linux 6 is going to have a nasty surprise when they try accessing a url protected by it.

This problem is acknowledged in ForgeRock Bugster OPENAM-721 (DO NOT follow additional instructions in OPENAM-728 if you are running the shipping Apache HTTPD Server). The bug report states the problem is fixed in v3.0.5 of the web agents.

The solution offered was twofold:

1. Add the following to the end of /etc/sysconfig/httpd:

export NSS_STRICT_NOFORK=DISABLED

2. When asked for the OpenAM server url, give an http (non-secure) not an https (secure) connection You can later add back in any https urls as the primary connection and move the http url to secondary.

In the agent bootstrap file, [Agent Install Dir]/Agent_001/config/OpenSSOAgentBootstrap.properties, the naming service urls are entered on a single line with a space between:

com.sun.identity.agents.config.naming.url = https://mysso.example.com:443/ http://mysso.example.com:80/

Another important step is to make sure all the nss and nspr packages on your host systems are up to date. Doing a “yum update nss* nspr*” is highly recommended.

Sub Realms and Agent Configuration

If you’ve followed the best practice advice from OpenAM’s developers, your agents will live in a new realm you’ve created under the default (“/”), for example “/intranet”. If that’s the case you’ll need to edit the OpenSSOAgentBootstrap.properties file under the Agent’s config directory on the web server to reflect that sub realm, because the agent installer configures the agent for the default realm by… default.

So, for example, if installed your agent under:

/opt/openam/web_agents/apache22_agent

Then you’ll need to drill down to

Agent_001/config

and edit OpenSSOAgentBootstrap.properties so it reads:

com.sun.identity.agents.config.organization.name = /intranet

Non-default cookie names

Again, if you follow the best practices outlined by the OpenAM developers, you will have changed your security cookie name from the default “iPlanetDirectoryPro” to something else, like “intranet” (this is found under Configuration… Servers and Sites… [Server Name]… Security under Cookie).

If you do this be forewarned that by default any web agent object you create under a realm is going to have the old default cookie name, not your custom name. To fix this you just have to go into the agent object (found in Access Control… [Realm]… Agents… [Agent Name]… SSO under “Cookie Name”) and make the change.

Of course since this is not a “hot swap” attribute, you’ll then have to restart the OpenAM application to effect the change.

This is one of the things that led me to learn how to create web agents from scratch using ssoadm. Here’s the relevant attribute that you’d set in your input file:

com.sun.identity.agents.config.cookie.name=intranet

In the example above I’ve named the cookie “intranet”. Not very creative, but hopefully more informative than the product documentation on the subject.

Policy Clock Skew

This attribute specifies the number of seconds allowed for in adjusting the time between an agent host and the OpenAM server host.

In the gui OpenAM console this can be found in Access Control… [Realm]… Agents… [Agent Name]… OpenAM Services, under Policy Client Service. The actual attribute you’d see in an ssoadm dump of the agent config would be:

com.sun.identity.agents.config.policy.clock.skew=2

Various mail list posts make it clear that to avoid Bad Things From Happening [TM], the policy clock skew value should never be set to zero (0) — although this is in fact the shipping default. Even in environments where everyone is slaved to the same time server slight differences in timing can crop up, so this is good advice, even if it isn’t found anywhere in the documentation.

In the example above I’ve set it to 2 seconds, which being a nonzero value is probably as good a place as any to start.

Note that this is not a hot swap attribute and will therefore require a restart of the web agent’s web service (on RHEL and its clones a simple “service httpd restart” will suffice). This would be something I’d include in any input file used to create a web agent with ssoadm.

CDSSO Cookies Domain List

This is a list of all the domains that need to have a cookie set by the CDSSO service. If you’ve enabled CDSSO, this should not be left blank, although that is the default for any newly created agnet and no one will warn you otherwise.

In the gui console it can be found in Access Control… [Realm]… Agents… [Agent Name]… SSO, under Cross Domain SSO.

com.sun.identity.agents.config.cdsso.cookie.domain[0]=.anotherexample.com
com.sun.identity.agents.config.cdsso.cookie.domain[1]=.example.com

The example given above is from an agent whose host is in the example.com domain, but that protects sites in the anotherexample.com domain. In most cases where you’re doing CDSSO, the list should contain at least two domains: the home domain of the web server host (and OpenAM server), as well as any other domain for sites that you are protecting.

Debug and Audit Log Rotation

In a word, turn them off. People have experienced bad headaches as a result of Apache and the OpenAM web agent playing tug-of-war on the filesystem. This as yet unresolved bug is discussed in OPENAM-329.

In the gui console look for this on the Global tab of each agent object (these are found under Access Control… [Realm]… Agents).

From a web agent config (dumped using ssoadm show-agent):

com.sun.identity.agents.config.debug.file.rotate=false
com.sun.identity.agents.config.local.log.rotate=false

On RHEL 6 you are still going to have problems because of the way the system logrotate cycles the httpd daemon and renames logs during log rotation.

By default the /etc/logrotate.d/httpd config invokes “/sbin/service reload”, in other words does a nohup. The solution is to replace this command with

/sbin/service httpd stop
/sbin/service httpd start

New to RHEL 6, files managed with logrotate affix a date stamp suffix when rolling out the old log. This is incompatible with the web agent’s “-N” renaming convention (e.g. amAgent-1… amAgent-2, etc.), which was the old RHEL standard. You can restore the old style names by adding a single line to /etc/logrotate.d/httpd:

nodateext

Log File Location

OpenAM allows you to set the full path to wherever you want to put your logs in $WEB_AGENT_INSTALL/config/OpenSSOAgentBootstrap.properties:

com.sun.identity.agents.config.debug.file = /var/log/httpd/amAgent.log
com.sun.identity.agents.config.local.logfile = /var/log/httpd/amAgent_web_anotherexample_com_80.log

Config for debug log is first, audit log second.

Turn off Notifications

At least consider doing so where you’re hosting on RHEL 6. In the agent config object on the OpenAM server set as follows:

com.sun.identity.agents.notification.enabled=false
com.sun.identity.agents.config.change.notification.enable=false