Key Features and Tasks Performed With the J2EE AMAgent.properties Configuration File

The J2EE agent AMAgent.properties configuration
file is a text file of configuration properties that you can modify to change
J2EE agent behavior.

Caution –

The content of the J2EE agent AMAgent.properties configuration
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 describes the most important details of the J2EE agent AMAgent.properties 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. This section
does not cover every property in the file. For a list and description of every
property, see Appendix B, J2EE Agent AMAgent.properties Configuration File in Policy Agent 2.2.

Hot-Swap Mechanism in J2EE Agents

Certain property keys in the J2EE agent AMAgent.properties configuration
file are hot-swap enabled. The value for these keys, when altered, are dynamically
loaded by the agent such that it is not necessary to restart the deployment
container for these changes to take effect. However, in cases where the property
is explicitly identified as not enabled for hot-swap or in cases when the
hot-swap mechanism is disabled on the system, the deployment container must
be restarted for the changes to take effect.

When the agent is deployed on a deployment container where Access Manager has
been configured, the hot-swap mechanism is disabled by default and cannot
be used.

The hot-swap mechanism is controlled by the following configuration
property:

com.sun.am.policy.config.load.interval

The valid values for this property is any unsigned integer including
0, which indicates the amount of time in seconds after which the agent will
check for changes to the configuration. A setting of 0 disables the mechanism.
By default, this mechanism is set to 0 and is, therefore, disabled.

This mechanism is primarily provided to facilitate the development and
testing of the application in a controlled development or test environment.
The best practice, and this must be emphasized, is to disable this feature
for production systems to ensure optimal utilization of system resources.
Also, in a production system by disabling this feature, any accidental changes
to the agent configuration will not take effect until the deployment container
has been restarted.

The property that controls the hot-swap mechanism itself is hot-swap
enabled. This means that if the hot-swap mechanism is enabled and you change
the value of this property, the new value will take effect after the last
hot-swap load interval expires. This can be therefore used to dynamically
disable the entire hot-swap system. For example consider the following situation:

The deployment container is started with the load interval
set to 10 seconds. Therefore, changes made to the agent configuration are
picked up by the agent every 10 seconds.

If you modify the load interval value while the deployment
container is running and set it to 0, when the last load interval completes,
the agent will pick up this new value. Since the value is set to 0 the agent
will disable the hot-swap mechanism for the entire system.

Once disabled, the configuration changes made in the J2EE
agent AMAgent.properties configuration file will not
be sensed by the agent. Therefore, even if you reset the value of this property
now to any other number, it will not enable the hot-swap mechanism unless
the deployment container is restarted.

When the value of the load interval is set to 0 during the startup of
the deployment container, the hot-swap mechanism will be disabled and cannot
be enabled without restarting the server and ensuring that this value is set
to a value greater than 0.

List Constructs in the J2EE AMAgent.properties Configuration
File

Certain property keys in the J2EE agent AMAgent.properties configuration
file are specified as lists. A list construct has the following format:

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

Map Constructs in the J2EE AMAgent.properties Configuration
File

Certain property keys in the J2EE agent are specified as maps. A map
construct has the following format:

<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 5–2 Example of Map Constructs in J2EE AMAgent.properties File

J2EE Property Configuration: Application Specific
or Global

Certain property keys in the J2EE agent AMAgent.properties configuration
file can be configured for specific applications. Therefore, the agent can
use different values of the same property for different applications as defined
in the configuration file. Properties that are not configured for specific
applications apply to all the applications on that deployment container. Such
properties are called global properties. An application specific property
has the following format:

<key>[<appname>]=<value>

key

The configuration key (name of the configuration property)

appname

The application name to which this configuration belongs.
The application name is the context path of the application without the leading
forward slash character. In case when the application has been deployed at
the root-context of the server, the application name should be specified as DefaultWebApp.

value

The value used by the agent to protect the application identified
by the given application name

Note –

When an application specific configuration is not present, the
agent uses different mechanisms to identify a default value. Configurations
are possible where the default value is used as the value specified for the
same key without any application specific suffix [<appname>]. The
following settings for a single property serve as an example:

Example 5–3 Example of Application Specific and Global Configuration

J2EE Agent Filter Mode

Note –

With Agent for IBM WebSphere Portal Server 6.0, “J2EE_POLICY”
mode has an unconventional meaning. For this agent, J2EE_POLICY mode
actually enables single sign-on (SSO) only. This is the only mode supported
by this agent.

Set the J2EE agent filter mode to J2EE_POLICY with
Agent for IBM WebSphere Portal Server 6.0. The following configuration property in the J2EE
agent AMAgent.properties configuration file
is used to set the mode of the agent filter:

com.sun.identity.agents.config.filter.mode

Therefore set this property as follows:

com.sun.identity.agents.config.filter.mode = J2EE_POLICY

The J2EE_POLICY mode enables the agent filter and
agent realm to work together with various Access Manager services to ensure
SSO.

Enabling Failover in J2EE Agents

The agent allows basic failover capabilities. This helps you ensure
that if the primary Access Manager instance for which the agent has been configured
becomes unavailable, the agent will switch to the next Access Manager instance
as specified in the J2EE agent AMAgent.properties configuration
file. This setup can be achieved by implementing the following steps.

To Enable Failover in J2EE Agents

Provide a list of Access Manager authentication services URLs that
may be used by the agent to authenticate users who do not have sufficient
credentials to access the protected resources.

Configure the following
property to create the list:

com.sun.identity.agents.config.login.url

You may specify more than one login URL as follows:

com.sun.identity.agents.config.login.url[0] =primary-AM-server

com.sun.identity.agents.config.login.url[1]
=failover-AM-server1

com.sun.identity.agents.config.login.url[2]
=failover-AM-server2

primary-AM-server

Represents the URL of the primary Access Manager instance to
which users are redirected for authentication.

failover-AM-server1

Represents the URL of the Access Manager instance to which
users are redirected for authentication if the primary Access Manager instance
fails.

failover-AM-server2

Represents the URL of the Access Manager instance to which
users are redirected for authentication if the primary Access Manager instance
fails and the first failover Access Manager instance fails.

If a URL list is provided to this property, com.sun.identity.agents.config.login.url, the agent first tries to establish a connection to the first server
(primary-AM-server) specified in the URL list.
If the agent is successful in establishing this connection, it redirects the
user to the Access Manager instance for authentication.

(Optional) Turn prioritization on for the failover
lists by setting the following property to true:

com.sun.identity.agents.config.login.url.prioritized

Note –

Setting this property to true turns prioritization
on for the login URL list and the CDSSO URL list. The two cases shown in this
step specifically mention the login URL list. However, this explanation of
prioritization is exactly the same for the CDSSO URL list. The final step
in this procedure describes how to create the CDSSO URL list in case such
a scenario applies to your site's deployment.

The following cases describe the behavior of the agent in different
situations: when you turn on prioritization and when you do not turn on prioritization
for the login URL list.

Case 1: com.sun.identity.agents.config.login.url.prioritized = true

A value of true means that priority is established
for the login URL list described in Step 1. The list was created by configuring
the following property:

com.sun.identity.agents.config.login.url

Therefore, the first URL on the list, which is abbreviated here as .url[0], has a higher priority than .url[1] and .url[1] has higher priority than.url[2] and so
on. If the server (primary-AM-server) specified
in this example as the value for .url[0] is running, the
agent sends all requests to this server only. However, if primary-AM-server fails, from that point on, subsequent requests are sent to
the server (failover-AM-server1) associated with .url[1]. Furthermore, if at some point primary-AM-server comes
back, then the subsequent requests from that point on are sent to primary-AM-server, since it takes priority over failover-AM-server1.
This mechanism always fails back to the highest priority Access Manager instance
among the Access Manager instances that are running at the point in time the
agent must redirect requests to an Access Manager instance.

Case 2: com.sun.identity.agents.config.login.url.prioritized
= false

In this case, no server takes priority over
another. Failover occurs in a round-robin fashion. If all the servers are
running, the agent sends requests to the server (primary-AM-server)
associated with .url[0]. If primary-AM-server goes
down then all subsequent requests are sent to the server (failover-AM-server1) associated with .url[1]. The agent keeps
sending the requests to failover-AM-server1 unless
that server goes down. If failover-AM-server1 does
go down then the agent routes all the subsequent requests to the server (failover-AM-server2) associated with .url[2] until
it goes down. If it goes down, the agent tries to connect to primary-AM-server once again. Assuming that by then the primary-AM-server is running, all the subsequent requests from then on are sent
to primary-AM-server. This is a simple round-robin
mechanism without any priority involved.

Provide a list of Access Manager Naming Service URLs that may be
used by the agent to get access to the various other service URLs that may
be needed to serve the logged on user.

This can be done by using
the following property:

com.iplanet.am.naming.url

More than one naming service URL may be specified as a space delimited
list of URLs. The following example illustrates this idea:

com.iplanet.am.naming.url=primary-AM-serverfailover-AM-server1

(Conditional) If the deployment consists of an agent instance
that is on a different domain than multiple Access Manager instances for which
you want to enable failover, provide a URL list of the remote Access Manager instances.

Login Attempt Limit in J2EE Agents

When a user tries to access a protected resource without having authenticated
with Access Manager Authentication Services, the request is treated as a request
with insufficient credentials. The default action taken by the agent when
it encounters such a request is to redirect the user to the next available
Login URL as configured in the J2EE agent AMAgent.properties configuration
file.

Despite the repeated redirects performed by the agent, the user could
still be unable to furnish the necessary credentials. In such a case, the
agent can be directed to block such a request. This is configured using the
Login Attempt Limit configuration property. The configuration property that
controls this behavior is as follows:

com.sun.identity.agents.config.login.attempt.limit

If a non-zero positive value is specified for this property in the J2EE
agent AMAgent.properties configuration file, the agent
will only allow that many attempts before it blocks the access request without
the necessary credentials. When set to a value of zero, this feature is disabled.

To guard against potential denial-of-service attacks on the system,
enable this feature.

Redirect Attempt Limit in J2EE Agents

The processing of requests by the agent can result in redirects for
the client browser. Such redirects can happen when the user has not authenticated
with Access Manager Authentication Service, lacks the sufficient credentials
necessary to access a protected resource, and a variety of other reasons.

While the agent ensures that only the authenticated and authorized users
get access to the protected resources, there is a remote possibility that
due to misconfiguration of the system, the client browser may be put into
an infinite redirection loop.

The Redirect Attempt Limit configuration property allows you to guard
against such potential situations by ensuring that after a given number of
consecutive requests from a particular user that result in the same exact
redirect, the agent blocks the user request. This blocking of the request
is only temporary and is removed the moment the user makes a request that
does not result in the same redirect or results in access being granted to
the protected resource. The configuration property that controls this feature
is:

com.sun.identity.agents.config.redirect.attempt.limit

If a non-zero positive integer is specified as the value of this property,
the agent will break the redirection loop after the specified number of requests
result in the same redirects. When its value is set to zero, this feature
is disabled.

To protect the system from such situations, enable this feature. Furthermore,
enabling this feature can help in breaking potential denial of service attacks.

Not-Enforced URI List in J2EE Agents

The J2EE agent AMAgent.properties configuration
file allows you to specify a list of URIs that are treated as not-enforced.
Access to these resources is always granted by the agent. The configuration
property that controls this list is as follows:

com.sun.identity.agents.config.notenforced.uri

If the deployed application has pages that use a bulk of graphics that
do not require agent protection, the best practice is to add such content
to the agent’s not-enforced list to ensure the optimal utilization of
the system resources. The following is an example of the entries that you
may specify in the not-enforced list:

com.sun.identity.agents.config.notenforced.uri[0] = /images/*

com.sun.identity.agents.config.notenforced.uri[1] = /public/*.html

com.sun.identity.agents.config.notenforced.uri[2] = /registration/*

This enables the agent to focus on enforcing access control only over
requests that do not match these given URI patterns. The use of a wildcard
(*) is allowed to indicate the presence of one or more characters in the URI
pattern being specified.

Inverting the Not-Enforced URI List

In situations where only a small portion of the deployed application
requires protection, you can configure the agent to do just that by inverting
the not-enforced list. This results in the agent enforcing access control
over the entries that are specified in the not-enforced list and allowing
access to all other resources on the system. This feature is controlled by
the following property:

com.sun.identity.agents.config.notenforced.uri.invert

When you set the value to true for this property,
it makes the entries specified in the not-enforced list as enforced entries
and the rest of the application resources are treated as not-enforced.

Caution –

When the not-enforced list is inverted, the number of resources
for which the agent will not enforce access control is potentially very large.
The use of this feature should therefore be used with extreme caution and
only after extensive evaluation of the security requirements of the deployed
applications.

Note –

When an Access Denied URI is specified, it is never enforced
by the agent regardless of the configuration of the not-enforced list. This
is necessary to ensure that the agent can use the Access Denied URI to block
any unauthorized access for protected system resources.

When configuring access denied URIs within the deployment
descriptor of the web application, you must ensure that these values are added
to the not-enforced list of the agent. Failing to do so can result in application
resources becoming inaccessible by the user.

Any resource that has been added to the not-enforced list
must not access any protected resource. If it does so, it can result in unauthorized
access to protected system resources. For example, if a servlet that has been
added to the not-enforced list, in turn sends the request to another servlet,
which is protected, it can potentially lead to unauthorized access to the
protected servlet.

Fetching Attributes in J2EE Agents

Certain applications rely on the presence of user-specific profile information
in some form in order to process the user requests appropriately. J2EE agents
provide the functionality that can help such applications by making these
attributes from the user's profile available in various forms. Policy Agent 2.2 allows
the following attribute types to be fetched using the corresponding property
from the J2EE agent AMAgent.properties configuration
file:

Profile Attributes

com.sun.identity.agents.config.profile.attribute.fetch.mode

Session Attributes

com.sun.identity.agents.config.session.attribute.fetch.mode

Policy Response Attributes

com.sun.identity.agents.config.response.attribute.fetch.mode

The following values are possible for these three properties:

NONE

HEADER

REQUEST_ATTRIBUTE

COOKIE

The default value for these properties is NONE, which
specifies that that particular attribute type (profile attribute, session
attribute, or policy response attribute) is not fetched. The other possible
values (HEADER, REQUEST_ATTRIBUTE, or COOKIE) that can be used with these properties specify which method
will be used to fetch a given attribute type. For more information, see Methods for Fetching Attributes in J2EE Agents.

Depending upon how these values are set, the agent retrieves the necessary
attributes available for the logged on user and makes them available to the
application.

The following subsections provide information about how to set the type
of attribute that is fetched.

Fetching Profile Attributes in J2EE Agents

To obtain user-specific information by fetching profile attributes,
assign a mode to the profile attribute property and map the profile attributes
to be populated under specific names for the currently authenticated user.
The following example first demonstrates how to assign the REQUEST_ATTRIBUTE mode for fetching profile attributes and then demonstrates a way
to map those attributes:

Fetching Session Attributes in J2EE Agents

To obtain user-specific information by fetching profile attributes,
assign a mode to the session attribute property and map the session attributes
to be populated under specific names for the currently authenticated user.
The following example first demonstrates how to assign the REQUEST_ATTRIBUTE mode for fetching session attributes and then demonstrates a way
to map those attributes:

Fetching Policy Response Attributes in J2EE Agents

To obtain user-specific information by fetching policy response attributes,
assign a mode to the policy response attribute property and map the policy
response attributes to be populated under specific names for the currently
authenticated user. The following example first demonstrates how to assign
the REQUEST_ATTRIBUTE mode for fetching policy response
attributes and then demonstrates a way to map those attributes:

Using this property for mapping policy response attributes, you can
specify any number of attributes that are required by the protected application.
For example, if the application requires the attributes cn and mail, and it expects these attributes to be available under the
names COMMON_NAME and EMAIL_ADDR, then
the configuration setting would be as follows:

Methods for Fetching Attributes in J2EE Agents

Fetching Attributes as HTTP Headers

When the agent is configured to provide the LDAP attributes as HTTP
headers, these attributes can be retrieved using the following methods on
the javax.servlet.http.HttpServletRequest interface:

long getDateHeader(java.lang.String name)

java.lang.String getHeader(java.lang.String name)

java.util.Enumeration getHeaderNames()

java.util.Enumeration getHeaders(java.lang.String name)

int getIntHeader(java.lang.String name)

The property that controls the parsing of a date value from an appropriate
string as set in the LDAP attribute is the following:

com.sun.identity.agents.config.attribute.date.format

This property defaults to the value EEE, d MMM yyyy hh:mm:ss
z and should be changed as necessary.

Multi-valued attributes can be retrieved as an instance of java.util.Enumeration from the following method:

java.util.Enumeration getHeaders(java.lang.String name)

Fetching Attributes as Request Attributes

When the agent is configured to provide the LDAP attributes as request
attributes, the agent populates these attribute values into the HttpServletRequest as attributes that can later be used by the application as necessary.
These attributes are populated as java.util.Set objects,
which must be cast to this type before they can be successfully used.

Fetching Attributes as Cookies

When the agent is configured to provide the LDAP attributes as cookies,
the necessary values are set as server specific cookies by the agent with
the path specified as “/.”

Multi-valued attributes are set as a single cookie value in a manner
that all values of the attribute are concatenated into a single string using
a separator character that can be specified by the following configuration
entry:

com.sun.identity.agents.config.attribute.cookie.separator

One of the tasks of the application is to parse this value back into
the individual values to ensure the correct interpretation of the multi-valued
LDAP attributes for the logged on user.

When you are fetching attributes as cookies, also use the cookie reset
functionality to ensure that these cookies get cleaned up from the client
browser when the client browser’s session expires. For more information,
see Using Cookie Reset Functionality in J2EE Agents.

Common Attribute Fetch Processing Related Properties

This section lists the most common configuration properties that are
used to influence attribute fetching.

com.sun.identity.agents.config.attribute.cookie.separator

This property allows you to assign a character to be used
to separate multiple values of the same attribute when it is being set as
a cookie. This property is set in the following manner:

com.sun.identity.agents.config.attribute.cookie.separator = |

com.sun.identity.agents.config.attribute.cookie.encode

This property is a flag that indicates if the value of the
attribute should be URL encoded before being set as a cookie. This property
is set in the following manner:

com.sun.identity.agents.config.attribute.cookie.encode = true

com.sun.identity.agents.config.attribute.date.format

This property allows you to set the format of date attribute
values to be used when the attribute is set to HTTP header. This format is
based on the definition as provided in java.text.SimpleDateFormat.
This property is set in the following manner:

Configuring FQDN Handling in J2EE Agents

To ensure appropriate user experience, the use of valid URLs by users
to access resources protected by the agent must be enforced. This functionality
is controlled by three separate properties:

com.sun.identity.agents.config.fqdn.check.enable

Enables FQDN

com.sun.identity.agents.config.fqdn.default

Stores the default FQDN value

com.sun.identity.agents.config.fqdn.mapping[]

Sets FQDN mapping

The configuration property for the default FQDN provides the information
required by the agent to identify if the user is using a valid URL to access
the protected resource. If the 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 now changed
by the agent to a fully qualified domain name (FQDN) as per the value specified
in this property.

The property FQDN Map provides another way by which the agent can resolve
malformed access URLs used by the users and take corrective action. The agent
gives precedence to entries defined in this property over the value defined
in the default FQDN property. If none of the entries in this property matches
the hostname specified in the user request, the agent uses the value specified
for default FQDN property to take the necessary corrective action.

The FQDN Map property can be used for creating a mapping for more than
one hostname. This can be done when the deployment container protected by
this agent can be accessed using more than one hostname. As an example, consider
a protected deployment container that can be accessed using the following
host names:

www.externalhostname.com

internalhostname.interndomain.com

IP address

In this case, assuming that www.externalhostname.com is
the default FQDN, then the FQDN Map can be configured as follows to allow
access to the application for users who will use the hostname internalhostname.interndomain.com or the raw IP address, say 192.101.98.45:

Using Cookie Reset Functionality in J2EE Agents

The agent allows you to reset certain cookies that may be present in
the user’s browser session if the user’s Access Manager session
has expired. This feature is controlled by the following configuration properties:

The preceding four properties can be used to specify the exact details
of the cookie that should be reset by the agent when a protected resource
is accessed without a valid session.

The com.sun.identity.agents.config.cookie.reset.name property
specifies a list of cookie names that will be reset by the agent when necessary.
Each entry in this list can correspond to a maximum of one entry in the com.sun.identity.agents.config.cookie.reset.domain property and
the com.sun.identity.agents.config.cookie.reset.path property,
both of which are used to define the cookie attributes - the domain on which
a particular cookie should be set and the path on which it will be set.

When using this feature, ensure that the correct values of the domain
and path are specified for every cookie entry in the cookie list. If these
values are inappropriate, the result might be that the cookie is not reset
in the client browser.

When a cookie entry does not have an associated domain specified in
the domain map, it is handled as a server cookie. Similarly, when a cookie
entry does not have a corresponding path entry specified, the anticipated
cookie path is “/.”

Enabling Port Check Functionality in J2EE Agents

In situations when Access Manager and the deployment container are installed
on the same system but on different ports, certain browsers may not send the
HOST header correctly to the agent in situations where there are redirects
involved between Access Manager Authentication Service and the agent. In such
situations, the agent, relying on the availability of the port number from
the deployment container, might misread the port number that the user is trying
to access.

When such a situation occurs, it can have a severe impact on the system
since the agent now senses a resource access that in reality did not occur
and consequently the subsequent redirects as well as any policy evaluations
may fail thereby making the protected application inaccessible to the end
user.

This situation can be controlled by enabling port check functionality
on the agent. This is controlled by the following configuration property:

com.sun.identity.agents.config.port.check.enable

When this property is set to true, the agent verifies
the correctness of the port number read from the request against its configuration.
The configuration that provides the reference for this checking is set by
the following property:

com.sun.identity.agents.config.port.check.setting

This property allows the agent to store a map of various ports and their
corresponding protocols. When the agent is installed, this map is populated
by the preferred port and protocol of the agent server as specified during
the installation. However, if the same agent is protecting more than one HTTP
listeners, you must add that information to the map accordingly.

When the agent discovers an invalid port in the request, it takes corrective
action by sending some HTML data to break the redirection chain so that the
browser can reset its HOST header on the subsequent request. This content
is read from the file that resides in the locale directory
of agent installation. The name of the file is controlled by the following
property:

com.sun.identity.agents.config.port.check.file

This property can also be used to specify the complete path to the file
that may be used to achieve this functionality. This file contains special
HTML that uses a META-EQUIV REFRESH tag in order to allow
the browser to continue automatically when the redirect chain is broken. Along
with this HTML, this file must contain the string am.filter.request.url,
which is dynamically replaced by the actual request URL by the agent.

You can modify the contents of this file or specify a different file
to be used, if necessary, so long as it contains the am.filter.request.url string that the agent can substitute in order to construct the
true request URL with the correct port. The contents of this file should be
such that it should either allow the user to automatically be sent to this
corrected location or let the user click on a link or a button to achieve
the same result.