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:
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:
A web agent on a human resources server prevents non-human resources personnel from viewing confidential salary information and other sensitive data.
A web agent on an operations deployment container allows only network administrators to view network status reports or to modify network administration records.
A web agent on an engineering deployment container allows authorized personnel from many internal segments of a company to publish and share research and development information. At the same time, the web agent restricts external partners from gaining access to the proprietary information.
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.
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.
The web agent intercepts the request and checks information in the request against not-enforced lists. If specific criteria are met, the authentication process is by passed and access is granted to the resource.
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.
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.
If the user’s credentials are properly authenticated, the web agent checks if the users is authorized to access the resource.
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
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.
Several important features have been added to the web agents in the 2.2 release as follows:
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:
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:
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.
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.
The type of information stored in log files has not changed in Policy Agent 2.2. The following types of information are logged:
Access denied information
Access allowed information
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:
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 value for following configuration property indicates the location of the debug file:
The value of following configuration property indicates the maximum number of bytes the debug file holds:
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.
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.
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:
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.
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.
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.
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.
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.
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.
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.
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.
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:
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.
Policy Agent 2.2 is backward compatible with Access Manager 6.3 Patch 1 or greater.
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.