Sun Java System Access Manager Policy Agent 2.2 Guide for IBM Lotus Domino 6.5.4

What's New About Web Agents

Several important features have been added to the web agents in the 2.2 release as follows:

Support for Fetching User Session Attributes

Before this release of web agents, header and cookie information was retrieved, or sourced, solely from user profile properties. Now, header and cookie information can also be sourced from session properties.

Use the following property to choose how you want session attributes retrieved:

com.sun.am.policy.agents.config.session.attribute.fetch.mode

For the preceding property, the following modes are available as retrieval methods:

The following example illustrates this property with the retrieval method set to HTTP_HEADER:


com.sun.am.policy.agents.config.session.attribute.fetch.mode = HTTP_HEADER

The source of header and cookie information is controlled by the following configuration property in the web agent AMAgent.properties configuration file:

com.sun.am.policy.agents.config.session.attribute.map

This configuration property has the same format as an LDAP header property. The following is an example of how this configuration property can be set:

com.sun.am.policy.agents.config.session.attribute.map = 
name-of-session-attribute1|name-of-header-attribute1, 
name-of-session-attribute2|name-of-header-attribute2

Where name-of-session-attribute1 and other similarly named properties, or attributes, in the preceding code represent actual property names.

Benefit - Support for Fetching User Session Attributes: The benefit of this feature is that session properties can be more effective for transferring information, especially dynamic information. Prior to this release, agents could only fetch users’ profile attributes, which tend to be static attributes. However, session attributes allow applications to obtain dynamic user information when necessary. Since this feature allows you to fetch non-user profile attributes, you can fetch attributes such as SAML assertion.

Log Rotation

Starting with this release of web agents, when the current log file reaches a specific size, a new log file is created. Log information is then stored in the new log file until it reaches the size limit. This default behavior is configurable. Therefore, log rotation can be turned off and the size limit can be changed.


Note –

The type of information stored in log files has not changed in Policy Agent 2.2. The following types of information are logged:

The troubleshooting, or diagnostic, information is stored in log files, locally, with the web agent. The access denied and access allowed information, which is often referred to as audit-related information, can be stored both locally and with Access Manager.

Configuration that relates to the local log files is performed in the web agent AMAgent.properties configuration file. Configuration that relates to the audit related logs stored with Access Manager is performed in the Access Manager AMConfig.properties configuration file.

The log rotation described in this section refers to logs that store troubleshooting information locally.


Log rotation is controlled by the following configuration property in the web agent AMAgent.properties configuration file:

com.sun.am.policy.agents.config.local.log.rotate

Log rotation occurs automatically since the default value of this property is true. When this property is set to false, no rotation takes place for the local log file.

The following example shows this configuration property set to true:

com.sun.am.policy.agents.config.local.log.rotate = true

The following properties are also related to log rotation:

The following code example demonstrates how to set the property that controls log file size so that a new log file is created when the current log file reaches a specific size.

com.sun.am.policy.agents.config.local.log.size: n

Where n represents the size of a file in bytes. The file size should be a minimum of 3000 bytes. The default size is 10 megabytes.


Note –

By default, the log file size property is not exposed in the web agent AMAgent.properties configuration file. If you want to change the default size, add a line to the file setting this property to the file size desired.


When a new log file is created an index appends to the name of the log file as such:

amAgent-1
amAgent-2

Where amAgent represents the fully qualified path name to the log files excluding the appended number. The numbers 1 and 2 represent the appended number. The appended number indicates the chronological order in which information of a given size was filed away into its respective log file. There is no limit to the number of log files that can be rotated.

Benefit - Log Rotation: Prior to this release of web agents, all logging messages were written to the same log file. However, saving all log information to a single log file has the potential of exhausting disk space. The log rotation feature solves this problem.

Policy-Based Response Attributes

Starting with this release of web agents, a new method is available for retrieving LDAP user attributes based on Access Manager policy configurations.

Policy-based response attributes take advantage of functionality now available in Access Manager that involves querying policy decisions. In previous versions of Access Manager, header attributes could only be determined by the list of attribute-value pairs in the agent configuration. Now, header attributes can also be determined by Access Manager policy configurations. With policy-based response attributes you can define attribute-value pairs at each policy definition as opposed to the method used in prior versions of Access Manager, which only allowed pairs to be defined globally in the agent configuration. For more information on policy-based response attributes, see Providing Personalization With Policy-Based Response Attributes

Benefit - Policy-Based Response Attributes: The benefit of policy-based response attributes is that they allow for personalization, improve the deployment process, allow greater flexibility in terms of customization, and provide central and hierarchical control of attribute values.

Personalization is provided in that an application can retrieve specific user information, such as a name, from a cookie or HTTP header and present it to the user in the browser.

Defining attribute-value pairs at each policy definition instead of at the root level allows an attribute value to be distributed only to the applications that need it. Furthermore, you can customize attribute names allowing the same attribute name to have entirely different property values for two different applications.

Composite Advice

Starting with this release, web agents provide a composite advice feature. This feature allows the policy and authentication services of Access Manager to decouple the advice handling mechanism of the agents. This allows you to introduce and manage custom advices by solely writing Access Manager side plug-ins. Starting with this release, you are not required to make changes on the agent side. Such advices are honored automatically by the composite advice handling mechanism.

Benefit - Composite Advice: A benefit of composite advice is that you can incorporate a custom advice type without having to make changes to an agent deployment. Prior to the 2.2 release of web agents, no interface existed on the client side to write client-side plug-ins.

Additional Method for Fetching the REMOTE_USER Server Variable

Prior to this release of web agents, the only method for fetching the value of the REMOTE_USER variable set by an agent was from session properties. Starting with the 2.2 release, the value can also be fetched from user profiles. This fetching process uses LDAP.

By default the value for the REMOTE_USER is fetched from the session. If the value needs to be fetched from LDAP, the following property needs to be defined in the web agent AMAgent.properties configuration file:

com.sun.am.policy.am.userid.param.type = LDAP

The following property can still be used to configure the key (key refers to the value assigned to this property) that needs to be searched. In addition to setting the preceding property, you need to give the correct LDAP attribute name for the following property.

com.sun.am.policy.am.userid.param

For example the property will be set as follows:

com.sun.am.policy.am.userid.param = ldap-attribute-name

where ldap-attribute-name represents the name of an LDAP attribute.

To enable the REMOTE_USER setting for a globally not-enforced URL as specified in the web agent AMAgent.properties configuration file (this is a URL that can be accessed by unauthenticated users) you must set the following property in the web agent AMAgent.properties configuration file to true. While the following example, has the value is set to true, the default value is false:

com.sun.am.policy.agents.config.anonymous_user.enable = true

When you set this property value to true, the value of REMOTE_USER will be set to the value contained in the following property in the web agent AMAgent.properties configuration file. In the following example the value is set to anonymous, which is the default:

com.sun.am.policy.agents.config.anonymous_user = anonymous

Benefit - Additional Method for Fetching the REMOTE_USER Server Variable: The benefit of this feature is that it gives better customization for end users since the REMOTE_USER server variable can now be obtained from either session attributes or user profile attributes.

Also, you do not need to write server-side plug-in code in order to add session attributes after authentication, which is necessary when this value is fetched from session properties.

Malicious Header Attributes Automatically Cleared by Agents

Starting with this release of web agents, malicious header attributes are automatically cleared.

Benefit - Header Attributes Set by Agents Automatically Cleared: The benefit of this automatic clean up is that security is improved. Header information that is not automatically cleared has greater risk of being accessed.

Load Balancing Enablement

Starting with this release of web agents, the default agent host port and protocol settings can be overridden to enable load balancing. For more information, see Enabling Load Balancing.

Benefit - Load Balancing Enablement: The benefit of this override capability is that you do not need to manually change the hostname, port, and protocol settings to enable load balancing.

Support for Heterogeneous Agent Types on the Same Machine

Starting with this release of web agents, you can install different types of agents on the same machine. Prior to this release, you could not install web agents from different product groups on the same machine. For example, previously, an agent instance for Sun Java System Web Server 6.1 and an agent instance for Apache 2.0.52 could not be installed on the same machine. Now, they can.

Benefit - Support for Heterogeneous Agent Types on Same Machine: The benefit of this feature is that a deployment that has agents in a multi-server scenario requires fewer hardware sources.

Support for Turning Off FQDN Mapping

Starting with this release, fully qualified domain name (FQDN) mapping of HTTP requests can be disabled. In prior web agent releases, the methods employed for checking if a user is using a valid URL could not be turned off.

This checking capability is controlled by the FQDN default and the FQDN map properties in the web agent AMAgent.properties configuration file as follows:

A toggling capability has been introduced that allows FQDN checking to be turned off. The following property allows for this toggling:

com.sun.am.policy.agents.config.fqdn.check.enable

The following property specifies whether the request URLs that are present in user requests are checked against the FQDN default and the FQDN map properties by the web agent:

com.sun.am.policy.agents.config.fqdn.check.enable

The valid values are true and false.

true

The request URLs that are present in user requests are checked against FQDN values.

false

No checking occurs against FQDN values.

The default value is true. If no value is specified, then the default value, true, is used.

Benefit - Support for Turning Off FQDN Mapping: This feature allows you to turn off or on FQDN mapping comparison. This feature can be beneficial when a deployment includes a number of virtual servers for which the agent is configured using FQDN mapping.

Backward Compatibility With Access Manager 6.3

Policy Agent 2.2 is backward compatible with Access Manager 6.3 Patch 1 or greater.


Note –

Policy Agent 2.2 is only compatible with Access Manager 6.3 when the Access Manager patch has been applied.


Be aware that Policy Agent 2.2 takes advantage of certain features that exist in Access Manager 7 that do not exist in Access Manager 6.3, such as “composite advices,” “policy-based response attributes,” and others.