Sun Java System Access Manager Policy Agent 2.2 Guide for Apache HTTP Server 2.0.54

Key Features and Tasks Performed with the Web Agent AMAgent.properties Configuration File

The web agent AMAgent.properties configuration file is a text file of configuration properties that you can modify to change web agent behavior. However, the content of this file is very sensitive. Changes made can result in changes in how the agent works. Errors made can cause the agent to malfunction.

This section focuses on some of the key features and tasks performed with the configuration file. For a list and description of every property in the configuration file, access the configuration file itself located as described in Table 6–1. Also a list of the properties is available in this guide, at Appendix C, Web Agent AMAgent.properties Configuration File.

This section describes the most important details of the configuration file, such as how specific properties can be modified to produce specific results. The topics described are typically those of greatest interest in real-world deployment scenarios. For a list and description of every property in the configuration file, access the configuration file itself located as described in Table 6–1. Also a list of the properties is available in this guide, at Appendix C, Web Agent AMAgent.properties Configuration File.

This section describes the following:

Locating the Web Agent AMAgent.properties Configuration File

The following table provides the default location for the web agent AMAgent.properties configuration file on the supported platforms.

Table 6–1 Location of the Web Agent AMAgent.properties Configuration File

Server 

Platform 

Location 

 

Solaris (SPARC and X86) 

/etc/opt/SUNWam/agents/apache/config/
_PathInstanceName/

AIX and Linux 

/etc/opt/agents/apache/config/_PathInstanceName/

Windows 

PolicyAgent-base\apache\config\apache_port\

where port is the port number of the Apache HTTP Server instance and _PathInstanceName represents the name of a directory that is automatically created and named during the agent installation process. The name for this directory is derived from the full path name of the Apache conf directory. The process of creating the directory name involves the conversion of forward slash symbols “/” into underscore symbols “_.” For example, a full path name of /opt/apache/conf provides the information used to name this new directory as follows:


_opt_apache_conf

Using the Web Agent AMAgent.properties Configuration File

Changing the web agent AMAgent.properties configuration file can have serious and far-reaching effects. When you make changes, keep the following in mind:


Note –

If you make changes to the web agent AMAgent.properties configuration file, restart the deployment container to make your changes take effect.


The web agent AMAgent.properties configuration file includes information for a variety of configurations, including the following:

The configuration file also contains configuration information on advanced features, such as forwarding LDAP user attributes through HTTP headers and POST data preservation.

Providing Failover Protection for a Web Agent

When you install a web agent, you can specify a failover or backup deployment container, such as a web server, for running Access Manager. This is essentially a high availability option. It ensures that if the deployment container that runs Access Manager service becomes unavailable, the web agent still processes access requests through a secondary, or failover, deployment container running Access Manager service.

Setting up failover protection for the web agent, requires modifying the web agent AMAgent.properties configuration file. However, you must first install two different instances of Access Manager on two separate deployment containers.

Then follow the instructions in this guide to about installing the web agent. The web agent installation program prompts you for the host name and port number of the failover deployment container that you have configured to work with Access Manager. The following property in the web agent AMAgent.properties configuration file, stores the failover deployment container name:

com.sun.am.policy.am.login.url

Set this property in order to store failover deployment container information. Given the values in the following list, the property would be set as shown in Example 6–1.

host1

Name of the primary Access Manager host.

host2

Name of the first failover Access Manager host.

host3

Name of the second failover Access Manager host.

example

Name of the domain.

58080

Default port number


Example 6–1 Configuration Property Setting for Failover Protection of a Web Agent

com.sun.am.policy.am.login.url = http://host1.example.com:58080/
amserver/UI/Login http://host2.example.com:58080/amserver/UI/Login 
http://host3.example.com:58080/amserver/UI/Login

A failover server name is configurable after it has been set during installation. When configuring this property, note that a space is required between each Access Manager login URL.

Changing the Web Agent Caching Behavior

Each web agent maintains a cache that stores the policies for every user’s session. The cache can be updated by a cache polling mechanism.

Cache Updates

A web agent maintains a cache of all active sessions involving content that the agent protects. Once an entry is added to an agent's cache, it remains valid for a period of time after which the entry is considered expired and later purged.

The property com.sun.am.policy.am.polling.interval in the web agent AMAgent.properties configuration file determines the number of minutes an entry will remain in the web agent cache. Once the interval specified by this property has elapsed, the entry is dropped from the cache. By default, the expiration time is set to three minutes.

In a normal deployment situation, policy changes on the server are frequent, which requires sites to accept a certain amount of latency for web agents to reflect policy changes. Each site decides the amount of latency time that is acceptable for the site’s specific needs. When setting the com.sun.am.policy.am.polling.interval property, set it to the lower of the two:


Note –

Sun Java System Policy Agent 2.2 for Apache HTTP Server does not support notifications. Therefore, updating the cache through a notification mechanism is not an available feature. However, since the notification mechanism is available for other agents in the Policy Agent 2.2 software set, a property exists in the web agent AMAgent.properties configuration file to control this feature. The property that controls the notification mechanism, com.sun.am.notification.enable, is set to false for this agent. Do not set this property to true for this agent as it might result in unexpected behavior.


Configuring the Not-Enforced URL List

The not-enforced URL list defines the resources that should not have any policies (neither allow nor deny) associated with them.

By default, the web agent denies access to all resources on the deployment container that it protects. However, various resources (such as a web site or an application) available through a deployment container might not need to have any policy enforced. Common examples of such resources include the HTML pages and .gif images found in the home pages of web sites and the cascading style sheets (CSS) that apply to these home pages. The user should be able to browse such pages without authenticating. For the home page example, all these resources need to be on the not-enforced URL list or the page will not be displayed properly. The property com.sun.am.policy.agents.config.notenforced_list is used for this purpose. Wild cards can be used to define a pattern of URLs. Space is the separator between the URLs mentioned in the list.

There can be a reverse, or “inverted”, scenario when all the resources on the deployment container, except a list of URLs, are open to any user. In that case, the property com.sun.am.policy.agents.config.notenforced_list.invert would be used to reverse the meaning of com.sun.am.policy.agents.config.notenforced_list. If it is set to true (by default it is set to false), then the not-enforced URL list would become the enforced list.


Example 6–2 Configuration Property Settings for Not-Enforced URL List

The following are examples:

Scenario 1: Not-Enforced URL List

com.sun.am.policy.agents.config.notenforced_list.invert = false

com.sun.am.policy.agents.config.notenforced_list = 
http://host1.example.com:80/welcome.html
http://host1.example.com:80/banner.html

In this case, authentication and policies will not be enforced on the two URLs listed in the notenforcedList. All other resources will be protected by the web agent.

Scenario 2: Inverted Not-Enforced URL List

com.sun.am.policy.agents.config.notenforced_list.invert = true

com.sun.am.policy.agents.config.notenforced_list =
 http://host1.example.com:80/welcome.html
 http://host1.example.com:80/banner.html

In this case, authentication and policies will be enforced by the web agent on the two URLs mentioned in the notenforcedList. All other resources will be accessible to any user.



Caution – Caution –

If feasible, keep this property set to false as such:

com.sun.am.policy.agents.config.notenforced_list.invert = false

A value of false reduces the chance of unintentionally allowing access to resources.


Configuring the Not-Enforced IP Address List

The com.sun.am.policy.agents.config.notenforced_client_ip_list property is used to specify a list of IP addresses. No authentication is required for the requests coming from these client IP addresses.

In other words, the web agent will not enforce policies for the requests originating from the IP addresses in the Not-Enforced IP Address list.

Enforcing Authentication Only

The property com.sun.am.policy.agents.config.do_sso_only is used to specify if only authentication is enforced for URLs protected by the web agent. If this property is set to true (by default it is set to false), it indicates that the web agent enforces authentication only, without enforcing policies. After a user logs onto Access Manager successfully, the web agent will not check for policies related to the user and the accessed URLs.

Providing Personalization Capabilities

Web agents in Policy Agent 2.2 can personalize page content for users in three distinct ways as described in the following subsections:

Providing Personalization With Session Attributes

Web agents in Policy Agent 2.2 support a feature where a user's session attributes are fetched and set as headers or cookies. The following property responsible for this task:


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

This property can be set to one of the following values:

When set to NONE, no session attributes are fetched and the com.sun.am.policy.agents.config.session.attribute.map property is ignored. With this property set to either HTTP_HEADER or HTTP_COOKIE, the web agent fetches session attributes. Use the following property to configure attributes that are to be forwarded as HTTP headers or cookies: com.sun.am.policy.agents.config.session.attribute.map.

The following content is from the web agent AMAgent.properties configuration file. The text has been reformatted for this section. This section illustrates how the com.sun.am.policy.agents.config.session.attribute.map property maps session attributes to headers or cookies.

Session attributes are added to an HTTP header following this format:


session_attribute_name|http_header_name[,...]

The value of the attribute being fetched in session is session_attribute_name. This value gets mapped to a header value as follows: http_header_name.


Note –

In most cases, in a destination application where http_header_name appears as a request header, it is prefixed with HTTP_ and the following type of conversion takes place:

Lower case letters

convert to upper case letters.

Hyphen “-

converts to underscore “_

"common-name

as an example, converts to “HTTP_COMMON_NAME.”


com.sun.am.policy.agents.config.session.attribute.map = 
successURL | success-url, contextId | context-id

The session attribute is forwarded as a header or a cookie as determined by the end-user applications on the web container that the web agent is protecting. These applications can be considered the consumers of the forwarded header values. The forwarded information is used for the customization and personalization of web pages. You can also write server side plug-ins to put any user session attribute and define the corresponding attribute name and mapping in the preceding property to retrieve the value.

Providing Personalization With Policy-Based Response Attributes

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.

Web agents in this release set policy-based response attributes as headers or cookies based on configuration. All subjects that match this attribute set obtain this attribute.

The following is a new property that has been added to the web agent AMAgent.properties configuration file to control this functionality:

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

This property can be set to one of the following values:

The following example shows this configuration property with the default setting, which is HTTP_HEADER:

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

Attribute mapping is available for response attributes. Therefore, the format of policy information can be mapped to the format of a header or a cookie. The below property is used for this type of mapping:


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

Unlike profile attributes and session attributes, where only the mapped attributes are displayed as headers or cookies, by default, response attributes are set by the agent as headers or cookies based on the setting of this property:


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

If a response attribute map is specified, then the corresponding attribute mapped name is fetched from the map and its corresponding value is displayed as either a header or a cookie based on the setting of the above property.

Providing Personalization With User Profile Attributes Globally

Web agents in Policy Agent 2.2 have the ability to forward user profile attribute values via HTTP headers to end-web applications. The user profile attribute values come from the server side of Access Manager. The web agent behaves like a broker to obtain and relay user attribute values to the destination servlets, CGI scripts, or ASP pages. These applications can in turn use the attribute values to personalize page content.

This feature is configurable through two properties in the web agent AMAgent.properties configuration file. To turn this feature on and off, edit the following property in the web agent AMAgent.properties configuration file:

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

This property can be set to one of the following values:

When set to NONE, the web agent does not fetch LDAP attributes from the server and ignores the com.sun.am.policy.agents.config.profile.attribute.map property. In the other two cases, the web agent fetches the attribute.

To configure the attributes that are to be forwarded in the HTTP headers, use the following property:

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

Below is an example section from the web agent AMAgent.properties configuration file, which shows how this feature is used:


#
# The policy attributes to be added to the HTTP header.  The
# specification is of the format
# ldap_attribute_name|http_header_name[,...]. ldap_attribute_name
# is the attribute in data store to be fetched and
# http_header_name is the name of the header to which the value
# needs to be assigned.
#
# NOTE: In most cases, in a destination application where a
# "http_header_name" shows up as a request header, it will be
# prefixed by HTTP_, and all lower case letters will become upper
# case, and any - will become _; For example, "common-name" would
# become "HTTP_COMMON_NAME"
#
com.sun.am.policy.agents.config.profile.attribute.map = cn|common-name,ou|
organizational-unit,
o|organization,mail|email,employeenumber|employee-number,c|country



      

By default, some LDAP user attribute names and HTTP header names are set to sample values.

To find the appropriate LDAP user attribute names, check the following XML file on the machine where Access Manager is installed:

AccessManager-base/SUNWam/config/xml/amUser.xml

The attributes in this file could be either Access Manager user attributes or Access Manager dynamic attributes. For an explanation of these two types of user attributes, see Sun Java System Access Manager 7 2005Q4 Administration Guide.

The attribute and HTTP header names that need to be forwarded must be determined by the end-user applications on the deployment container that the web agent is protecting. Basically, these applications are the consumers of the forwarded header values (the forwarded information is used for the customization and personalization of web pages).

Setting the Fully Qualified Domain Name

To ensure appropriate user experience, it is necessary that the users access resources protected by the web agent using valid URLs. The configuration property com.sun.am.policy.agents.config.fqdn.default provides the necessary information needed by the web agent to identify if the user is using a valid URL to access the protected resource. If the web agent determines that the incoming request does not have a valid hostname in the URL, it redirects the user to the corresponding URL with a valid hostname. The difference between the redirect URL and the URL originally used by the user is only the hostname, which is changed by the web agent to a fully qualified domain name (FQDN) as per the value specified in this property.

This is a required configuration property without which the deployment container may not start up correctly. This property is set during the web agent installation and must not be modified unless absolutely necessary to accommodate deployment requirements. An invalid value for this property can result in the deployment container becoming unusable or the resources becoming inaccessible.

The property com.sun.am.policy.agents.config.fqdn.map provides another way by which the web agent can resolve partial or malformed access URLs and take corrective action. The web agent gives precedence to the entries defined in this property over the value defined in the com.sun.am.policy.agents.config.fqdn.default property. If none of the entries in this property matches the hostname specified in the user request, the agent uses the value specified for com.sun.am.policy.agents.config.fqdn.default property.

The com.sun.am.policy.agents.config.fqdn.map property can be used for creating a mapping for more than one hostname. This may be the case when the deployment container protected by this agent is accessible by more than one hostname. However, this feature must be used with caution as it can lead to the deployment container resources becoming inaccessible.

This property can also be used to override the behavior of the web agent in cases where necessary. The format for specifying the property com.sun.am.policy.agents.config.fqdn.map is:

com.sun.am.policy.agents.config.fqdn.map = [invalid_hostname|valid_hostname][,...]

where:

invalid_hostname is a possible invalid hostname such as partial hostname or an IP address that the user may provide .

valid_hostname is the corresponding valid hostname that is fully qualified. For example, the following is a possible value specified for hostname xyz.domain1.com:

com.sun.am.policy.agents.config.fqdn.map = xyz|xyz.domain1.com, xyz.domain1|xyz.domain1.com

This value maps xyz and xyz.domain1 to the FQDN xyz.domain1.com.

This property can also be used in such a way that the web agent uses the name specified in this map instead of the deployment container’s actual name.

If you want your server to be addressed as xyz.hostname.com whereas the actual name of the server is abc.hostname.com. The browser only knows xyz.hostname.com and you have specified policies using xyz.hostname.com in the Access Manager Console. In this file, set the mapping as com.sun.am.policy.agents.config.fqdn.map = valid|xyz.hostname.com.

Resetting Cookies

The cookie reset feature enables the web agent to reset some cookies in the browser session while redirecting to Access Manager for authentication.

This feature is configurable through two properties in the web agent AMAgent.properties configuration file.

Configuring CDSSO

The cross domain single sign-on (CDSSO) feature is configurable through three properties in the web agent AMAgent.properties configuration file. To turn this feature on or off, use the following property:

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

By default, this property is set to false, and the feature is turned off. To turn on CDSSO, set this property to true.

Set the URL where CDC controller is installed by specifying the URL in the following property:

com.sun.am.policy.agents.config.cdcservlet.url

The following is an example of how this property could be set:

com.sun.am.policy.agents.config.cdcservlet.url = 
http://host1.eng.example.com:58080/amserver/cdcservlet

The third property, com.sun.am.policy.agents.config.cookie.domain.list allows you to specify a list of domains in which cookies have to be set in a CDSSO scenario. This property is used only if CDSSO is enabled. If you leave this property blank, then the fully qualified cookie domain for the web agent server will be used for setting the cookie domain. In such a case, it is a host cookie and not a domain cookie.

For more information on CDSSO, see Sun Java System Access Manager 7 2005Q4 Technical Overview

Setting the REMOTE_USER Server Variable

The property com.sun.am.policy.am.userid.param allows you to configure the user ID parameter passed by the session or user profile information from Access Manager. The user ID value is used by the agent to set the value of the REMOTE_USER server variable. By default, this parameter is set to UserToken and is fetched from session attributes.

It can be set to any other session attribute. Another property determines where to retrieve the value, from user profiles or from session properties.

Example 1: This example demonstrates how to set the user ID parameter with session attributes:

com.sun.am.policy.am.userid.param.type=SESSION (this is default)

com.sun.am.policy.am.userid.param=UserToken (UserId, Principal, or any other session attribute)

Example 2: This example demonstrates how to set the user ID parameter with LDAP user profile attributes:

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

com.sun.am.policy.am.userid.param=cn (any profile attribute)

Setting Anonymous User

For resources on the not-enforced list, the default configuration does not allow the REMOTE_USER variable to be set. To enable the REMOTE_USER variable to be set for not-enforced URLs, you must set the following property in the web agent AMAgent.properties configuration file to TRUE (by default the value is FALSE):


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

When you set the value of this property 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:


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

By default, the value of this property is set to anonymous as follows:


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

Validating Client IP Addresses

This feature can be used to enhance security by preventing the stealing or hijacking of SSO tokens.

The web agent AMAgent.properties configuration file contains a property titled com.sun.am.policy.agents.config.client_ip_validation.enable, which by default, is set to false.

If you set this property value to true, client IP address validation will be enabled for each incoming request that contains an SSO token. If the IP address from which the request was generated does not match the IP address issued for the SSO token, the request will be denied. This is essentially the same as enforcing a deny policy.

This feature should not be used, however, if the client browser uses a web proxy or if there is a load balancer somewhere between the client browser and the agent-protected deployment container. In such cases, the IP address appearing in the request will not reflect the real IP address on which the client browser runs.

Resetting the Shared Secret Password

This section describes how to reset the shared secret. The web agent stores the shared secret in the web agent AMAgent.properties configuration file.

If you are only interested in resetting the shared secret, not the agent profile name, continue reading this section. If you are interested in creating or updating the agent profile in Access Manager Console and then updating the same credential information in the web agent, see Chapter 4, The Relationship Between the Agent Profile and Web Agents in Policy Agent 2.2. The steps described in that chapter are comprehensive, integrating the simpler steps described in this section.

The chapter mentioned in the preceding paragraph also provides a useful explanation of the process and terminology related to the credentials used by web agents to authenticate with Access Manager. Refer to that chapter for more information.

This section specifically describes how to change the shared secret in web agents. The following situations might require you to reset the shared secret:

The value for the property com.sun.am.policy.am.password in the web agent AMAgent.properties configuration file is set with the encrypted shared secret during web agent installation. Therefore, if the shared secret is entered incorrectly during installation, the preceding property is assigned an incorrect value, preventing the web agent from authenticating with Access Manager.

To reset or change the shared secret, use the encryption utility to encrypt the shared secret and then set the value in the property as described in the following task.

ProcedureTo Reset the Shared Secret

This task applies to all platforms.

  1. Go to the following directory:

    PolicyAgent-base/bin

  2. Execute the appropriate platform-specific script in the command line:

    • UNIX-based Systems:

      # ./crypt_util shared-secret

    • Windows Systems:

      cryptit shared-secret

    where shared-secret represents the password, that along with the agent user name, allows the web agent to authenticate with Access Manager. The default value of the shared secret is the password of the Access Manager internal LDAP authentication user. This user is commonly referred to as amldapuser.

  3. Copy the output obtained after issuing the preceding command and paste it as the value for the following property:


    com.sun.am.policy.am.password
  4. Restart the deployment container and try accessing any resource protected by the agent.

    If the agent gets redirected to Access Manager, this indicates the above steps were executed properly.

Enabling Load Balancing

Various properties in the web agent AMAgent.properties configuration file can be used to enable load balancing. Edit the properties that apply, according to the location of the load balancer or load balancers in your deployment, as follows:

Load Balancer in Front of Access Manager

When a load balancer is deployed in front of Access Manager and a web agent interacts with the load balancer, the following properties must be edited:

com.sun.am.naming.url
com.sun.am.policy.am.login.url
com.sun.am.load_balancer.enable

Example 6–3 Property Settings: Load Balancer in Front of Access Manager

This example illustrates property settings in the web agent AMAgent.properties configuration file that can be used to enable load balancing:

com.sun.am.naming.url = LB-url/amserver/namingservice
com.sun.am.policy.am.login.url = LB-url/amserver/UI/Login
com.sun.am.load_balancer.enable = true

where LB-url represents the load balancer URL. The following example is a conceivable load balancer URL:

http://hostname.example.com:8080

Load Balancer in Front of Web Agent

In many cases, when a load balancer is deployed in front of the web agent only the following property must be set:

com.sun.am.policy.agents.fqdnMap

Example 6–4 Property Settings: Load Balancer in Front of Web Agent

com.sun.am.policy.agents.fqdnMap = valid|LB-hostname

where LB-hostname represents the name of the machine on which the load balancer is located.


However, if SSL-termination or a proxy server is used in the deployment, all the following properties in the web agent AMAgent.properties configuration file should be set in addition to the preceding property:

com.sun.am.policy.agents.config.override_protocol
com.sun.am.policy.agents.config.override_host
com.sun.am.policy.agents.config.override_port
com.sun.am.policy.agents.config.agenturi.prefix

This example illustrates how properties can be set to enable load balancing when the protocol, hostname, and port number of the load balancer differ from that of the web agent. However, if the load balancer and the web agent share one of these characteristics, such as the protocol or hostname, then the respective property would be left blank instead of being assigned a value of true.

com.sun.am.policy.agents.config.override_protocol = true
com.sun.am.policy.agents.config.override_host = true
com.sun.am.policy.agents.config.override_port = true
com.sun.am.policy.agents.config.agenturi.prefix = LB-url/amagent

where LB-url represents the load balancer URL. The following example is a conceivable load balancer URL:

http://hostname.example.com:8080

Load Balancers in Front of Both the Web Agent and Access Manager

This scenario is simply a combination of the scenarios described in the preceding sections. See Load Balancer in Front of Access Manager and Load Balancer in Front of Web Agent.