Sun Java System Access Manager Policy Agent 2.2 Guide for Microsoft Internet Information Services 5.0

Chapter 1 Introduction to Web Agents for Policy Agent 2.2

The Sun JavaTM System Access Manager Policy Agent 2.2 software set includes J2EE agents and web agents. This guide discusses web agents, the functionality of which has increased for this release. This chapter provides a brief overview of web agents in the 2.2 release as well as some concepts you need to understand before proceeding with a web agent deployment. For a general introduction of agents, both J2EE agents and web agents, see Sun Java System Access Manager Policy Agent 2.2 User’s Guide.

Topics in this chapter include:

Uses of Web Agents

Web agents function with Sun Java System Access Manager to protect content on web servers and web proxy servers from unauthorized intrusions. They control access to services and web resources based on the policies configured by an administrator. Web agents perform these tasks while providing single sign-on (SSO) and cross domain single sign-on (CDSSO) capabilities as well as URL protection.

Web agents are installed on deployment containers for a variety of reasons. Here are three examples:

In each of these situations, a system administrator must set up policies that allow or deny users access to content on a deployment container. For information on setting policies and for assigning roles and policies to users, see the Sun Java System Access Manager 7 2005Q4 Administration Guide.

How Web Agents Work

When a user points a browser to a particular URL on a protected deployment container, a variety of interactions take place as explained in the following numbered list. See the terminology list immediately following this numbered list for a description of terms.

  1. The web agent intercepts the request and checks information from the request against not-enforced lists. If specific criteria are met, the authentication process is by passed and access is granted to the resource.

  2. If authentication is required, the web agent validates the existing authentication credentials. If the existing authentication level is insufficient, the appropriate Access Manager Authentication Service will present a login page. The login page prompts the user for credentials such as username and password.

  3. The authentication service verifies that the user credentials are valid. For example, the default LDAP authentication service verifies that the username and password are stored in Sun Java System Directory Server. You might use other authentication modules such as RADIUS and Certificate modules. In such cases, credentials are not verified by Directory Server but are verified by the appropriate authentication module.

  4. If the user’s credentials are properly authenticated, the web agent checks if the users is authorized to access the resource.

  5. Based on the aggregate of all policies assigned to the user, the individual is either allowed or denied access to the URL.

Terminology: How Web Agents Work

Authentication Level

The ability to access resources can be divided into levels. Therefore, different resources on a deployment container (such as a web server or proxy server) might require different levels of authentication


Access Manager is made of many components. A service is a certain type of component that performs specific tasks. Some of the Access Manager services available are Authentication Service, Naming Service, Session Service, Logging Service, and Policy Service.

Authentication Module

An authentication interface, also referred to as an authentication module, is used to authenticate a user on Access Manager.


Roles are a Directory Server entry mechanism. A role's members are LDAP entries that possess the role.


A policy defines rules that specify access privileges to protected resources on a deployment container, such as a web server.

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:

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: = HTTP_HEADER

The source of header and cookie information is controlled by the following configuration property from the web agent configuration file:

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: = 

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 configuration file. Configuration that relates to the audit related logs stored with Access Manager is performed in the Access Manager 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 configuration file:

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: = 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. 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 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:


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 configuration file: = 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.

For example the property will be set as follows: = 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 configuration file (this is a URL that can be accessed by unauthenticated users) you must set the following property in the web agent configuration file to true. While the following example, has the value is set to true, the default value is false: = 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 configuration file. In the following example the value is set to anonymous, which is the default: = 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 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:

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:

The valid values are true and false.


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


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.