test

Sun OpenSSO Enterprise Policy Agent 3.0 User's Guide for Web Agents

Chapter 4 Common Web Agent Tasks and Features in Policy Agent 3.0

After installing the web agent and performing the required post-installation steps, you must adjust the agent configuration to your site's specific deployment. This chapter describes how to modify web agents generally. Therefore, the information in this chapter tends to apply to all web agents in the Policy Agent 3.0 software set.

Interaction with Policy Agent 3.0 is enabled to a great extent by configuring the agent properties. However, some interaction with the agent is performed using the agentadmin command as explained in Role of the agentadmin Program in Policy Agent 3.0.

This section focuses on features that involve setting web agent property values. Assigning values to properties is the key method available for configuring agent features. The topics described in this section are typically those of greatest interest in real-world deployment scenarios. This section does not cover every property. For a list of every web agent property, see Policy Agent 3.0: Web Agent Properties. For a description of all the agent properties, see the following link: http://wikis.sun.com/display/OpenSSO/agent3properties.

The manner in which these properties are set varies depending on if the agent configuration is centralized on the OpenSSO Enterprise server or contained locally with the agent. However, regardless of if the agent configuration is local or centralized, a small subset of properties is always stored locally with the agent in the OpenSSOAgentBootstrap.properties file. The properties in the bootstrap file are required for the agent to start up and initialize itself. For example, the agent profile name and password used to access the OpenSSO Enterprise server are stored in this bootstrap file. To change the values in the bootstrap file, you must edit the file directly. For information about the ssoadm utility, see Appendix D, Using the ssoadm Command-Line Utility With Agents.

In terms of the properties not stored in the OpenSSOAgentBootstrap.properties file and when the web agent configuration is centralized on the OpenSSO Enterprise server, you can use the OpenSSO Enterprise Console or the ssoadm command-line utility to set the web agent properties. For information about the ssoadm utility, see Appendix D, Using the ssoadm Command-Line Utility With Agents.

When the web agent configuration is local, OpenSSO Enterprise Console and the ssoadm utility tool are not available for agent configuration. Instead, you must configure the majority of web agent properties using the OpenSSOAgentConfiguration.properties file. However, the properties in the bootstrap file still apply in a local configuration. In all situations, you must edit the properties in the bootstrap file directly.

Caution – Caution –

The content of the OpenSSOAgentBootstrap.properties file and the OpenSSOAgentConfiguration.properties file are very sensitive. Changes made can result in changes in how the agent works. Errors made can cause the agent to malfunction.

The following is the location of the OpenSSOAgentBootstrap.properties file and the OpenSSOAgentConfiguration.properties file:

PolicyAgent-base/AgentInstance-Dir/config

For more information about the Policy Agent 3.0 directory structure, see Web Agent Directory Structure in Policy Agent 3.0.

The following topics are discussed in this section:

How Web Agent Properties Are Discussed in this Guide

When this guide discusses editing a property, the emphasis is on the property as set in OpenSSO Enterprise Console. For a description of how to access the Web agent properties using OpenSSO Enterprise Console, see To Navigate in the OpenSSO Enterprise 8.0 Console to the Web Agent Properties.

To set a property in OpenSSO Enterprise Console, the name of the Console tab in which the property is located is useful as well as the property label. The property name is not usually as important when using OpenSSO Enterprise Console, but can still be of some use and is therefore included in this guide whenever a property is mentioned.

Example 4–1 The Method Used for Discussing Web Agent Properties in This Guide

Most agent properties mentioned in this guide are presented using a format that is most useful for those configuring properties using OpenSSO Enterprise Console. However, that format is not used when the property is in the OpenSSOAgentBootstrap.properties file since the bootstrap file is not accessible using OpenSSO Enterprise Console. The following example illustrates the format usually used in this guide to mention an agent property:

Example: The property labeled Login Form URI (Tab: Application, Name: com.sun.identity.agents.config.login.form).

Caution – Caution –

Every time you change a property using OpenSSO Enterprise Console, you must click Save on that page for the change to take place. Furthermore, if the property is not hot-swappable, you must restart the Policy Agent container for the new value to take effect.

The above example provides the following details about the property:

Property label used in OpenSSO Enterprise Console:

Login Form URI

The name of the OpenSSO Enterprise Console tab within which the property is located:

Application

The property name:

com.sun.identity.agents.config.login.form

Since the emphasis of this guide is on the use of OpenSSO Enterprise Console, other methods of editing properties are not consistently mentioned. If you are configuring agent properties using the ssoadm utility, the explanations provided in this guide about the purpose of the agent properties are still applicable, however for details on configuring the agent properties using the ssoadm utility, see Appendix D, Using the ssoadm Command-Line Utility With Agents.

If the agent is configured locally, therefore using the OpenSSOAgentConfiguration.properties file, you cannot use OpenSSO Enterprise Console. For such a scenario, descriptions of the properties provided in this guide are still applicable and some limited information about setting the property in the OpenSSOAgentConfiguration.properties file is provided. However. for the most part, you should consult the OpenSSOAgentConfiguration.properties file itself for information about setting the properties.

Hot-Swap Mechanism in Web Agents

Most web agent properties are hot-swap enabled. Properties are identified as hot-swappable or not in OpenSSO Enterprise Console (a centralized agent configuration option) and in the OpenSSOAgentConfiguration.properties file (the local agent configuration option). When changes are made to the agent configuration, the changes must be communicated to the property configuration cache for it to be updated. Hot-swap enabled (or Hot-swappable) properties allow such changes to be made without having to restart the agent server. For properties that are not hot-swappable, the new values are only picked up by the agent once the agent container is restarted.

Therefore, when hot-swappable properties are changed on the OpenSSO Enterprise server (using OpenSSO Enterprise Console or the ssoadm utility), the changes can be communicated using notifications or polling. However, when the agent configuration is stored with the agent locally (in the OpenSSOAgentConfiguration.properties file), changes to the property values can only be communicated through polling. The communication of property value changes results in an update to the property configuration cache.

For notifications, the property that controls the hot-swap mechanism is labeled Agent Configuration Change Notification (Tab: Global, Name: com.sun.identity.agents.config.change.notification.enable) and for polling, the property that controls the hot-swap mechanism is labeled Configuration Reload Interval (Tab: Global, Name: com.sun.identity.agents.config.load.interval). These two properties, which both control the hot-swap mechanism, are themselves hot-swap enabled. This means that if the hot-swap mechanism is enabled by one of these properties and you change the value of the respective property, the new value will take effect.

Web Agent Properties That Are List Constructs

Certain web properties are specified as lists. Knowledge of the format of these list constructs is often not required in order to set them. For example when you configure the properties using OpenSSO Enterprise Console, you do not interact with the “<key>[<index>] = <value>” formatting involved with list constructs. However, if you use OpenSSO Enterprise Console to set a list, though the formatting information provided in this section is not applicable, the general information about lists is useful.

See the following table to determine when the list construct format is required to set this property.

Table 4–1 Use of the List Construct Format: Required or Not

Method for Setting Properties

Location of Agent Configuration

Knowledge of List Construct Format Required

Using the OpenSSO Enterprise Console 

Centralized agent configuration 

NO 

Using the ssoadm command-line utility

Centralized agent configuration 

YES 

Using the OpenSSOAgentConfiguration.properties file

Local agent configuration 

YES 

A list construct has the following format (Does not apply when the OpenSSO Enterprise Console is used):

<key>[<index>] = <value>
key

The configuration key (name of the configuration property)

index

A positive number starting from 0 that increments by 1 for every value specified in this list.

value

One of the values specified in this list

Note –

Properties that are specified in this manner must follow the preceding format, otherwise they will be treated as invalid or missing properties.

More than one property can be specified for this key by changing the value of <index>. This value must start from the number 0 and increment by 1 for each entry added to this list.

If certain indices are missing, those indices are ignored and the rest of the specified values are loaded at adjusted list positions.

Duplicate index values result in only one value being loaded in the indexed or adjusted indexed position.

Example 4–2 Example of Web Agent Properties That Are List Constructs

com.sun.identity.agents.config.notenforced.url[0] = http://agentHost.com:8080/public/*
com.sun.identity.agents.config.notenforced.url[1] = http://agentHost.com:8080/images/*
com.sun.identity.agents.config.notenforced.url[2] = http://agentHost.com:8080/index.html

Web Agent Properties That Are Map Constructs

Knowledge of the format of these map constructs is often not required in order to set them. For example when you configure the properties using OpenSSO Enterprise Console, you do not interact with the “<key>[<name>]=<value>” formatting involved with map constructs. However, if you use OpenSSO Enterprise Console to set a map, though the formatting information provided in this section is not applicable, the general information about maps is useful.

See the following table to determine when the map construct format is required to set this property.

Table 4–2 Use of the Map Construct Format: Required or Not

Method for Setting Properties

Location of Agent Configuration

Use of Map Construct Format Required

Using the OpenSSO Enterprise Console 

Centralized agent configuration 

NO 

Using the ssoadm command-line utility

Centralized agent configuration 

YES 

Using the OpenSSOAgentConfiguration.properties file

Local agent configuration 

YES 

Certain web agent properties are specified as maps. A map construct has the following format (Does not apply when OpenSSO Enterprise Console is used):

<key>[<name>]=<value>
key

The configuration key (name of the configuration property)

name

A string that forms the lookup key as available in the map

value

The value associated with the name in the map

Note –

Properties that are specified in this manner must follow the preceding format, otherwise they will be treated as invalid or missing properties.

For a given <name>, there may only be one entry in the configuration for a given configuration key (<key>). If multiple entries with the same <name> for a given configuration key are present, only one of the values will be loaded in the system and the other values will be discarded.

Example 4–3 Example of Web Agent Properties That Are Map Constructs

com.sun.identity.agents.config.fqdn.mapping[invalid_hostname] = valid_hostname
com.sun.identity.agents.config.profile.attribute.mapping[mail] = email

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 OpenSSO Enterprise. This is essentially a high availability option. It ensures that if the deployment container that runs OpenSSO Enterprise service becomes unavailable, the web agent still processes access requests through a secondary, or failover, deployment container running OpenSSO Enterprise service.

Setting up failover protection for the web agent, requires modifying a web agent property. However, you must first install two different instances of OpenSSO Enterprise on two separate deployment containers.

Then follow the instructions 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 OpenSSO Enterprise. The property labeled OpenSSO Login URL (Tab: OpenSSO Services, Name: com.sun.identity.agents.config.login.url) stores the failover deployment container name. Furthermore, whenever you add a value to the OpenSSO Login URL property, you must configure the property named com.sun.identity.agents.config.naming.url (accessible in the OpenSSOAgentBootstrap.properties file) as illustrated subsequently.

Set this property in order to store failover server information. Given the values in the following list, the property would be set as shown in Example 4–4.

host1

Name of the primary OpenSSO Enterprise host.

host2

Name of the failover OpenSSO Enterprise host.

example

Name of the domain.

58080

Default port number

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

Failover protection of a web agent is enabled by assigning values, as shown in the following list, to the OpenSSO Login URL property:

http://host1.example.com:58080/opensso/UI/Login
http://host2.example.com:58080/opensso/UI/Login
Example 4–5 Configuration Property Setting for Naming Service of Web Agent

Adding a value to the OpenSSO Login URL property requires that you configure the following property:com.sun.identity.agents.config.naming.url (accessible in the OpenSSOAgentBootstrap.properties file). For example, if the OpenSSO Login URL property is set as illustrated in Example 4–4, the following property should be set as shown:

com.sun.identity.agents.config.naming.url =
http://host1.example.com:58080/opensso/namingservice
http://host2.example.com:58080/opensso/namingservice

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 and a cache notification 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. This feature relies on a polling mechanism.

The web agent property labeled Policy Cache Polling Period (com.sun.identity.agents.config.policy.cache.polling.interval) 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.

Hybrid Cache Updates

In this mode, cache entry expiration still applies through use of the polling mechanism. In addition, the web agent gets notified by the OpenSSO Enterprise service about session changes through use of a notification mechanism. Session changes include events such as session logout or a session timeout. When notified of a session or a policy change, the web agent updates the corresponding entry in the cache. Apart from session updates, web agents can also receive policy change updates. Policy changes include events such as updating, deleting, and creating policies.

Web agents have the hybrid cache update mode switched on by default. This is triggered by the web agent property labeled Enable Notifications com.sun.identity.agents.config.notification.enable. When this property is disabled, the web agent updates its cache through the polling mechanism only.

Restrictions due to firewalls, as well as the type of deployment container in use, might not allow notifications to work. In such cases, the notification mechanism is turned off.

The web agent sets a timeout period on its cache entries. After its end of life, the cache entry is purged from the web agent’s cache. The web agent does not refetch the cache data. The next attempt to access the same entry from cache fails and the web agent makes a round trip to the server and fetches it again to populate the cache. This lazy method of cache updating keeps the web agent cache performing optimally and reduces network traffic.

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 Policy Cache Polling Period property, set it to the lower of the two:

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 labeled Not Enforced URLs (Tab: Application, Name: com.sun.identity.agents.config.notenforced.url) is used for this purpose. Wild cards can be used to define a pattern of URLs. For more information about the use of wildcards, see Appendix C, Wildcard Matching in Policy Agent 3.0 Web Agents.

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 labeled Invert Not Enforced URLs (Tab: Application, Name: com.sun.identity.agents.config.notenforced.url.invert) is used to reverse the meaning of the Not Enforced URLs property. If the Invert Not Enforced URLs property is enabled (by default it is not enabled), then the not-enforced URL list becomes the enforced list.

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

The following are examples:

Scenario 1: Not-Enforced URL List

The Invert Not Enforced URLs property is not enabled.

The following URLs are listed as values for the Not Enforced URLs property:

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 on the not-enforced list. All other resources will be protected by the web agent.

Scenario 2: Inverted Not-Enforced URL List

The Invert Not Enforced URLs property is enabled.

The following URLs are listed as values for the Not Enforced URLs property:

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 not-enforced list. All other resources will be accessible to any user.

Caution – Caution –

If feasible, do not enable the Invert Not Enforced URLs property.

Not enabling this property reduces the chance of unintentionally allowing access to resources.

Configuring the Not-Enforced IP Address List

The property labeled Not Enforced Client IP List (Tab: Application, Name: com.sun.identity.agents.config.notenforced.ip) 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 labeled SSO Only (Tab: Global, Name com.sun.identity.agents.config.sso.only) is used to specify if only authentication is enforced for URLs protected by the web agent. If this property is enabled (by default it is not enabled), it indicates that the web agent enforces authentication only, without enforcing policies. After a user logs into OpenSSO Enterprise server 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 3.0 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 3.0 support a feature where a user's session attributes are fetched and set as headers or cookies.

Session attributes are especially effective for transferring information that is dynamic. However, the information transferred only lasts during the current session.

Unlike profile attributes, session attributes are not limited to LDAP attributes retrieved from the user data store. Since session attributes allow non-user profile attributes to be fetched, you can configure the deployment to fetch attributes such as SAML assertion.

The following are examples of session attributes: UserToken, UserId, Principal, AuthType, AuthLevel, sun.am.UniversalIdentifier, MyProperty

A good use case for fetching user session attributes presents itself when a post authentication plug-in is involved. A post authentication plug-in performs some tasks right after user authentication. You can configure a post authentication plug-in to fetch data from an external data repository and then set this data as session attributes for that user. These session attributes can be retrieved by the web container and made available to the application.

The web agent property labeled Session Attribute Fetch Mode (Tab: Application, Name: com.sun.identity.agents.config.session.attribute.fetch.mode) is responsible for fetching session attributes. This property can be configured using OpenSSO Enterprise Console and can be set to one of the following values:

When set to NONE, no session attributes are fetched and the property labeled Session Attribute Map (Tab: Application, Name: com.sun.identity.agents.config.session.attribute.mapping) is ignored.

With the Session Attribute Fetch Mode property set to either HTTP_HEADER or HTTP_COOKIE, the web agent fetches session attributes. Use the Session Attribute Map property to configure attributes that are to be forwarded as HTTP headers or cookies.

This section illustrates how the Session Attribute Fetch Mode 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.”

Therefore, the Session Attribute Map property would have the following value:

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 OpenSSO Enterprise policy configurations. With policy-based response attributes you can define attribute-value pairs at each policy.

Policy-based response attributes can improve the deployment process, allow greater flexibility in terms of customization, and provide central and hierarchical control of attribute values.

Web agents set policy-based response attributes as headers or cookies based on configuration. All subjects that match this attribute set obtain this attribute. The web agent property labeled Response Attribute Fetch Mode (Tab: Application, Name: com.sun.identity.agents.config.response.attribute.fetch.mode) controls this functionality:

The default setting for this property is HTTP_HEADER. However, this property can be set to any of the following values:

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 property labeled Response Attribute Map (Tab: Application, Name: com.sun.identity.agents.config.response.attribute.mapping) is used for this type of mapping:

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 the Response Attribute Fetch Mode property.

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 3.0 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 OpenSSO Enterprise. 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 web agent properties. To turn this feature on and off, edit the property labeled Profile Attribute Fetch Mode (Tab: Application, Name: com.sun.identity.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 web agent property labeled Profile Attribute Map (Tab: Application, Name: com.sun.identity.agents.config.profile.attribute.mapping). 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 Profile Attribute Map property.

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 OpenSSO Enterprise is installed: amUser.xml

Note –

The amUser.xml file is available from the directory within which the opensso.war file is deployed. This directory varies according to the web container. The following is an example of a possible location:

OpenSSO-Deploy-base/WEB-INF/classes/amUser.xml

The attributes in this file could be either OpenSSO Enterprise user attributes or OpenSSO Enterprise dynamic attributes. For an explanation of these two types of user attributes, see Sun OpenSSO Enterprise 8.0 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 users access resources protected by the web agent using valid URLs. The property labeled FQDN Default (Tab: Global, Name: com.sun.identity.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 labeled FQDN Virtual Host Map (Tab: Global, Name: com.sun.identity.agents.config.fqdn.mapping) 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 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 the FQDN Default property.

The FQDN Virtual Host 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 assigning a value to the FQDN Virtual Host Map property is as follows:

Map Key

invalid_hostname

Corresponding Map Value

valid_hostname

where:

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

The valid_hostname value is the corresponding valid hostname that is fully qualified. For example, the following are possible values assigned to the FQDN Virtual Host Map property in OpenSSO Enterprise Console for xyz.domain1.com:

Map Key

xyz

Corresponding Map Value

xyz.domain1.com

Map Key

xyz.domain1

Corresponding Map Value

xyz.domain1.com

When you are done setting the FQDN Virtual Host Map property as described in this example, it appears in OpenSSO Enterprise Console with the following format:

[xyz]=xyz.domain1.com

[xyz.domain1]=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 OpenSSO Enterprise Console. Set the FQDN Virtual Host Map property as such:

Map Key

valid

Corresponding Map Value

xyz.hostname.com

Turning Off FQDN Mapping

You can disable fully qualified domain name (FQDN) mapping of HTTP requests.

This checking capability is controlled by the web agent properties labeled FQDN default (Tab: Global, Name: com.sun.identity.agents.config.fqdn.default) and FQDN Virtual Host Map (Tab: Global, Name: com.sun.identity.agents.config.fqdn.mapping).

The web agent property labeled FQDN Check (Tab: Global, Name: com.sun.identity.agents.config.fqdn.check.enable) is enabled by default. When this property is enabled, the request URLs that are present in user requests are checked against FQDN values. However, you can turn FQDN checking off if you choose. Turning off FQDN checking might be beneficial when a deployment includes a number of virtual servers for which the agent is configured using FQDN mapping.

Resetting Cookies

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

This feature is configurable through two web agent properties: the property labeled Cookie Reset (Tab: SSO, Name: com.sun.identity.agents.config.cookie.reset.enable) and the property labeled Cookies Reset Name List (Tab: SSO, Name: com.sun.identity.agents.config.cookie.reset):

Configuring CDSSO

Note –

The cross domain single sign-on (CDSSO) feature does not apply to all web agents. When CDSSO is not supported by a specific web agent, such information is provided in the individual web agent guide.

The CDSSO feature is configurable through three web agent properties. Enable or disable this feature with the property labeled Cross Domain SSO (Tab: SSO, Name: com.sun.identity.agents.config.cdsso.enable). By default, this property is not enabled, and the feature is turned off.

Set the URL where the CDC controller is installed by assigning the URL as the value to the property labeled CDSSO Servlet URL (Tab: SSO, Name: com.sun.identity.agents.config.cdsso.cdcservlet.url).

The following is an example of the value that could be assigned to the CDSSO Servlet URL property:

http://OpenSSOhost.example.com:58080/amserver/cdcservlet

The third property involved in configuring CDSSO is labeled Cookies Domain List (Tab: SSO, Name: com.sun.identity.agents.config.cookie.domain). This property 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 OpenSSO Enterprise 8.0 Technical Overview.

Setting the REMOTE_USER Server Variable

The property labeled User ID Parameter (Tab: OpenSSO Services, Name: com.sun.identity.agents.config.userid.param) allows you to configure the user ID parameter passed by the session or user profile information from OpenSSO Enterprise. 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 or profile attribute. The property labeled User ID Parameter Type (Tab: OpenSSO Services, Name: com.sun.identity.agents.config.userid.param.type) determines the location from which to retrieve the value: from user profiles or from session properties.

Note –

Be aware that when this value is fetched from session properties, you must write server-side plug-in code in order to add session attributes after authentication.

Example 1: This example lists the values that you can set the User ID Parameter property to for session attributes:

SESSION (this is default)

UserToken (UserId, Principal, or any other session attribute)

Example 2: This example lists the values that you can set the User ID Parameter property to for LDAP user profile attributes:

LDAP

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. The not-enforced list refers to values assigned to the property labeled Not Enforced URLs (Tab: Application, Name: com.sun.identity.agents.config.notenforced.url)

To enable the REMOTE_USER variable to be set for not-enforced URLs, you must enable the web agent property labeled Anonymous User (Tab: Miscellaneous, Name: com.sun.identity.agents.config.anonymous.user.enable). By default, this value is not enabled.

When you enable this property, the value of REMOTE_USER is set to the value contained in the web agent property labeled Anonymous User Default Value (Tab: Miscellaneous, Name: com.sun.identity.agents.config.anonymous.user.id). By default, the value assigned to this property is anonymous.

Validating Client IP Addresses

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

By default, the web agent labeled Client IP Validation (Tab: Application, Name: com.sun.identity.agents.config.client.ip.validation.enable) is not enabled.

If you enable this property, client IP address validation is enforced 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 is 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 a load balancer exists 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 a Web Agent Profile in Policy Agent 3.0

Agents in the Policy Agent software set must authenticate with the OpenSSO Enterprise server in order for the two components to interact. To authenticate, the agent must provide its name (the agent profile name) and agent profile password. This password was established and encrypted as part of the web agent installation process. For more information, see Creating a Web Agent Profile in Policy Agent 3.0. However, you can change this password if you choose.

The agent profile password can be updated with a combination of configuration steps involving both the OpenSSO Enterprise Console and the OpenSSOAgentBootstrap.properties file. The agent profile password should originally be created either prior to agent installation. However, after you install a web agent, you can update the agent profile password at anytime.

ProcedureTo Update a Web Agent Profile Password in Policy Agent 3.0

The instructions that follow describe how to change agent profile password.

  1. Using a browser, navigate through OpenSSO Enterprise Console to the web agent properties of the agent that you want to configure.

    For the steps to navigate to the web agent properties, see To Navigate in the OpenSSO Enterprise 8.0 Console to the Web Agent Properties.

  2. Update the agent profile password in the web agent properties section as described in the substeps that follow:

    1. In the Global tab ( which is the default tab), locate the property labeled Password.

    2. Update the property labeled Password to a password of your choice.

    3. Update the property labeled “Password (confirm)” to the same value you chose for the Password property.

    4. Click Save at the top of that Global page.

  3. Update or create an agent profile password in a password file as described in the substeps that follow.

    The password file should originally have been created as a web agent pre-installation task.

    1. (Conditional) If an ASCII text agent password file does not already exist, create one .

      For example, create a file such as the following: /tmp/pwf1

    2. Using a text editor, enter in clear text on the first line, (or replace the original password, if one already exists with) the password you just updated in OpenSSO Enterprise Console.

  4. In the command line, issue the agentadmin --encrypt command to encrypt the new password.

    For example:

    PolicyAgent-base/bin/agentadmin --encrypt Agent_001 /tmp/pwf1

    The agentadmin program returns the new encrypted password with a message such as the following:

    The encrypted value is: nMXvXoCgWAAbTomKJ6H5/g==

    For more information on this command, see agentadmin --encrypt.

  5. Copy the encrypted value that is returned.

  6. Using a text editor of your choice, access the web agent OpenSSOAgentBootstrap.properties configuration file at the following location:

    PolicyAgent-base/AgentInstance-Dir/config

  7. In the bootstrap configuration file, edit the property for the agent password by pasting the encrypted password, and therefore replacing the original value of the encrypted password, as shown:

    com.sun.identity.agents.config.password = encryptedPassword

    where encryptedPassword represents the new encrypted password you created when you issued the agentadmin --encrypt command.

    This property is set in a manner similar to the following:

    com.sun.identity.agents.config.password = nMXvXoCgWAAbTomKJ6H5/g==

  8. Restart the web agent container.

    The container must be restarted for the changes to the bootstrap file to take effect.

Configuring Web Agent Log Rotation

For 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 or the size limit can be changed.

Note –

The following types of information are logged for Policy Agent 3.0:

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 OpenSSO Enterprise.

Configuration that relates to the local log files is performed by editing the web agent property labeled Rotate Local Audit Log (Tab: Global, Name: com.sun.identity.agents.config.local.log.rotate). The Rotate Local Audit Log property is accessible using the OpenSSO Enterprise Console. Configuration that relates to the audit related logs stored with OpenSSO Enterprise is not controlled by an agent property, but this type of configuration can also be implemented using the Console.

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

The local logs are rotated automatically since by default, the Rotate Local Audit Log property is enabled. When this property is not enabled, no rotation takes place for the local log file.

The following properties are also related to log rotation:

This property controls the log file size in that a new log file is created when the current log file reaches a specific size. The file size should be a minimum of 3000 bytes. The default size is 10 megabytes.

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.

Enabling Load Balancing

Various web agent properties influence the enablement of 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 OpenSSO Enterprise

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

Example 4–7 Property Settings: Load Balancer in Front of OpenSSO Enterprise

This example illustrates the web agent property settings that can be used to enable load balancing:

Property (name or label) 

Setting 

com.sun.identity.agents.config.naming.url (accessible in the OpenSSOAgentBootstrap.properties file)

LB-url /amserver/namingservice

OpenSSO Login URL 

LB-url /amserver/UI/Login

Load Balancer Setup 

Enabled  

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

http://LBhost.example.com:8080

Load Balancer in Front of the Web Agent

In many cases, when a load balancer is deployed in front of the web agent only the property labeled FQDN Virtual Host Map (Tab: Global, Name: com.sun.identity.agents.config.fqdn.mapping) is required.

Assign the following value to the FQDN Virtual Host Map property:

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 web agent properties should be set in addition to the preceding property:

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 not be enabled.

Property (name or label) 

Setting 

Override Request URL Protocol 

true

Override Request URL Host 

(Enabled) 

Override Request URL Port 

(Enabled) 

Override Notification URL 

LB-url/amagent

Load Balancers in Front of Both the Web Agent and OpenSSO Enterprise

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

Composite Advice

Web agents provide a composite advice feature. This feature allows the policy and authentication services of OpenSSO Enterprise to decouple the advice handling mechanism of the agents. This allows you to introduce and manage custom advices by solely writing OpenSSO Enterprise side plug-ins. You are not required to make changes on the agent side. Such advices are honored automatically by the composite advice handling mechanism.

Malicious Header Attributes Automatically Cleared by Agents

For web agents in the Policy Agent software set, malicious header attributes are 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