Chapter 6. Configuring Policy Agent Profiles
Prev |  | Next

# Chapter 6. Configuring Policy Agent Profiles

You install policy agents in web servers and web application containers to enforce access policies OpenAM applies to protected web sites and web applications. Policy agents depend on OpenAM for all authentication and authorization decisions. Their primary responsibility consists in enforcing what OpenAM decides in a way that is unobtrusive to the user. In organizations with many servers, you might well install many policy agents.

Policy agents can have local configurations where they are installed, but usually you store all policy agent configuration information in the OpenAM configuration store, defining policy agent profiles for each, and then you let the policy agents access their profiles through OpenAM such that you manage all agent configuration changes centrally. This chapter describes how to set up policy agent profiles in OpenAM for centralized configuration.

## 6.1. Identity Gateway or Policy Agent?

OpenAM includes both the Identity Gateway and also a variety of policy agents. Both the Identity Gateway and also the policy agents enforce policy, redirecting users to authenticate when necessary, and controlling access to protected resources. Yet, the Identity Gateway runs as a self-contained reverse proxy located between the users and the protected applications. Policy agents are installed into the servers where applications run, intercepting requests in that context.

The Identity Gateway allows you to protect access to applications not suited for a policy agent. Not all web servers and Java EE applications have policy agents. Not all operating systems work with policy agents.

Policy agents have the advantage, where you can install them, of sitting within your existing server infrastructure. Once you have agents installed into the servers with web applications or sites to protect, then you can manage their configurations centrally from OpenAM.

Of course, for organizations with both servers where you can install policy agents and also applications that you must protect without touching the server, you can use policy agents on the former and the Identity Gateway for the latter.

## 6.2. Kinds of Agent Profiles

When you open the OpenAM console to configure agents for the top level realm, you can choose from a number of different types of agents. Web and J2EE policy agents are the most common, requiring the least integration effort.

Web

  You install web agents in web servers to protect web sites.

J2EE

  You install J2EE agents in web application containers to protect web applications.

Web Service Provider

  WSP agents are for use with Web Services Security.

Web Service Client

  WSC agents are for use with Web Services Security.

Discovery

  The Discovery Service agent has the trust authority configuration that OpenAM uses to communicate with a Liberty Discovery Service.

STS Client

  The Security Token Service client agent is for securing requests to the Security Token Service.

2.2 Agents

  Version 2.2 web and J2EE policy agents hold their configuration locally, connecting to OpenAM with a user name, password combination. This kind of agent is provided for backwards compatibility.

OAuth 2.0 Client Agent

  OAuth 2.0 clients are registered using this type of policy agent profile.

Agent Authenticator

  The agent authenticator can read agent profiles by connecting to OpenAM with a user name, password combination, but unlike the agent profile administrator, cannot change agent configuration.

## 6.3. Creating Agent Profiles

This section concerns creating agent profiles, and creating groups that let agents inherit settings when you have many agents with nearly the same profile settings.

Procedure 6.1. To Create an Agent Profile

To create a new web or J2EE policy agent profile, you need a name and password for the agent, and the URLs to OpenAM and the application to protect.

1. On the Access Control tab page of the OpenAM console, click the link for the realm in which you manage agents.

2. Click the Agents tab, click the tab page for the kind of agent you want to create, and then click the New... button in the Agent table.

3. Provide a name for the agent, and also the URLs to OpenAM and to the application to protect, then click Create.

   [D]

4. After creating the agent profile, you can click the link to the new profile to adjust and export the configuration.

Procedure 6.2. To Create an Agent Profile Group & Inherit Settings

Agent profile groups let you set up multiple agents to inherit settings from the group. To create a new web or J2EE agent profile group, you need a name and the URL to the OpenAM server in which you store the profile.

1. On the Access Control tab page of the OpenAM console, click the link for the realm in which you manage agents.

2. Click the Agents tab, click the tab page for the kind of agent you want to create, and then click the New... button in the Group table.

   After creating the group profile, you can click the link to the new group profile to fine-tune or export the configuration.

3. Inherit group settings by selecting your agent profile, and then selecting the group name in the Group drop-down list near the top of the profile page.

   You can then adjust inheritance by clicking Inheritance Settings on the agent profile page.

Procedure 6.3. To Create an Agent Profile Using the Command Line

You can create a policy agent profile in OpenAM using the ssoadm command-line tool. You do so by specifying the agent properties either as a list of attributes, or by using an agent properties file as shown below. Export an existing policy agent configuration before you start to see what properties you want to set when creating the agent profile.

The following procedure demonstrates creating a web policy agent profile using the ssoadm command.

1. Make sure the ssoadm command is installed as described in the Installation Guide procedure, To Set Up Administration Tools.

2. Determine the list of properties to set in the agent profile.

   The following properties file shows a minimal configuration for a web policy agent profile.

       $ cat myWebAgent.properties
       com.sun.identity.agents.config.agenturi.prefix=http://www.example.com:80/amagent
       com.sun.identity.agents.config.cdsso.cdcservlet.url[0]=https://openam.example.com:8443/openam/cdcservlet
       com.sun.identity.agents.config.fqdn.default=www.example.com
       com.sun.identity.agents.config.login.url[0]=http://openam.example.com:8443/openam/UI/Login
       com.sun.identity.agents.config.logout.url[0]=http://openam.example.com:8443/openam/UI/Logout
       com.sun.identity.agents.config.remote.logfile=amAgent_www_example_com_80.log
       com.sun.identity.agents.config.repository.location=centralized
       com.sun.identity.client.notification.url=http://www.example.com:80/UpdateAgentCacheServlet?shortcircuit=false
       com.sun.identity.client.notification.url=http://www.example.com:80/UpdateAgentCacheServlet?shortcircuit=false
       sunIdentityServerDeviceKeyValue[0]=agentRootURL=http://www.example.com:80/
       sunIdentityServerDeviceStatus=Active
       userpassword=password

3. Set up a password file used when authenticating to OpenAM.

       $ echo password > /tmp/pwd.txt
       $ chmod 400 /tmp/pwd.txt

4. Create the profile in OpenAM.

       $ ssoadm create-agent --realm /
        --agentname myWebAgent --agenttype WebAgent --adminid amadmin
        --password-file /tmp/pwd.txt --datafile myWebAgent.properties

       Agent configuration was created.

   At this point you can view the profile in OpenAM Console under Access Control > `Realm Name` > Agents to make sure the configuration is what you expect.

## 6.4. Delegating Agent Profile Creation

If you want to create policy agent profiles when installing policy agents, then you need the credentials of an OpenAM user who can read and write agent profiles.

You can use the OpenAM administrator account when creating policy agent profiles. If however you delegate policy agent installation, then you might not want to share OpenAM administrator credentials with everyone who installs policy agents.

Follow these steps to create agent administrator users for a realm.

1. In OpenAM console, browse to Access Control > `Realm Name` > Subjects.

2. Under Group click New... and create a group for agent administrators.

3. Switch to the Privileges tab for the realm, and click the name of the group you created.

4. Select "Read and write access to all configured Agents," and then Save your work.

5. Return to the Subjects tab, and under User create as many agent administrator users as needed.

6. For each agent administrator user, edit the user profile.

   Under the Group tab of the user profile, add the user to agent profile administrator group, and then Save your work.

7. Provide each system administrator who installs policy agents with their agent administrator credentials.

   When installing the policy agent with the `--custom-install` option, the system administrator can choose the option to create the profile during installation, and then provide the agent administrator user name and the path to a read-only file containing the agent administrator password.

## 6.5. Configuring Web Policy Agents

When you create a web policy agent profile and install the agent, you can choose to store the agent configuration centrally and configure the agent through OpenAM console. Alternatively, you can choose to store the agent configuration locally and configure the agent by changing values in the properties file. This section covers centralized configuration, indicating the corresponding properties for use in a local configuration file where applicable.[5]

### Tip

To show the agent properties in configuration file format that correspond to what you see in the console, click Export Configuration after editing agent properties.

This corresponds to the local Java properties configuration file that is set up when you install an agent, for example in `Agent_001/config/`.

After changing properties specified as "Hot swap: no" you must restart the agent for the changes to take effect.

### 6.5.1. Configuring Web Policy Agent Global Properties

This section covers global web agent properties. After creating the agent profile, you access these properties in the OpenAM console under Access Control > `Realm Name` > Agents > Web > `Agent Name` > Global.

Profile properties

Group

  For assigning the agent to a previously configured web agent group in order to inherit selected properties from the group.

Password

  Agent password used when creating the password file and when installing the agent.

Status

  Status of the agent configuration.

Location of Agent Configuration Repository

  Indicates agent's configuration located either on agent's host or centrally on OpenAM server.

  If you change this to a local configuration, you can no longer manage the policy agent configuration through OpenAM console.

  Property: `com.sun.identity.agents.config.repository.location`

Agent Configuration Change Notification

  Enable agent to receive notification messages from OpenAM server for configuration changes.

  Property: `com.sun.identity.agents.config.change.notification.enable`

Enable Notifications

  If enabled, the agent receives policy updates from the OpenAM notification mechanism to maintain its internal cache. If disabled, the agent must poll OpenAM for changes.

  Property: `com.sun.identity.agents.config.notification.enable`

  Hot swap: no

Agent Notification URL

  URL used by agent to register notification listeners.

  Property: `com.sun.identity.client.notification.url`

  Hot swap: no

Agent Deployment URI Prefix

  The default value is ``agent-root-URL`/amagent`.

  Property: `com.sun.identity.agents.config.agenturi.prefix`

  Hot swap: yes

Configuration Reload Interval

  Interval in minutes to fetch agent configuration from OpenAM. Used if notifications are disabled. Default: 60.

  Property: `com.sun.identity.agents.config.polling.interval`

  Hot swap: no

Configuration Cleanup Interval

  Interval in minutes to cleanup old agent configuration entries unless they are referenced by current requests. Default: 30.

  Property: `com.sun.identity.agents.config.cleanup.interval`

  Hot swap: no

Agent Root URL for CDSSO

  The agent root URL for CDSSO. The valid value is in the format ``protocol`://`hostname`:`port`/` where `protocol` represents the protocol used, such as `http` or `https`, `hostname` represents the host name of the system where the agent resides, and `port` represents the port number on which the agent is installed. The slash following the port number is required.

  If your agent system also has virtual host names, add URLs with the virtual host names to this list as well. OpenAM checks that `goto` URLs match one of the agent root URLs for CDSSO.

General properties

SSO Only Mode

  When enabled, agent only enforces authentication (SSO), but no policies for authorization.

  Property: `com.sun.identity.agents.config.sso.only`

Resources Access Denied URL

  The URL of the customized access denied page. If no value is specified (default), then the agent returns an HTTP status of 403 (Forbidden).

  Property: `com.sun.identity.agents.config.access.denied.url`

Agent Debug Level

  Default is `Error`. Increase to `Message` or even `All` for fine-grained detail.

  Property: `com.sun.identity.agents.config.debug.level`

  You can set the level in the configuration file by module using the format ``module`[:`level`][,`module`[:`level`]]*`, where `module` is one of `AuthService`, `NamingService`, `PolicyService`, `SessionService`, `PolicyEngine`, `ServiceEngine`, `Notification`, `PolicyAgent`, `RemoteLog`, or `all`, and `level` is one of the following.

  - `0`: Disable logging from specified module

    At this level the agent nevertheless logs messages having the level value `always`.

  - `1`: Log error messages

  - `2`: Log warning and error messages

  - `3`: Log info, warning, and error messages

  - `4`: Log debug, info, warning, and error messages

  - `5`: Like level 4, but with even more debugging messages

  When you omit `level`, the agent uses the default level, which is the level associated with the `all` module.

  The following example used in the local configuration sets the log overall level to debug for all messages.

      com.sun.identity.agents.config.debug.level=all:4

Agent Debug File Rotation

  When enabled, rotate the debug file when specified file size is reached.

  Property: `com.sun.identity.agents.config.debug.file.rotate`

Agent Debug File Size

  Debug file size in bytes beyond which the log file is rotated. The minimum is 1048576 bytes (1 MB), and lower values are reset to 1 MB. OpenAM console sets a default of 10 MB.

  Property: `com.sun.identity.agents.config.debug.file.size`

Audit properties

Audit Access Types

  Types of messages to log based on user URL access attempts.

  Property: `com.sun.identity.agents.config.audit.accesstype`

  Valid values for the configuration file property include `LOG_NONE`, `LOG_ALLOW`, `LOG_DENY`, and `LOG_BOTH`.

Audit Log Location

  Specifies where audit messages are logged. By default, audit messages are logged remotely.

  Property: `com.sun.identity.agents.config.log.disposition`

  Valid values for the configuration file property include `REMOTE`, `LOCAL`, and `ALL`.

Remote Log Filename

  Name of file stored on OpenAM server that contains agent audit messages if log location is remote or all.

  Property: `com.sun.identity.agents.config.remote.logfile`

  Hot swap: no

Remote Audit Log Interval

  Periodic interval in minutes in which audit log messages are sent to the remote log file.

  Property: `com.sun.identity.agents.config.remote.log.interval`

  Default: 5

  Hot swap: no

Rotate Local Audit Log

  When enabled, audit log files are rotated when reaching the specified size.

  Property: `com.sun.identity.agents.config.local.log.rotate`

Local Audit Log Rotation Size

  Beyond this size limit in bytes the agent rotates the local audit log file if rotation is enabled.

  Property: `com.sun.identity.agents.config.local.log.size`

  Default: 50 MB

Fully Qualified Domain Name Checking properties

FQDN Check

  Enables checking of FQDN default value and FQDN map values.

  Property: `com.sun.identity.agents.config.fqdn.check.enable`

FQDN Default

  Fully qualified domain name that the users should use in order to access resources. Without this value, the web server can fail to start, thus you set the property on agent installation, and only change it when absolutely necessary.

  This property ensures that when users access protected resources on the web server without specifying the FQDN, the agent can redirect the users to URLs containing the correct FQDN.

  Property: `com.sun.identity.agents.config.fqdn.default`

FQDN Virtual Host Map

  Enables virtual hosts, partial hostname and IP address to access protected resources. Maps invalid or virtual name keys to valid FQDN values so the agent can properly redirect users and the agents receive cookies belonging to the domain.

  To map `myserver` to `myserver.mydomain.example`, enter `myserver` in the Map Key field, and enter `myserver.mydomain.example` in the Corresponding Map Value field. This corresponds to `com.sun.identity.agents.config.fqdn.mapping[myserver]= myserver.mydomain.example`.

  Invalid FQDN values can cause the web server to become unusable or render resources inaccessible.

  Property: `com.sun.identity.agents.config.fqdn.mapping`

### 6.5.2. Configuring Web Policy Agent Application Properties

This section covers application web agent properties. After creating the agent profile, you access these properties in the OpenAM console under Access Control > `Realm Name` > Agents > Web > `Agent Name` > Application.

Not Enforced URL Processing properties

Ignore Path Info for Not Enforced URLs

  When enabled, the path info and query are stripped from the request URL before being compared with the URLs of the not enforced list for those URLs containing a wildcard character. This prevents a user from accessing `http://host/index.html` by requesting `http://host/index.html/hack.gif` when the not enforced list includes `http://host/*.gif`.

  ### Note

  This setting is not supported by the Varnish Cache agent.

  For a more generally applicable setting, see Ignore Path Info properties.

  Property: `com.sun.identity.agents.config.ignore.path.info.for.not.enforced.list`

Enable Regular Expressions for Not Enforced URLs (Not yet in OpenAM console)

  Enable use of Perl-compatible regular expressions in Not Enforced URL settings by using the following property under Advanced > Custom Properties in the agent profile.

      com.forgerock.agents.notenforced.url.regex.enable=true

Not Enforced URLs

  List of URLs for which no authentication is required. You can use wildcards to define a pattern for a URL.

  The `*` wildcard matches all characters except question mark (`?`), cannot be escaped, and spans multiple levels in a URL. Multiple forward slashes do not match a single forward slash, so `*` matches `mult/iple/dirs`, yet `mult/*/dirs` does not match `mult/dirs`.

  The `-*-` wildcard matches all characters except forward slash (`/`) or question mark (`?`), and cannot be escaped. As it does not match `/`, `-*-` does not span multiple levels in a URL.

  OpenAM does not let you mix `*` and `-*-` in the same URL.

  Examples include `http://www.example.com/logout.html`, `http://www.example.com/images/*`, `http://www.example.com/css/-*-`, and `http://www.example.com/*.jsp?locale=*`.

  Trailing forward slashes are not recognized as part of a resource name. Therefore `http://www.example.com/images//` and `http://www.example.com/images` are equivalent.

  Property: `com.sun.identity.agents.config.notenforced.url`

  If you enabled use of Perl-compatible regular expressions to match Not Enforced URLs, then all your settings must be done using regular expressions. (Do not mix settings; use either the mechanism described above or Perl-compatible regular expressions, but not both.)

  The following example shows settings where no authentication is required for URLs whose path ends `/publicA` or `/publicB` (with or without query string parameters), and no authentication is required to access .png, .jpg, .gif, .js, or .css files under URLs that do not contain `/protectedA/` or `/protectedB/`.

      .*/(PublicServletA|PublicServletB)(\?.*|$)
      ^(?!.*(/protectedA/|/protectedB/)).*\.(png|jpg|gif|js|css)(\?.*|$)

Invert Not Enforced URLs

  Only enforce not enforced list of URLs. In other words, enforce policy only for those URLs and patterns specified in the list.

  Property: `com.sun.identity.agents.config.notenforced.url.invert`

Fetch Attributes for Not Enforced URLs

  When enabled, the agent fetches profile, response, and session attributes that are mapped by doing policy evaluation, and forwards these attributes to not enforced URLs.

  Property: `com.sun.identity.agents.config.notenforced.url.attributes.enable`

Not Enforced IP Processing properties

Not Enforced Client IP List

  No authentication and authorization are required for the requests coming from these client IP addresses.

  Property: `com.sun.identity.agents.config.notenforced.ip`

CIDR Client IP Specification (Not yet in OpenAM console)

  As of version 3.0.4, web policy agents with this property set to `cidr` can use IPv4 netmasks and IP ranges instead of wildcards as values for Not Enforced Client IP addresses. Version 3.0.5 adds support for IPv6, including the IPv6 loopback address, `::1`.

  When the parameter is defined, wildcards are ignored in Not Enforced Client IP settings. Instead, you can use settings such as those shown in the following examples.

  Netmask Example

    To disable policy agent enforcement for addresses in 192.168.1.1 to 192.168.1.255, use the following setting.

        com.sun.identity.agents.config.notenforced.ip = 192.168.1.1/24

    The following example shows an IPv6 address with a corresponding network mask.

        com.sun.identity.agents.config.notenforced.ip = 2001:5c0:9168:0:0:0:0:2/128

    Currently the policy agent stops evaluating properties after reaching an invalid netmask in the list.

  IP Range Example

    To disable policy agent enforcement for addresses between 192.168.1.1 to 192.168.4.3 inclusive, use the following setting.

        com.sun.identity.agents.config.notenforced.ip = 192.168.1.1-192.168.4.3

    The following example shows a range of IPv6 addresses.

        com.sun.identity.agents.config.notenforced.ip = 2001:5c0:9168:0:0:0:0:1-2001:5c0:9168:0:0:0:0:2

  Property: `com.forgerock.agents.config.notenforced.ip.handler`

  Hot swap: no

Client IP Validation

  When enabled, validate that the subsequent browser requests come from the same IP address that the SSO token is initially issued against.

  Property: `com.sun.identity.agents.config.client.ip.validation.enable`

Profile Attributes Processing properties

Profile Attribute Fetch Mode

  When set to `HTTP_COOKIE` or `HTTP_HEADER`, profile attributes are introduced into the cookie or the headers, respectively.

  Property: `com.sun.identity.agents.config.profile.attribute.fetch.mode`

Profile Attribute Map

  Maps the profile attributes to HTTP headers for the currently authenticated user. Map Keys are LDAP attribute names, and Map Values are HTTP header names.

  To populate the value of profile attribute CN under `CUSTOM-Common-Name`: enter CN in the Map Key field, and enter `CUSTOM-Common-Name` in the Corresponding Map Value field. This corresponds to `com.sun.identity.agents.config.profile.attribute.mapping[cn]=CUSTOM-Common-Name`.

  In most cases, in a destination application where an HTTP header name shows up as a request header, it is prefixed by `HTTP_`, lower case letters become upper case, and hyphens (`-`) become underscores (`_`). For example, `common-name` becomes `HTTP_COMMON_NAME`.

  Property: `com.sun.identity.agents.config.profile.attribute.mapping`

Response Attributes Processing properties

Response Attribute Fetch Mode

  When set to `HTTP_COOKIE` or `HTTP_HEADER`, response attributes are introduced into the cookie or the headers, respectively.

  Property: `com.sun.identity.agents.config.response.attribute.fetch.mode`

Response Attribute Map

  Maps the policy response attributes to HTTP headers for the currently authenticated user. The response attribute is the attribute in the policy response to be fetched.

  To populate the value of response attribute `uid` under `CUSTOM-User-Name`: enter `uid` in the Map Key field, and enter `CUSTOM-User-Name` in the Corresponding Map Value field. This corresponds to `com.sun.identity.agents.config.response.attribute.mapping[uid]=Custom-User-Name`.

  In most cases, in a destination application where an HTTP header name shows up as a request header, it is prefixed by `HTTP_`, lower case letters become upper case, and hyphens (`-`) become underscores (`_`). For example, `response-attr-one` becomes `HTTP_RESPONSE_ATTR_ONE`.

  Property: `com.sun.identity.agents.config.response.attribute.mapping`

Session Attributes Processing properties

Session Attribute Fetch Mode

  When set to `HTTP_COOKIE` or `HTTP_HEADER`, session attributes are introduced into the cookie or the headers, respectively.

  Property: `com.sun.identity.agents.config.session.attribute.fetch.mode`

Session Attribute Map

  Maps session attributes to HTTP headers for the currently authenticated user. The session attribute is the attribute in the session to be fetched.

  To populate the value of session attribute `UserToken` under `CUSTOM-userid`: enter `UserToken` in the Map Key field, and enter `CUSTOM-userid` in the Corresponding Map Value field. This corresponds to `com.sun.identity.agents.config.session.attribute.mapping[UserToken] =CUSTOM-userid`.

  In most cases, in a destination application where an HTTP header name shows up as a request header, it is prefixed by `HTTP_`, lower case letters become upper case, and hyphens (`-`) become underscores (`_`). For example, `success-url` becomes `HTTP_SUCCESS_URL`.

  Property: `com.sun.identity.agents.config.session.attribute.mapping`

Common Attributes Fetching Processing properties

Attribute Multi Value Separator

  Specifies separator for multiple values. Applies to all types of attributes such as profile, session and response attributes. Default: `|`.

  Property: `com.sun.identity.agents.config.attribute.multi.value.separator`

### 6.5.3. Configuring Web Policy Agent SSO Properties

This section covers SSO web agent properties. After creating the agent profile, you access these properties in the OpenAM console under Access Control > `Realm Name` > Agents > Web > `Agent Name` > SSO

Cookie properties

Cookie Name

  Name of the SSO Token cookie used between the OpenAM server and the agent. Default: `iPlanetDirectoryPro`.

  Property: `com.sun.identity.agents.config.cookie.name`

  Hot swap: no

Cookie Security

  When enabled, the agent marks cookies secure, sending them only if the communication channel is secure.

  Property: `com.sun.identity.agents.config.cookie.secure`

  Hot swap: no

HTTPOnly Cookies (Not yet in OpenAM console)

  As of version 3.0.5, web policy agents with this property set to `true` mark cookies as HTTPOnly, to prevent scripts and third-party programs from accessing the cookies.

  Property: `com.sun.identity.cookie.httponly`

Cross Domain SSO properties

Cross Domain SSO

  Enables Cross Domain Single Sign On.

  Property: `com.sun.identity.agents.config.cdsso.enable`

CDSSO Servlet URL

  List of URLs of the available CDSSO controllers that the agent can use for CDSSO processing. For example, `http://openam.example.com:8080/openam/cdcservlet`.

  Property: `com.sun.identity.agents.config.cdsso.cdcservlet.url`

Cookies Domain List

  List of domains, such as `.example.com`, in which cookies have to be set in CDSSO. If this property is left blank, then the fully qualified domain name of the cookie for the agent server is used to set the cookie domain, meaning that a host cookie rather than a domain cookie is set.

  To set the list to `.example.com`, and `.example.net` using the configuration file property, include the following.

      com.sun.identity.agents.config.cdsso.cookie.domain[0]=.example.com
      com.sun.identity.agents.config.cdsso.cookie.domain[1]=.example.net

  Property: `com.sun.identity.agents.config.cdsso.cookie.domain`

Cookie Reset properties

Cookie Reset

  When enabled, agent resets cookies in the response before redirecting to authentication.

  Property: `com.sun.identity.agents.config.cookie.reset.enable`

Cookie Reset Name List

  List of cookies in the format ``name`[=`value`][;Domain=`value`]`.

  Concrete examples include the following with two list items configured.

  - `LtpaToken`, corresponding to `com.sun.identity.agents.config.cookie.reset[0]=LtpaToken`. The default domain is taken from FQDN Default.

  - `token=value;Domain=subdomain.domain.com`, corresponding to `com.sun.identity.agents.config.cookie.reset[1]= token=value;Domain=subdomain.domain.com`

  Property: `com.sun.identity.agents.config.cookie.reset`

### 6.5.4. Configuring Web Policy Agent OpenAM Services Properties

This section covers OpenAM services web agent properties. After creating the agent profile, you access these properties in the OpenAM console under Access Control > `Realm Name` > Agents > Web > `Agent Name` > OpenAM Services.

Login URL properties

OpenAM Login URL

  OpenAM login page URL, such as `http://openam.example.com:8080/openam/UI/Login`, to which the agent redirects incoming users without sufficient credentials so then can authenticate.

  Property: `com.sun.identity.agents.config.login.url`

OpenAM Conditional Login URL (Not yet in OpenAM console)

  To conditionally redirect users based on the incoming request URL, set this property.

  This takes the incoming request domain to match, a vertical bar ( `|` ), and then a comma-separated list of URLs to which to redirect incoming users.

  If the domain before the vertical bar matches an incoming request URL, then the policy agent uses the list of URLs to determine how to redirect the user-agent. If the global property FQDN Check (`com.sun.identity.agents.config.fqdn.check.enable`) is enabled for the policy agent, then the policy agent iterates through the list until it finds an appropriate redirect URL that matches the FQDN check. Otherwise, the policy agent redirects the user-agent to the first URL in the list.

  Property: `com.forgerock.agents.conditional.login.url`

  Examples: `com.forgerock.agents.conditional.login.url[0]= login.example.com|http://openam1.example.com/openam/UI/Login, http://openam2.example.com/openam/UI/Login`, `com.forgerock.agents.conditional.login.url[1]= signin.example.com|http://openam3.example.com/openam/UI/Login, http://openam4.example.com/openam/UI/Login`

  If CDSSO is enabled for the policy agent, then this property takes CDSSO Servlet URLs for its values (`com.sun.identity.agents.config.cdsso.cdcservlet.url`), rather than OpenAM login URLs.

  CDSSO examples: `com.forgerock.agents.conditional.login.url[0]= login.example.com|http://openam1.example.com/openam/cdcservlet, http://openam2.example.com/openam/cdcservlet`, `com.forgerock.agents.conditional.login.url[1]= signin.example.com|http://openam3.example.com/openam/cdcservlet, http://openam4.example.com/openam/cdcservlet`

Agent Connection Timeout

  Timeout period in seconds for an agent connection with OpenAM auth server.

  Property: `com.sun.identity.agents.config.auth.connection.timeout`

  Default: 2

Polling Period for Primary Server

  Interval in minutes, agent polls to check the primary server is up and running. Default: 5.

  Property: `com.sun.identity.agents.config.poll.primary.server`

  Hot swap: no

Logout URL properties

OpenAM Logout URL

  OpenAM logout page URL, such as `http://openam.example.com:8080/openam/UI/Logout`.

  Property: `com.sun.identity.agents.config.logout.url`

Enable Logout URL Redirect (Not yet in OpenAM console)

  Logout URL redirect is enabled by default.

  When this is disabled, instead of redirecting the user-agent, the policy agent performs session logout in the background and then continues processing access to the current URL. Disable this using Advanced > Custom Properties in the agent profile.

      com.forgerock.agents.config.logout.redirect.disable=true

Agent Logout URL properties

Logout URL List

  List of application logout URLs, such as `http://www.example.com/logout.html`. The user is logged out of the OpenAM session when these URLs are accessed. When using this property, specify a value for the Logout Redirect URL property.

  Property: `com.sun.identity.agents.config.agent.logout.url`

Agent Logout URL Regular Expression (Not yet in OpenAM console)

  Perl-compatible regular expression that matches logout URLs. Set this using Advanced > Custom Properties in the agent profile.

  For example, to match URLs with `protectedA` or `protectedB` in the path and `op=logout` in the query string, use the following setting.

      com.forgerock.agents.agent.logout.url.regex= \
         .*(/protectedA\?|/protectedB\?/).*(\&op=logout\&)(.*|$)

  When you use this property, the agent ignores the settings for Logout URL List.

Logout Cookies List for Reset

  Cookies to be reset upon logout in the same format as the cookie reset list.

  Property: `com.sun.identity.agents.config.logout.cookie.reset`

Logout Redirect URL

  User gets redirected to this URL after logout. Specify this property alongside a Logout URL List.

  Property: `com.sun.identity.agents.config.logout.redirect.url`

Policy Client Service properties

Policy Cache Polling Period

  Polling interval in minutes during which an entry remains valid after being added to the agent's cache.

  Property: `com.sun.identity.agents.config.policy.cache.polling.interval`

  Hot swap: no

SSO Cache Polling Period

  Polling interval in minutes during which an SSO entry remains valid after being added to the agent's cache.

  Property: `com.sun.identity.agents.config.sso.cache.polling.interval`

  Hot swap: no

User ID Parameter

  Agent sets this value for User Id passed in the session from OpenAM to the REMOTE_USER server variable. Default: UserToken.

  Property: `com.sun.identity.agents.config.userid.param`

User ID Parameter Type

  User ID can be fetched from either SESSION and LDAP attributes. Default: `SESSION`.

  Property: `com.sun.identity.agents.config.userid.param.type`

Fetch Policies from Root Resource

  When enabled, the agent caches the policy decision of the resource and all resources from the root of the resource down. For example, if the resource is `http://host/a/b/c`, then the root of the resource is `http://host/`. This setting can be useful when a client is expect to access multiple resources on the same path. Yet, caching can be expensive if very many policies are defined for the root resource.

  Property: `com.sun.identity.agents.config.fetch.from.root.resource`

  Default: false

  Hot swap: no

Retrieve Client Hostname

  When enabled, get the client hostname through DNS reverse lookup for use in policy evaluation. This setting can impact performance.

  Property: `com.sun.identity.agents.config.get.client.host.name`

Policy Clock Skew

  Time in seconds used adjust time difference between agent system and OpenAM. Clock skew in seconds = AgentTime - OpenAMServerTime.

  Use this property to adjust for small time differences encountered despite use of a time synchronization service. When this property is not set and agent time is greater than OpenAM server time, the agent can make policy calls to the OpenAM server before the policy subject cache has expired, or you can see infinite redirection occur.

  Property: `com.sun.identity.agents.config.policy.clock.skew`

  Hot swap: no

### 6.5.5. Configuring Web Policy Agent Miscellaneous Properties

This section covers miscellaneous web agent properties. After creating the agent profile, you access these properties in the OpenAM console under Access Control > `Realm Name` > Agents > Web > `Agent Name` > Miscellaneous.

Advice Handling properties

Composite Advice Handling (Not yet in OpenAM console)

  As of version 3.0.4, when set to `true`, the agent sends composite advice in the query (GET request) instead of sending it through a POST request.

  Property: `com.sun.am.use_redirect_for_advice`

Locale properties

Agent Locale

  The default locale for the agent.

  Property: `com.sun.identity.agents.config.locale`

  Hot swap: no

Anonymous user properties

Anonymous User

  Enable or disable REMOTE_USER processing for anonymous users.

  Property: `com.sun.identity.agents.config.anonymous.user.enable`

Cookie Processing properties

Encode special chars in Cookies

  When enabled, encode special chars in cookie by URL encoding. This is useful when profile, session, and response attributes contain special characters, and the attributes fetch mode is set to `HTTP_COOKIE`.

  Property: `com.sun.identity.agents.config.encode.cookie.special.chars.enable`

Profile Attributes Cookie Prefix

  Sets cookie prefix in the attributes headers. Default: `HTTP_`.

  Property: `com.sun.identity.agents.config.profile.attribute.cookie.prefix`

Profile Attributes Cookie Maxage

  Maximum age in seconds of custom cookie headers. Default: 300.

  Property: `com.sun.identity.agents.config.profile.attribute.cookie.maxage`

URL Handling properties

URL Comparison Case Sensitivity Check

  When enabled, enforces case insensitivity in both policy and not enforced URL evaluation.

  Property: `com.sun.identity.agents.config.url.comparison.case.ignore`

Encode URL's Special Characters

  When enabled, encodes the URL which has special characters before doing policy evaluation.

  Property: `com.sun.identity.agents.config.encode.url.special.chars.enable`

Ignore Naming URL properties

Ignore Preferred Naming URL in Naming Request

  When enabled, do not send a preferred naming URL in the naming request.

  Property: `com.sun.identity.agents.config.ignore.preferred.naming.url`

Invalid URL properties (Not yet in OpenAM console)

Invalid URL Regular Expression

  Use a Perl-compatible regular expression to filter out invalid request URLs. The policy agent reject requests to invalid URLs with HTTP 403 Forbidden status without further processing. Use Advanced > Custom Properties to set this in the agent profile.

  For example, to filter out URLs containing the symbols in the list ./, /., /, ., ,\, %00-%1f, %7f-%ff, %25, %2B, %2C, %7E, .info, use the following setting.

      com.forgerock.agents.agent.invalid.url.regex= \
       ^((?!(|/\.|\./||*|\.info|%25|%2B|%2C|%[0-1][0-9a-fA-F]|%[7-9a-fA-F][0-9a-fA-F])).)$

Ignore Server Check properties

Ignore Server Check

  When enabled, do not check whether OpenAM is up before doing a 302 redirect.

  Property: `com.sun.identity.agents.config.ignore.server.check`

Ignore Path Info properties

Ignore Path Info in Request URL

  When enabled, strip path info from the request URL while doing the Not Enforced List check, and URL policy evaluation. This is designed to prevent a user from accessing a URI by appending the matching pattern in the policy or not enforced list.

  ### Note

  This setting is not supported by the Varnish Cache agent.

  For example, if the not enforced list includes `http://host/*.gif`, then stripping path info from the request URI prevents access to `http://host/index.html` by using `http://host/index.html?hack.gif`.

  However, when a web server is configured as a reverse proxy for a J2EE application server, the path info is interpreted to map a resource on the proxy server rather than the application server. This prevents the not enforced list or the policy from being applied to the part of the URI below the application server path if a wildcard character is used.

  For example, if the not enforced list includes `http://host/webapp/servcontext/*` and the request URL is `http://host/webapp/servcontext/example.jsp`, the path info is `/servcontext/example.jsp` and the resulting request URL with path info stripped is `http://host/webapp/`, which does not match the not enforced list. Thus when this property is enabled, path info is not stripped from teh request URL even if there is a wildcard in the not enforced list or policy.

  Make sure therefore when this property is enabled that there is nothing following the wildcard in the not enforced list or policy.

  Property: `com.sun.identity.agents.config.ignore.path.info`

Multi-byte Enable properties

Native Encoding of Profile Attributes

  When enabled, the agent encodes the LDAP header values in the default encoding of operating system locale. When disabled, the agent uses UTF-8.

  Property: `com.sun.identity.agents.config.convert.mbyte.enable`

Goto Parameter Name properties

Goto Parameter Name

  Property used only when CDSSO is enabled. Only change the default value, `goto` when the login URL has a landing page specified such as, `com.sun.identity.agents.config.cdsso.cdcservlet.url = http://openam.example.com:8080/openam/cdcservlet?goto= http://www.example.com/landing.jsp`. The agent uses this parameter to append the original request URL to this cdcservlet URL. The landing page consumes this parameter to redirect to the original URL.

  As an example, if you set this value to `goto2`, then the complete URL sent for authentication is `http://openam.example.com:8080/openam/cdcservlet?goto= http://www.example.com/landing.jsp?goto2=http://www.example.com/original.jsp`.

  Property: `com.sun.identity.agents.config.redirect.param`

Deprecated Agent properties

Anonymous User Default Value

  User ID of unauthenticated users. Default: `anonymous`.

  Property: `com.sun.identity.agents.config.anonymous.user.id`

### 6.5.6. Configuring Web Policy Agent Advanced Properties

This section covers advanced web agent properties. After creating the agent profile, you access these properties in the OpenAM console under Access Control > `Realm Name` > Agents > Web > `Agent Name` > Advanced.

Client Identification properties

If the agent is behind a proxy or load balancer, then the agent can get client IP and host name values from the proxy or load balancer. For proxies and load balancer that support providing the client IP and host name in HTTP headers, you can use the following properties.

When multiple proxies are load balancers sit in the request path, the header values can include a comma-separated list of values with the first value representing the client, as in `client,next-proxy,first-proxy`.

Client IP Address Header

  HTTP header name that holds the IP address of the client.

  Property: `com.sun.identity.agents.config.client.ip.header`

Client Hostname Header

  HTTP header name that holds the hostname of the client.

  Property: `com.sun.identity.agents.config.client.hostname.header`

Load Balancer properties

Load Balancer Setup

  Enable if a load balancer is used for OpenAM services.

  Property: `com.sun.identity.agents.config.load.balancer.enable`

  Hot swap: no

Override Request URL Protocol

  Enable if the agent is sitting behind a SSL/TLS off-loader, load balancer, or proxy such that the protocol users use is different from the protocol the agent uses. When enabled, the protocol is overridden with the value from the Agent Deployment URI Prefix (property: `com.sun.identity.agents.config.agenturi.prefix`).

  Property: `com.sun.identity.agents.config.override.protocol`

Override Request URL Host

  Enable if the agent is sitting behind a SSL/TLS off-loader, load balancer, or proxy such that the host name users use is different from the host name the agent uses. When enabled, the host is overridden with the value from the Agent Deployment URI Prefix (property: `com.sun.identity.agents.config.agenturi.prefix`).

  Property: `com.sun.identity.agents.config.override.host`

Override Request URL Port

  Enable if the agent is sitting behind a SSL/TLS off-loader, load balancer, or proxy such that the port users use is different from the port the agent uses. When enabled, the port is overridden with the value from the Agent Deployment URI Prefix (property: `com.sun.identity.agents.config.agenturi.prefix`).

  Property: `com.sun.identity.agents.config.override.port`

Override Notification URL

  Enable if the agent is sitting behind a SSL/TLS off-loader, load balancer, or proxy such that the URL users use is different from the URL the agent uses. When enabled, the URL is overridden with the value from the Agent Deployment URI Prefix (property: `com.sun.identity.agents.config.agenturi.prefix`).

  Property: `com.sun.identity.agents.config.override.notification.url`

Post Data Preservation properties

POST Data Preservation

  Enables HTTP POST data preservation. This feature is available in the Apache 2.2, Microsoft IIS 6, Microsoft IIS 7, and Sun Java System Web Server web policy agents as of version 3.0.3.

  Property: `com.sun.identity.agents.config.postdata.preserve.enable`

POST Data Entries Cache Period

  POST cache entry lifetime in minutes. Default: 10.

  Property: `com.sun.identity.agents.config.postcache.entry.lifetime`

POST Data Preservation Cookie Name (Not yet in OpenAM Console)

  When HTTP POST data preservation is enabled, override properties are set to true, and the agent is behind a load balancer, then this property sets the name and value of the sticky cookie to use.

  Property: `com.sun.identity.agents.config.postdata.preserve.lbcookie`

Post Data Preservation URI Prefix (Not yet in OpenAM Console)

  If you run multiple web servers with policy agents behind a load balancer that directs traffic based on the request URI, and you need to preserve POST data, then set this property.

  By default, policy agents use a dummy URL for POST data preservation, `http://`agent.host`:`port`/dummypost/sunpostpreserve`, to handle POST data across redirects to and from OpenAM. When you set this property, the policy agent prefixes the property value to the dummy URL path. In other words, when you set `com.forgerock.agents.config.pdpuri.prefix = app1`, the policy agent uses the dummy URL, `http://`agent.host`:`port`/app1/dummypost/sunpostpreserve`.

  Next, use the prefix you set when you define load balancer URI rules. This ensures that clients end up being redirected to the policy agent that preserved the POST data.

  Property: `com.forgerock.agents.config.pdpuri.prefix`

Sun Java System Proxy Server properties

Override Proxy Server's Host and Port

  When enabled ignore the host and port settings.

  Property: `com.sun.identity.agents.config.proxy.override.host.port`

  Hot swap: no

Microsoft IIS Server properties

Authentication Type

  The agent should normally perform authentication, so this is not required. If necessary, set to `none`.

  Property: `com.sun.identity.agents.config.iis.auth.type`

  Hot swap: no

Replay Password Key

  DES key for decrypting the basic authentication password in the session.

  Property: `com.sun.identity.agents.config.replaypasswd.key`

Filter Priority

  The loading priority of filter, DEFAULT, HIGH, LOW, or MEDIUM.

  Property: `com.sun.identity.agents.config.iis.filter.priority`

Filter configured with OWA

  Enable if the IIS agent filter is configured for OWA.

  Property: `com.sun.identity.agents.config.iis.owa.enable`

Change URL Protocol to https

  Enable to avoid IE6 security pop-ups.

  Property: `com.sun.identity.agents.config.iis.owa.enable.change.protocol`

Idle Session Timeout Page URL

  URL of the local idle session timeout page.

  Property: `com.sun.identity.agents.config.iis.owa.enable.session.timeout.url`

IBM Lotus Domino Server properties

Check User in Domino Database

  When enabled, the agent checks whether the user exists in the Domino name database.

  Property: `com.sun.identity.agents.config.domino.check.name.database`

Use LTPA token

  Enable if the agent needs to use LTPA Token.

  Property: `com.sun.identity.agents.config.domino.ltpa.enable`

LTPA Token Cookie Name

  The name of the cookie that contains the LTPA token.

  Property: `com.sun.identity.agents.config.domino.ltpa.cookie.name`

LTPA Token Configuration Name

  The configuration name that the agent uses in order to employ the LTPA token mechanism.

  Property: `com.sun.identity.agents.config.domino.ltpa.config.name`

LTPA Token Organization Name

  The organization name to which the LTPA token belongs.

  Property: `com.sun.identity.agents.config.domino.ltpa.org.name`

Custom properties

Custom Properties

  Additional properties to augment the set of properties supported by agent. Such properties take the following forms.

  - `customproperty=custom-value1`

  - `customlist[0]=customlist-value-0`

  - `customlist[1]=customlist-value-1`

  - `custommap[key1]=custommap-value-1`

  - `custommap[key2]=custommap-value-2`

  Property: `com.sun.identity.agents.config.freeformproperties`

## 6.6. Configuring J2EE Policy Agents

When you create a J2EE policy agent profile and install the agent, you can choose to store the agent configuration centrally and configure the agent through OpenAM console. Alternatively, you can choose to store the agent configuration locally and configure the agent by changing values in the properties file. This section covers centralized configuration, indicating the corresponding properties for use in a local configuration file where applicable.[6]

### Tip

To show the agent properties in configuration file format that correspond to what you see in the console, click Export Configuration after editing agent properties.

After changing properties specified as "Hot swap: no" you must restart the agent.

### 6.6.1. Configuring J2EE Policy Agent Global Properties

This section covers global web agent properties. After creating the agent profile, you access these properties in the OpenAM console under Access Control > `Realm Name` > Agents > J2EE > `Agent Name` > Global.

Profile properties

Group

  For assigning the agent to a previously configured web agent group in order to inherit selected properties from the group.

Password

  Agent password used when creating the password file and when installing the agent.

Status

  Status of the agent configuration.

Agent Notification URL

  URL used by agent to register notification listeners.

  Property: `com.sun.identity.client.notification.url`

  Hot swap: no

Location of Agent Configuration Repository

  Indicates agent's configuration located either on agent's host or centrally on OpenAM server.

  If you change this to a local configuration, you can no longer manage the policy agent configuration through OpenAM console.

  Property: `com.sun.identity.agents.config.repository.location`

Configuration Reload Interval

  Interval in seconds to fetch agent configuration from OpenAM. Used if notifications are disabled. Default: 0

  Property: `com.sun.identity.agents.config.load.interval`

Agent Configuration Change Notification

  Enable agent to receive notification messages from OpenAM server for configuration changes.

  Property: `com.sun.identity.agents.config.change.notification.enable`

Agent Root URL for CDSSO

  The agent root URL for CDSSO. The valid value is in the format ``protocol`://`hostname`:`port`/` where `protocol` represents the protocol used, such as `http` or `https`, `hostname` represents the host name of the system where the agent resides, and `port` represents the port number on which the agent is installed. The slash following the port number is required.

  If your agent system also has virtual host names, add URLs with the virtual host names to this list as well. OpenAM checks that `goto` URLs match one of the agent root URLs for CDSSO.

General properties

Agent Filter Mode

  Specifies how the agent filters requests to protected web applications. The global value functions as a default, and applies for protected applications that do not have their own filter settings. Valid settings include the following.

  `ALL`

    Enforce both the J2EE policy defined for the web container where the protected application runs, and also OpenAM policies.

    When setting the filter mode to `ALL`, set the Map Key, but do not set any Corresponding Map Value.

  `J2EE_POLICY`

    Enforce only the J2EE policy defined for the web container where the protected application runs.

  `NONE`

    Do not enforce policies to protect resources. In other words, turn off access management. Not for use in production.

  `SSO_ONLY`

    Enforce only authentication, not policies.

  `URL_POLICY`

    Enforce only OpenAM, URL resource based policies.

    When setting the filter mode to `URL_POLICY`, set the Map Key to the application name and the Corresponding Map Value to `URL_POLICY`.

  Property: `com.sun.identity.agents.config.filter.mode`

  Hot swap: no

HTTP Session Binding

  When enabled the agent invalidates the HTTP session upon login failure, when the user has no SSO session, or when the principal user name does not match the SSO user name.

  Property: `com.sun.identity.agents.config.httpsession.binding`

Login Attempt Limit

  When set to a value other than zero, this defines the maximum number of failed login attempts allowed during a single browser session, after which the agent blocks requests from the user.

  Property: `com.sun.identity.agents.config.login.attempt.limit`

Custom Response Header

  Specifies the custom headers the agent sets for the client. The key is the header name. The value is the header value.

  Property: `com.sun.identity.agents.config.response.header`

  For example, `com.sun.identity.agents.config.response.header[Cache-Control]=no-cache`.

Redirect Attempt Limit

  When set to a value other than zero, this defines the maximum number of redirects allowed for a single browser session, after which the agent blocks the request.

  Property: `com.sun.identity.agents.config.redirect.attempt.limit`

Agent Debug Level

  Default is `Error`. Increase to `Message` for fine-grained detail.

  Property: `com.iplanet.services.debug.level`

User Mapping properties

User Mapping Mode

  Specifies the mechanism used to determine the user ID.

  Property: `com.sun.identity.agents.config.user.mapping.mode`

User Attribute Name

  Specifies the data store attribute that contains the user ID.

  Property: `com.sun.identity.agents.config.user.attribute.name`

User Principal Flag

  When enabled, OpenAM uses both the principal user name and also the user ID for authentication.

  Property: `com.sun.identity.agents.config.user.principal`

User Token Name

  Specifies the session property name for the authenticated user's ID. Default: `UserToken`.

  Property: `com.sun.identity.agents.config.user.token`

Audit properties

Audit Access Types

  Types of messages to log based on user URL access attempts.

  Property: `com.sun.identity.agents.config.audit.accesstype`

  Valid values for the configuration file property include `LOG_NONE`, `LOG_ALLOW`, `LOG_DENY`, and `LOG_BOTH`.

Audit Log Location

  Specifies where audit messages are logged. By default, audit messages are logged remotely.

  Property: `com.sun.identity.agents.config.log.disposition`

  Valid values for the configuration file property include `REMOTE`, `LOCAL`, and `ALL`.

Remote Log Filename

  Name of file stored on OpenAM server that contains agent audit messages if log location is remote or all.

  Property: `com.sun.identity.agents.config.remote.logfile`

  Hot swap: no

Rotate Local Audit Log

  When enabled, audit log files are rotated when reaching the specified size.

  Property: `com.sun.identity.agents.config.local.log.rotate`

Local Audit Log Rotation Size

  Beyond this size limit in bytes the agent rotates the local audit log file if rotation is enabled.

  Property: `com.sun.identity.agents.config.local.log.size`

  Default: 50 MB

Fully Qualified Domain Name Checking properties

FQDN Check

  Enables checking of FQDN default value and FQDN map values.

  Property: `com.sun.identity.agents.config.fqdn.check.enable`

FQDN Default

  Fully qualified domain name that the users should use in order to access resources.

  This property ensures that when users access protected resources on the web server without specifying the FQDN, the agent can redirect the users to URLs containing the correct FQDN.

  Property: `com.sun.identity.agents.config.fqdn.default`

FQDN Virtual Host Map

  Enables virtual hosts, partial hostname and IP address to access protected resources. Maps invalid or virtual name keys to valid FQDN values so the agent can properly redirect users and the agents receive cookies belonging to the domain.

  To map `myserver` to `myserver.mydomain.example`, enter `myserver` in the Map Key field, and enter `myserver.mydomain.example` in the Corresponding Map Value field. This corresponds to `com.sun.identity.agents.config.fqdn.mapping[myserver]= myserver.mydomain.example`.

  Property: `com.sun.identity.agents.config.fqdn.mapping`

### 6.6.2. Configuring J2EE Policy Agent Application Properties

This section covers application web agent properties. After creating the agent profile, you access these properties in the OpenAM console under Access Control > `Realm Name` > Agents > J2EE > `Agent Name` > Application.

Login Processing properties

Login Form URI

  Specifies the list of absolute URIs corresponding to a protected application's `web.xml` `form-login-page` element, such as `/myApp/jsp/login.jsp`.

  Property: `com.sun.identity.agents.config.login.form`

Login Error URI

  Specifies the list of absolute URIs corresponding to a protected application's `web.xml` `form-error-page` element, such as `/myApp/jsp/error.jsp`.

  Property: `com.sun.identity.agents.config.login.error.uri`

Use Internal Login

  When enabled, the agent uses the internal default content file for the login.

  Property: `com.sun.identity.agents.config.login.use.internal`

Login Content File Name

  Full path name to the file containing custom login content when Use Internal Login is enabled.

  Property: `com.sun.identity.agents.config.login.content.file`

Logout Processing properties

Application Logout Handler

  Specifies how logout handlers map to specific applications. The key is the web application name. The value is the logout handler class.

  To set a global logout handler for applications without other logout handlers defined, leave the key empty and set the value to the global logout handler class name, `GlobalApplicationLogoutHandler`.

  To set a logout handler for a specific application, set the key to the name of the application, and the value to the logout handler class name.

  Property: `com.sun.identity.agents.config.logout.application.handler`

Application Logout URI

  Specifies request URIs that indicate logout events. The key is the web application name. The value is the application logout URI.

  To set a global logout URI for applications without other logout URIs defined, leave the key empty and set the value to the global logout URI, `/logout.jsp`.

  To set a logout URI for a specific application, set the key to the name of the application, and the value to the application logout page.

  Property: `com.sun.identity.agents.config.logout.uri`

Logout Request Parameter

  Specifies parameters in the HTTP request that indicate logout events. The key is the web application name. The value is the logout request parameter.

  To set a global logout request parameter for applications without other logout request parameters defined, leave the key empty and set the value to the global logout request parameter, `logoutparam`.

  To set a logout request parameter for a specific application, set the key to the name of the application, and the value to the application logout request parameter, such as `logoutparam`.

  Property: `com.sun.identity.agents.config.logout.request.param`

Logout Introspect Enabled

  When enabled, the agent checks the HTTP request body to locate the Logout Request Parameter you set.

  Property: `com.sun.identity.agents.config.logout.introspect.enabled`

Logout Entry URI

  Specifies the URIs to return after successful logout and subsequent authentication. The key is the web application name. The value is the URI to return.

  To set a global logout entry URI for applications without other logout entry URIs defined, leave the key empty and set the value to the global logout entry URI, `/welcome.html`.

  To set a logout entry URI for a specific application, set the key to the name of the application, and the value to the application logout entry URI, such as `/myApp/welcome.html`.

  Property: `com.sun.identity.agents.config.logout.entry.uri`

Access Denied URI Processing properties

Resource Access Denied URI

  Specifies the URIs of custom pages to return when access is denied. The key is the web application name. The value is the custom URI.

  To set a global custom access denied URI for applications without other custom access denied URIs defined, leave the key empty and set the value to the global custom access denied URI, `/sample/accessdenied.html`.

  To set a custom access denied URI for a specific application, set the key to the name of the application, and the value to the application access denied URI, such as `/myApp/accessdenied.html`.

  Property: `com.sun.identity.agents.config.access.denied.uri`

Not Enforced URI Processing properties

Not Enforced URIs

  List of URIs for which no authentication is required, and the agent does not protect access. You can use wildcards to define a pattern for a URI.

  The `*` wildcard matches all characters except question mark (`?`), cannot be escaped, and spans multiple levels in a URI. Multiple forward slashes do not match a single forward slash, so `*` matches `mult/iple/dirs`, yet `mult/*/dirs` does not match `mult/dirs`.

  The `-*-` wildcard matches all characters except forward slash (`/`) or question mark (`?`), and cannot be escaped. As it does not match `/`, `-*-` does not span multiple levels in a URI.

  OpenAM does not let you mix `*` and `-*-` in the same URI.

  Examples include `/logout.html`, `/images/*`, `/css/-*-`, and `/*.jsp?locale=*`.

  Trailing forward slashes are not recognized as part of a resource name. Therefore `/images//` and `/images` are equivalent.

  Property: `com.sun.identity.agents.config.notenforced.uri`

Invert Not Enforced URIs

  Only enforce not enforced list of URIs. In other words, enforce policy only for those URIs and patterns specified in the list.

  Property: `com.sun.identity.agents.config.notenforced.uri.invert`

Not Enforced URIs Cache Enabled

  When enabled, the agent caches evaluation of the not enforced URI list.

  Property: `com.sun.identity.agents.config.notenforced.uri.cache.enable`

Not Enforced URIs Cache Size

  When caching is enabled, this limits the number of not enforced URIs cached.

  Property: `com.sun.identity.agents.config.notenforced.uri.cache.size`

  Default: 1000

Refresh Session Idle Time

  When enabled, the agent reset the session idle time when granting access to a not enforced URI, prolonging the time before the user must authenticate again.

  Property: `com.sun.identity.agents.config.notenforced.refresh.session.idletime`

Not Enforced IP Processing properties

Not Enforced Client IP List

  No authentication and authorization are required for the requests coming from these client IP addresses.

  Property: `com.sun.identity.agents.config.notenforced.ip`

Not Enforced IP Invert List

  Only enforce the not enforced list of IP addresses. In other words, enforce policy only for those client addresses and patterns specified in the list.

  Property: `com.sun.identity.agents.config.notenforced.ip.invert`

Not Enforced IP Cache Flag

  When enabled, the agent caches evaluation of the not enforced IP list.

  Property: `com.sun.identity.agents.config.notenforced.ip.cache.enable`

Not Enforced IP Cache Size

  When caching is enabled, this limits the number of not enforced addresses cached.

  Property: `com.sun.identity.agents.config.notenforced.ip.cache.size`

  Default: 1000

Profile Attributes Processing properties

Profile Attribute Fetch Mode

  When set to `HTTP_COOKIE` or `HTTP_HEADER`, profile attributes are introduced into the cookie or the headers, respectively. When set to `REQUEST_ATTRIBUTE`, profile attributes are part of the HTTP request.

  Property: `com.sun.identity.agents.config.profile.attribute.fetch.mode`

Profile Attribute Map

  Maps the profile attributes to HTTP headers for the currently authenticated user. Map Keys are LDAP attribute names, and Map Values are HTTP header names.

  To populate the value of profile attribute CN under `CUSTOM-Common-Name`: enter CN in the Map Key field, and enter `CUSTOM-Common-Name` in the Corresponding Map Value field. This corresponds to `com.sun.identity.agents.config.profile.attribute.mapping[cn]=CUSTOM-Common-Name`.

  In most cases, in a destination application where an HTTP header name shows up as a request header, it is prefixed by `HTTP_`, lower case letters become upper case, and hyphens (`-`) become underscores (`_`). For example, `common-name` becomes `HTTP_COMMON_NAME`.

  Property: `com.sun.identity.agents.config.profile.attribute.mapping`

Response Attributes Processing properties

Response Attribute Fetch Mode

  When set to `HTTP_COOKIE` or `HTTP_HEADER`, response attributes are introduced into the cookie or the headers, respectively. When set to `REQUEST_ATTRIBUTE`, response attributes are part of the HTTP response.

  Property: `com.sun.identity.agents.config.response.attribute.fetch.mode`

Response Attribute Map

  Maps the policy response attributes to HTTP headers for the currently authenticated user. The response attribute is the attribute in the policy response to be fetched.

  To populate the value of response attribute `uid` under `CUSTOM-User-Name`: enter `uid` in the Map Key field, and enter `CUSTOM-User-Name` in the Corresponding Map Value field. This corresponds to `com.sun.identity.agents.config.response.attribute.mapping[uid]=Custom-User-Name`.

  In most cases, in a destination application where an HTTP header name shows up as a request header, it is prefixed by `HTTP_`, lower case letters become upper case, and hyphens (`-`) become underscores (`_`). For example, `response-attr-one` becomes `HTTP_RESPONSE_ATTR_ONE`.

  Property: `com.sun.identity.agents.config.response.attribute.mapping`

Common Attributes Fetching Processing properties

Cookie Separator Character

  Specifies the separator for multiple values of the same attribute when it is set as a cookie. Default: `|` (also known as the vertical bar character).

  Property: `com.sun.identity.agents.config.attribute.cookie.separator`

Fetch Attribute Date Format

  Specifies the `java.text.SimpleDateFormat` of date attribute values used when an attribute is set in an HTTP header. Default: `EEE, d MMM yyyy hh:mm:ss z`.

  Property: `com.sun.identity.agents.config.attribute.date.format`

Attribute Cookie Encode

  When enabled, attribute values are URL encoded before being set as a cookie.

  Property: `com.sun.identity.agents.config.attribute.cookie.encode`

Session Attributes Processing properties

Session Attribute Fetch Mode

  When set to `HTTP_COOKIE` or `HTTP_HEADER`, session attributes are introduced into the cookie or the headers, respectively. When set to `REQUEST_ATTRIBUTE`, session attributes are part of the HTTP response.

  Property: `com.sun.identity.agents.config.session.attribute.fetch.mode`

Session Attribute Map

  Maps session attributes to HTTP headers for the currently authenticated user. The session attribute is the attribute in the session to be fetched.

  To populate the value of session attribute `UserToken` under `CUSTOM-userid`: enter `UserToken` in the Map Key field, and enter `CUSTOM-userid` in the Corresponding Map Value field. This corresponds to `com.sun.identity.agents.config.session.attribute.mapping[UserToken]=CUSTOM-userid`.

  In most cases, in a destination application where an HTTP header name shows up as a request header, it is prefixed by `HTTP_`, lower case letters become upper case, and hyphens (`-`) become underscores (`_`). For example, `success-url` becomes `HTTP_SUCCESS_URL`.

  Property: `com.sun.identity.agents.config.session.attribute.mapping`

Privilege Attributes Processing properties

Default Privileged Attribute

  Specifies the list of privileged attributes granted to all users with a valid OpenAM session, such as `AUTHENTICATED_USERS`.

  Property: `com.sun.identity.agents.config.default.privileged.attribute`

Privileged Attribute Type

  Specifies the list of privileged attribute types fetched for each user.

  Property: `com.sun.identity.agents.config.privileged.attribute.type`

Privileged Attributes To Lower Case

  Specifies how privileged attribute types should be converted to lower case.

  Property: `com.sun.identity.agents.config.privileged.attribute.tolowercase`

Privileged Session Attribute

  Specifies the list of session property names, such as `UserToken` which hold privileged attributes for authenticated users.

  Property: `com.sun.identity.agents.config.privileged.session.attribute`

Enable Privileged Attribute Mapping

  When enabled, lets you use Privileged Attribute Mapping.

  Property: `com.sun.identity.agents.config.privileged.attribute.mapping.enable`

Privileged Attribute Mapping

  OpenAM allows original attribute values to be mapped to other values. For example, you can map UUIDs to principal names in roles specified in a web application's deployment descriptor. For example, to map the UUID `id=employee,ou=group,o=openam` to the principal name `am_employee_role` in the deployment descriptor, set the key to `id=employee,ou=group,o=openam`, and the value to `am_employee_role`.

  Property: `com.sun.identity.agents.config.privileged.attribute.mapping`

Custom Authentication Processing properties

Custom Authentication Handler

  Specifies custom authentication handler classes for users authenticated with the application server. The key is the web application name and the value is the authentication handler class name.

  Property: `com.sun.identity.agents.config.auth.handler`

Custom Logout Handler

  Specifies custom logout handler classes to log users out of the application server. The key is the web application name and the value is the logout handler class name.

  Property: `com.sun.identity.agents.config.logout.handler`

Custom Verification Handler

  Specifies custom verification classes to validate user credentials with the local user repository. The key is the web application name and the value is the validation handler class name.

  Property: `com.sun.identity.agents.config.verification.handler`

### 6.6.3. Configuring J2EE Policy Agent SSO Properties

This section covers SSO web agent properties. After creating the agent profile, you access these properties in the OpenAM console under Access Control > `Realm Name` > Agents > J2EE > `Agent Name` > SSO

Cookie properties

Cookie Name

  Name of the SSO Token cookie used between the OpenAM server and the agent. Default: `iPlanetDirectoryPro`.

  Property: `com.iplanet.am.cookie.name`

  Hot swap: no

Caching properties

SSO Cache Enable

  When enabled, the agent exposes SSO Cache through the agent SDK APIs.

  Property: `com.sun.identity.agents.config.amsso.cache.enable`

Cross Domain SSO properties

Cross Domain SSO

  Enables Cross Domain Single Sign On.

  Property: `com.sun.identity.agents.config.cdsso.enable`

CDSSO Redirect URI

  Specifies a URI the agent uses to process CDSSO requests.

  Property: `com.sun.identity.agents.config.cdsso.redirect.uri`

CDSSO Servlet URL

  List of URLs of the available CDSSO controllers that the agent can use for CDSSO processing. For example, `http://openam.example.com:8080/openam/cdcservlet`.

  Property: `com.sun.identity.agents.config.cdsso.cdcservlet.url`

CDSSO Clock Skew

  When set to a value other than zero, specifies the clock skew in seconds that the agent accepts when determining the validity of the CDSSO authentication response assertion.

  Property: `com.sun.identity.agents.config.cdsso.clock.skew`

CDSSO Trusted ID Provider

  Specifies the list of OpenAM servers or identity providers the agent trusts when evaluating CDC Liberty Responses.

  Property: `com.sun.identity.agents.config.cdsso.trusted.id.provider`

CDSSO Secure Enable

  When enabled, the agent marks the SSO Token cookie as secure, thus the cookie is only transmitted over secure connections.

  Property: `com.sun.identity.agents.config.cdsso.secure.enable`

CDSSO Domain List

  List of domains, such as `.example.com`, in which cookies have to be set in CDSSO.

  Property: `com.sun.identity.agents.config.cdsso.domain`

Cookie Reset properties

Cookie Reset

  When enabled, agent resets cookies in the response before redirecting to authentication.

  Property: `com.sun.identity.agents.config.cookie.reset.enable`

Cookie Reset Name List

  List of cookies to reset if Cookie Reset is enabled.

  Property: `com.sun.identity.agents.config.cookie.reset.name`

Cookie Reset Domain Map

  Specifies how names from the Cookie Reset Name List correspond to cookie domain values when the cookie is reset.

  Property: `com.sun.identity.agents.config.cookie.reset.domain`

Cookie Reset Path Map

  Specifies how names from the Cookie Reset Name List correspond to cookie paths when the cookie is reset.

  Property: `com.sun.identity.agents.config.cookie.reset.path`

### 6.6.4. Configuring J2EE Policy Agent OpenAM Services Properties

This section covers OpenAM services web agent properties. After creating the agent profile, you access these properties in the OpenAM console under Access Control > `Realm Name` > Agents > J2EE > `Agent Name` > OpenAM Services.

Login URL properties

OpenAM Login URL

  OpenAM login page URL, such as `http://openam.example.com:8080/openam/UI/Login`, to which the agent redirects incoming users without sufficient credentials so then can authenticate.

  Property: `com.sun.identity.agents.config.login.url`

OpenAM Conditional Login URL (Not yet in OpenAM console)

  To conditionally redirect users based on the incoming request URL, set this property.

  This takes the incoming request domain to match, a vertical bar ( `|` ), and then a comma-separated list of URLs to which to redirect incoming users.

  If the domain before the vertical bar matches an incoming request URL, then the policy agent uses the list of URLs to determine how to redirect the user-agent. If the global property FQDN Check (`com.sun.identity.agents.config.fqdn.check.enable`) is enabled for the policy agent, then the policy agent iterates through the list until it finds an appropriate redirect URL that matches the FQDN check. Otherwise, the policy agent redirects the user-agent to the first URL in the list.

  Property: `com.sun.identity.agents.config.conditional.login.url`

  Examples: `com.sun.identity.agents.config.conditional.login.url[0]= login.example.com|http://openam1.example.com/openam/UI/Login, http://openam2.example.com/openam/UI/Login`, `com.sun.identity.agents.config.conditional.login.url[1]= signin.example.com|http://openam3.example.com/openam/UI/Login, http://openam4.example.com/openam/UI/Login`

  If CDSSO is enabled for the policy agent, then this property takes CDSSO Servlet URLs for its values (`com.sun.identity.agents.config.cdsso.cdcservlet.url`), rather than OpenAM login URLs.

  CDSSO examples: `com.sun.identity.agents.config.conditional.login.url[0]= login.example.com|http://openam1.example.com/openam/cdcservlet, http://openam2.example.com/openam/cdcservlet`, `com.sun.identity.agents.config.conditional.login.url[1]= signin.example.com|http://openam3.example.com/openam/cdcservlet, http://openam4.example.com/openam/cdcservlet`

Login URL Prioritized

  When enabled, OpenAM uses the priority defined in the OpenAM Login URL list as the priority for Login and CDSSO URLs when handling failover.

  Property: `com.sun.identity.agents.config.login.url.prioritized`

Login URL Probe

  When enabled, OpenAM checks the availability of OpenAM Login URLs before redirecting to them.

  Property: `com.sun.identity.agents.config.login.url.probe.enabled`

Login URL Probe Timeout

  Timeout period in milliseconds for OpenAM to determine whether to failover between Login URLs when Login URL Probe is enabled.

  Property: `com.sun.identity.agents.config.login.url.probe.timeout`

  Default: 2000

Logout URL properties

OpenAM Logout URL

  OpenAM logout page URLs, such as `http://openam.example.com:8080/openam/UI/Logout`. The user is logged out of the OpenAM session when accessing these URLs.

  Property: `com.sun.identity.agents.config.logout.url`

OpenAM Conditional Logout URL (Not yet in OpenAM console)

  The values take the incoming request URL to match and a comma-separated list of URLs to which to redirect users logging out.

  Property: `com.sun.identity.agents.config.conditional.logout.url`

  Example: `com.sun.identity.agents.config.conditional.logout.url[0]= logout.example.com|http://openam1.example.com/openam/UI/Logout, http://openam2.example.com/openam/UI/Logout`

Logout URL Prioritized

  When enabled, OpenAM uses the priority defined in the OpenAM Logout URL list as the priority for Logout URLs when handling failover.

  Property: `com.sun.identity.agents.config.logout.url.prioritized`

Logout URL Probe

  When enabled, OpenAM checks the availability of OpenAM Logout URLs before redirecting to them.

  Property: `com.sun.identity.agents.config.logout.url.probe.enabled`

Logout URL Probe Timeout

  Timeout period in milliseconds for OpenAM to determine whether to failover between Logout URLs when Logout URL Probe is enabled.

  Property: `com.sun.identity.agents.config.logout.url.probe.timeout`

  Default: 2000

Authentication Service properties

OpenAM Authentication Service Protocol

  Specifies the protocol used by the OpenAM authentication service.

  Property: `com.iplanet.am.server.protocol`

  Hot swap: no

OpenAM Authentication Service Host Name

  Specifies the OpenAM authentication service host name.

  Property: `com.iplanet.am.server.host`

  Hot swap: no

OpenAM Authentication Service Port

  Specifies the OpenAM authentication service port number.

  Property: `com.iplanet.am.server.port`

  Hot swap: no

Policy Client Service properties

Enable Policy Notifications

  When enabled, OpenAM sends notification about changes to policy.

  Property: `com.sun.identity.agents.notification.enabled`

  Hot swap: no

Policy Client Polling Interval

  Specifies the time in minutes after which the policy cache is refreshed.

  Property: `com.sun.identity.agents.polling.interval`

  Default: 3

  Hot swap: no

Policy Client Cache Mode

  Set to cache mode subtree when only a small number of policy rules are defined. For large numbers of policy rules, set to self.

  Property: `com.sun.identity.policy.client.cacheMode`

  Default: self

  Hot swap: no

Policy Client Boolean Action Values

  Specifies the values, such as `allow` and `deny`, that are associated with boolean policy decisions.

  Default: `iPlanetAMWebAgentService|GET|allow|deny:iPlanetAMWebAgentService|POST|allow|deny`

  Property: `com.sun.identity.policy.client.booleanActionValues`

  Hot swap: no

Policy Client Resource Comparators

  Specifies the comparators used for service names in policy.

  Default: `serviceType=iPlanetAMWebAgentService| class=com.sun.identity.policy.plugins.HttpURLResourceName|wildcard=*| delimiter=/|caseSensitive=false`

  Property: `com.sun.identity.policy.client.resourceComparators`

  Hot swap: no

Policy Client Clock Skew

  Time in seconds used adjust time difference between agent system and OpenAM. Clock skew in seconds = AgentTime - OpenAMServerTime.

  Default: 10.

  Property: `com.sun.identity.policy.client.clockSkew`

  Hot swap: no

URL Policy Env GET Parameters

  Specifies the list of HTTP GET request parameters whose names and values the agents sets in the environment map for URL policy evaluation by the OpenAM server.

  Property: `com.sun.identity.agents.config.policy.env.get.param`

URL Policy Env POST Parameters

  Specifies the list of HTTP POST request parameters whose names and values the agents sets in the environment map for URL policy evaluation by the OpenAM server.

  Property: `com.sun.identity.agents.config.policy.env.post.param`

URL Policy Env jsession Parameters

  Specifies the list of HTTP session attributes whose names and values the agents sets in the environment map for URL policy evaluation by the OpenAM server.

  Property: `com.sun.identity.agents.config.policy.env.jsession.param`

Use HTTP-Redirect for composite advice

  When enabled, the remote policy client is configured to use HTTP-Redirect instead of HTTP-POST for composite advice.

  Property: `com.sun.identity.agents.config.policy.advice.use.redirect`

User Data Cache Service properties

Enable Notification of User Data Caches

  When enabled, receive notification from OpenAM to update user management data caches.

  Property: `com.sun.identity.idm.remote.notification.enabled`

  Hot swap: no

User Data Cache Polling Time

  If notifications are not enabled and set to a value other than zero, specifies the time in minutes after which the agent polls to update cached user management data.

  Property: `com.iplanet.am.sdk.remote.pollingTime`

  Default: 1

  Hot swap: no

Enable Notification of Service Data Caches

  When enabled, receive notification from OpenAM to update service configuration data caches.

  Property: `com.sun.identity.sm.notification.enabled`

  Hot swap: no

Service Data Cache Time

  If notifications are not enabled and set to a value other than zero, specifies the time in minutes after which the agent polls to update cached service configuration data.

  Property: `com.sun.identity.sm.cacheTime`

  Default: 1

  Hot swap: no

Session Client Service properties

Enable Client Polling

  When enabled, the session client polls to update the session cache rather than relying on notifications from OpenAM.

  Property: `com.iplanet.am.session.client.polling.enable`

  Hot swap: no

Client Polling Period

  Specifies the time in seconds after which the session client requests an update from OpenAM for cached session information.

  Property: `com.iplanet.am.session.client.polling.period`

  Default: 180

  Hot swap: no

### 6.6.5. Configuring J2EE Policy Agent Miscellaneous Properties

This section covers miscellaneous web agent properties. After creating the agent profile, you access these properties in the OpenAM console under Access Control > `Realm Name` > Agents > J2EE > `Agent Name` > Miscellaneous.

Locale properties

Locale Language

  The default language for the agent.

  Property: `com.sun.identity.agents.config.locale.language`

  Hot swap: no

Locale Country

  The default country for the agent.

  Property: `com.sun.identity.agents.config.locale.country`

  Hot swap: no

Port Check Processing properties

Port Check Enable

  When enabled, activate port checking, correcting requests on the wrong port.

  Property: `com.sun.identity.agents.config.port.check.enable`

Port Check File

  Specifies the name of the file containing the content to handle requests on the wrong port when port checking is enabled.

  Property: `com.sun.identity.agents.config.port.check.file`

Port Check Setting

  Specifies which ports correspond to which protocols. The agent uses the map when handling requests with invalid port numbers during port checking.

  Property: `com.sun.identity.agents.config.port.check.setting`

Bypass Principal List properties

Bypass Principal List

  Specifies a list of principals the agent bypasses for authentication and search purposes, such as `guest` or `testuser`.

  Property: `com.sun.identity.agents.config.bypass.principal`

Agent Password Encryptor properties

Encryption Provider

  Specifies the agent's encryption provider class.

  Default: `com.iplanet.services.util.JCEEncryption`

  Property: `com.iplanet.security.encryptor`

  Hot swap: no

Ignore Path Info properties

Ignore Path Info in Request URL

  When enabled, strip path info from the request URL while doing the Not Enforced List check, and URL policy evaluation. This is designed to prevent a user from accessing a URI by appending the matching pattern in the policy or not enforced list.

  For example, if the not enforced list includes `/*.gif`, then stripping path info from the request URL prevents access to `http://host/index.html` by using `http://host/index.html?hack.gif`.

  Property: `com.sun.identity.agents.config.ignore.path.info`

Deprecated Client Browser User Agent Properties

Goto Parameter Name

  Property used only when CDSSO is enabled. Only change the default value, `goto` when the login URL has a landing page specified such as, `com.sun.identity.agents.config.cdsso.cdcservlet.url = http://openam.example.com:8080/openam/cdcservlet?goto= http://www.example.com/landing.jsp`. The agent uses this parameter to append the original request URL to this cdcserlet URL. The landing page consumes this parameter to redirect to the original URL.

  As an example, if you set this value to `goto2`, then the complete URL sent for authentication is `http://openam.example.com:8080/openam/cdcservlet?goto= http://www.example.com/landing.jsp?goto2=http://www.example.com/original.jsp`.

  Property: `com.sun.identity.agents.config.redirect.param`

Legacy User Agent Support Enable

  When enabled, provide support for legacy browsers.

  Property: `com.sun.identity.agents.config.legacy.support.enable`

Legacy User Agent List

  List of header values that identify legacy browsers. Entries can use the wildcard character, `*`.

  Property: `com.sun.identity.agents.config.legacy.user.agent`

Legacy User Agent Redirect URI

  Specifies a URI the agent uses to redirect legacy user agent requests.

  Property: `com.sun.identity.agents.config.legacy.redirect.uri`

### 6.6.6. Configuring J2EE Policy Agent Advanced Properties

This section covers advanced web agent properties. After creating the agent profile, you access these properties in the OpenAM console under Access Control > `Realm Name` > Agents > J2EE > `Agent Name` > Advanced.

Client Identification properties

If the agent is behind a proxy or load balancer, then the agent can get client IP and host name values from the proxy or load balancer. For proxies and load balancer that support providing the client IP and host name in HTTP headers, you can use the following properties.

When multiple proxies are load balancers sit in the request path, the header values can include a comma-separated list of values with the first value representing the client, as in `client,next-proxy,first-proxy`.

Client IP Address Header

  HTTP header name that holds the IP address of the client.

  Property: `com.sun.identity.agents.config.client.ip.header`

Client Hostname Header

  HTTP header name that holds the hostname of the client.

  Property: `com.sun.identity.agents.config.client.hostname.header`

Web Service Processing properties

Web Service Enable

  Enable web service processing.

  Property: `com.sun.identity.agents.config.webservice.enable`

Web Service End Points

  Specifies a list of web application end points that represent web services.

  Property: `com.sun.identity.agents.config.webservice.endpoint`

Web Service Process GET Enable

  When enabled, the agent processes HTTP GET requests for web service endpoints.

  Property: `com.sun.identity.agents.config.webservice.process.get.enable`

Web Service Authenticator

  Specifies a class implementing `com.sun.identity.agents.filter.IWebServiceAuthenticator`, used to authenticate web service requests.

  Property: `com.sun.identity.agents.config.webservice.responseprocessor`

Web Service Response Processor

  Specifies a class implementing `com.sun.identity.agents.filter.IWebServiceResponseProcessor`, used to process web service reponses.

  Property: `com.sun.identity.agents.config.webservice.responseprocessor`

Web Service Internal Error Content File

  Specifies a file the agent uses to generate an internal error fault for the client application.

  Property: `com.sun.identity.agents.config.webservice.internalerror.content`

Web Service Authorization Error Content File

  Specifies a file the agent uses to generate an authorization error fault for the client application.

  Property: `com.sun.identity.agents.config.webservice.autherror.content`

Alternate Agent URL properties

Alternative Agent Host Name

  Specifies the host name of the agent protected server to show to client browsers, rather than the actual host name.

  Property: `com.sun.identity.agents.config.agent.host`

Alternative Agent Port Name

  Specifies the port number of the agent protected server to show to client browsers, rather than the actual port number.

  Property: `com.sun.identity.agents.config.agent.port`

Alternative Agent Protocol

  Specifies the protocol used to contact the agent from the browser client browsers, rather than the actual protocol used by the server. Either `http` or `https`.

  Property: `com.sun.identity.agents.config.agent.protocol`

JBoss Application Server properties

WebAuthentication Available

  When enabled, allow programmatic authentication with the JBoss container using the WebAuthentication feature. This feature works only with JBoss 4.2.2 to 7 when the `J2EE_POLICY` or `ALL` filter mode is in use.

  Property: `com.sun.identity.agents.config.jboss.webauth.available`

Cross Site Scripting Detection properties

Possible XSS code elements

  Specifies strings that, when found in the request, cause the agent to redirect the client to an error page.

  Property: `com.sun.identity.agents.config.xss.code.elements`

XSS detection redirect URI

  Maps applications to URIs of customized pages to which to redirect clients upon detection of XSS code elements.

  For example, to redirect clients of MyApp to `/myapp/error.html`, enter MyApp as the Map Key and `/myapp/error.html` as the Corresponding Map Value.

  Property: `com.sun.identity.agents.config.xss.redirect.uri`

Post Data Preservation properties

POST Data Preservation

  Enables HTTP POST data preservation, storing POST data before redirecting the browser to the login screen, and then autosubmitting the same POST after successful authentication to the original URL.

  Property: `com.sun.identity.agents.config.postdata.preserve.enable`

Missing PDP entry URI

  Specifies a list of application-specific URIs if the referenced Post Data Preservation entry cannot be found in the local cache because it has exceeded its POST entry TTL. Either the agent redirects to a URI in this list, or it shows an HTTP 403 Forbidden error.

  Property: `com.sun.identity.agents.config.postdata.preserve.cache.noentry.url`

POST entry TTL

  POST data storage lifetime in milliseconds. Default: 300000.

  Property: `com.sun.identity.agents.config.postdata.preserve.cache.entry.ttl`

PDP Stickysession mode

  Specifies whether to create a cookie, or to append a query string to the URL to assist with sticky load balancing.

  Property: `com.sun.identity.agents.config.postdata.preserve.stickysession.mode`

PDP Stickysession key-value

  Specifies the key-value pair for stickysession mode. For example, a setting of `lb=myserver` either sets an `lb` cookie with `myserver` value, or adds `lb=myserver` to the URL query string.

  Property: `com.sun.identity.agents.config.postdata.preserve.stickysession.value`

Custom properties

Custom Properties

  Additional properties to augment the set of properties supported by agent. Such properties take the following forms.

  - `customproperty=custom-value1`

  - `customlist[0]=customlist-value-0`

  - `customlist[1]=customlist-value-1`

  - `custommap[key1]=custommap-value-1`

  - `custommap[key2]=custommap-value-2`

  Property: `com.sun.identity.agents.config.freeformproperties`

## 6.7. Configuring Web Service Provider Policy Agents

This section covers Web Service Provider (WSP) properties. WSPs both validate incoming web service requests from Web Service Clients (WSC), and also secure outgoing responses sent back to WSCs.

After creating a WSP profile, you access WSP properties in the OpenAM console under Access Control > `Realm Name` > Agents > Web Service Provider > `Agent Name`.

General properties

Group

  For assigning the agent to a previously configured agent group in order to inherit selected properties from the group.

Password

  Agent password used when creating the password file and when installing the agent.

Status

  Status of the agent configuration.

Universal Identifier

  OpenAM identifier for the agent configuration.

Security properties

Security Mechanism

  Specifies the mechanisms allowed to validate the web service request.

Authentication Chain

  Specifies which OpenAM authentication chain consumes the credentials from the web service request to authenticate the WSC.

Token Conversion Type

  Specifies how to covert the incoming token before issuing requests to other WSPs.

Preserve Security Headers in Message

  Yes means the agent preserves SOAP security headers from the request for subsequent processing.

Detect Message Replay

  Yes means the agent checks whether the request is a replay of an earlier request, and if so, rejects the request.

Detect User Token Replay

  Yes means the agent checks whether the user token is a replay from an earlier requests, and if so, rejects the request.

Private Key Type

  Specifies the type of key, such as `PublicKey`, used to verify the request signature.

Liberty Service Type URN

  Specifies the Universal Resource Name for the Liberty service type used for lookups.

DNS Claim

  Specifies a Uniform Resource Identitier shared by the WSP and WSC.

Credential for User Token

  Specifies the user name and password credentials compared with the user name security token in a request.

SAML Configuration properties

SAML Attribute Mapping

  Maps SAML attribute names from the incoming request to attribute names as retrieved from the SSOToken or the identity repository, used to have the Security Token Service generate an appropriate SAML assertion.

SAML NameID Mapper Plugin

  Specifies the class name of a plugin used to perform SAML account mapping.

SAML Attributes Namespace

  Identifies the attribute name space used when generating SAML assertions.

Include Memberships

  Yes means the agent includes the principal's membership as a SAML attribute.

Signing and Encryption properties

Is Request Signature Verified

  Yes means verify signatures in requests.

Is Response Signed Enabled

  Yes means the agent signs the specified parts of the response with its x509 certificate.

Signing Reference Type

  Specifies how the x509 certificate used to sign responses is referenced in the response.

Is Request Decrypted

  Yes means do decrypt the specified parts of incoming requests.

Is Response Encrypted

  Yes means do encrypt the outgoing response.

Encryption Algorithm

  Specifies whether to use Advanced Encryption Standard, corresponding to an Encryption Strength of 128, 192, or 256, or to use Triple DES with a key length of 0, 112, or 168.

Encryption Strength

  Specifies the key length used for encryption.

Key Store properties

Public Key Alias of Web Service Client

  Specifies the alias of the certificate in the key store used to verify request signatures and encrypt responses.

Private Key Alias

  Specifies the alias of the certificate in the key store used to sign responses and decrypt requests.

Key Store Usage

  If you use your own, custom key store, specify how to access it here.

End Points properties

Web Service Security Proxy End Point

  If the WSC sends requests through a web service proxy, specify that as the end point here.

Web Service End Point

  Specifies the end point to which the WSC sends requests.

Kerberos Configuration properties

Kerberos Domain Server

  Specifies the fully qualified domain name of the Kerberos Distribution Center service.

Kerberos Domain

  Specifies the Kerberos Distribution Center domain name. For Windows environments this is the domain controller domain name.

Kerberos Service Principal

  Specifies the Kerberos principal used by OpenAM, using the form `HTTP/`openam-fqdn`@`krb-domain``, where `openam-fqdn` is the fully qualified domain name for OpenAM, and `krb-domain` is the Kerberos Domain.

Kerberos Key Tab File

  Specifies the Kerberos keytab file using the form ``openam-host`.HTTP.keytab`, where `openam-host` is the host name for OpenAM.

Verify Kerberos Signature

  Yes means the agent signs the Kerberos token.

## 6.8. Configuring Web Service Client Policy Agents

This section covers Web Service Client (WSC) properties. WSCs both secure outgoing requests sent to Web Service Providers (WSP), and also validate incoming from WSPs.

After creating a WSC profile, you access WSC properties in the OpenAM console under Access Control > `Realm Name` > Agents > Web Service Client > `Agent Name`.

General properties

Group

  For assigning the agent to a previously configured agent group in order to inherit selected properties from the group.

Password

  Agent password used when creating the password file and when installing the agent.

Status

  Status of the agent configuration.

Universal Identifier

  OpenAM identifier for the agent configuration.

Security properties

Security Mechanism

  Specifies the mechanism used to secure web service requests.

STS Configuration

  Specifies the agent used to secure requests to the Security Token Service. Associated with the STSSecurity Security Mechanism.

Discovery Configuration

  Specifies the agent used to secure requests to the Discovery Service. Associated with the LibertyDiscoverySecurity Security Mechanism.

User Authentication Required

  Yes means users must authenticate to access the WSC's protected page.

Preserve Security Headers in Message

  Yes means the agent preserves SOAP security headers in the request for subsequent processing.

User Pass Through Security Token

  Yes means the agent passes along the Security Token from the Subject, rather than generating a token or requesting it from the Security Token Service.

Liberty Service Type URN

  Specifies the Universal Resource Name for the Liberty service type used for lookups.

Credential for User Token

  Specifies the user name and password credentials shared with the WSP and used to generate a Username Security Token.

DNS Claim

  Specifies a Uniform Resource Identitier shared by the WSP and WSC.

SAML Configuration properties

SAML Attribute Mapping

  Maps SAML attribute names from the outgoing request to attribute names as retrieved from the SSOToken or the identity repository.

SAML NameID Mapper Plugin

  Specifies the class name of a plugin used to perform SAML account mapping.

SAML Attributes Namespace

  Identifies the attribute name space used when generating SAML assertions.

Include Memberships

  Yes means the agent includes the principal's membership as a SAML attribute.

Signing and Encryption properties

Is Request Signed Enabled

  Yes means the agent signs the specified parts of the request with its x509 certificate.

Signing Reference Type

  Specifies how the x509 certificate used to sign requests is referenced in the request.

Is Response Signature Verified

  Yes means verify signatures in responses.

Is Request Encryption Enabled

  Yes means do encrypt the specified parts of outgoing requests.

Encryption Algorithm

  Specifies whether to use Advanced Encryption Standard, corresponding to an Encryption Strength of 128, 192, or 256, or to use Triple DES with a key length of 0, 112, or 168.

Encryption Strength

  Specifies the key length used for encryption.

Is Response Decrypted

  Yes means do decrypt the incoming response.

Key Store properties

Public Key Alias of Web Service Provider

  Specifies the alias of the certificate in the key store used to sign requests and decrypt responses.

Private Key Alias

  Specifies the alias of the certificate in the key store used to verify response signatures and encrypt requests.

Key Store Usage

  If you use your own, custom key store, specify how to access it here.

End Points properties

Web Service Security Proxy End Point

  If the WSC sends requests through a web service proxy, specify that as the end point here.

Web Service End Point

  Specifies the end point to which the WSC sends requests.

Kerberos Configuration properties

Kerberos Domain Server

  Specifies the fully qualified domain name of the Kerberos Distribution Center service.

Kerberos Domain

  Specifies the Kerberos Distribution Center domain name. For Windows environments this is the domain controller domain name.

Kerberos Service Principal

  Specifies the Kerberos principal used by OpenAM, using the form `HTTP/`openam-fqdn`@`krb-domain``, where `openam-fqdn` is the fully qualified domain name for OpenAM, and `krb-domain` is the Kerberos Domain.

Kerberos Ticket Cache Directory

  Specifies the directory in which Kerberos Ticket Granting Tickets (TGT) are cached. The kinit command stores the TGT from the KDC here.

## 6.9. Configuring Security Token Service Client Policy Agents

This section covers Security Token Service (STS) Client properties. STS clients both secure outgoing requests to trust authorities, and also validate incoming requests from trust authorities. You can configure STS clients to work with OpenAM's Security Token Service and with its Discovery Service.

After creating an STS Client profile, you access STS Client properties in the OpenAM console under Access Control > `Realm Name` > Agents > STS Client > `Agent Name`.

General properties

Group

  For assigning the agent to a previously configured agent group in order to inherit selected properties from the group.

Password

  Agent password used when creating the password file and when installing the agent.

Status

  Status of the agent configuration.

WS-Trust Version

  Specifies whether to use WS-Trust 1.3 or 1.0.

Universal Identifier

  OpenAM identifier for the agent configuration.

Security properties

Security Mechanism

  Specifies the mechanism used to secure the STS request.

STS Configuration

  Specifies the STS Client agent profile to use if the security mechanism is STS Security.

Preserve Security Headers in Message

  Yes means the agent preserves SOAP security headers for subsequent processing.

Credential for User Token

  Specifies the user name and password credentials the agent uses to generate a Username security token.

Requested Key Type

  Specifies the type of key, such as `PublicKey`, used to encrypt responses.

Requested Claims

  Specifies the Uniform Resource Identitiers for the claims to be represented in the Security Token.

DNS Claim

  Specifies a Uniform Resource Identitier shared by the agent and the WSC.

SAML Configuration properties

SAML Attribute Mapping

  Maps SAML attribute names from the incoming request to attribute names as retrieved from the SSOToken or the identity repository, used to have the Security Token Service generate an appropriate SAML assertion.

SAML NameID Mapper Plugin

  Specifies the class name of a plugin used to perform SAML account mapping.

SAML Attributes Namespace

  Identifies the attribute name space used when generating SAML assertions.

Include Memberships

  Yes means the agent includes the principal's membership as a SAML attribute.

Signing and Encryption properties

Is Response Signature Verified

  Yes means verify signatures in responses.

Is Request Signed Enabled

  Yes means the agent signs the specified parts of the request with its x509 certificate.

Signing Reference Type

  Specifies how the x509 certificate used to sign requests is referenced in the request.

Is Request Encryption Enabled

  Yes means do encrypt the specified parts of requests.

Is Response Decrypted

  Yes means do decrypt the response.

Encryption Algorithm

  Specifies whether to use Advanced Encryption Standard, corresponding to an Encryption Strength of 128, 192, or 256, or to use Triple DES with a key length of 0, 112, or 168.

Encryption Strength

  Specifies the key length used for encryption.

Key Store properties

Public Key Alias of Web Service Provider

  Specifies the alias of the certificate in the key store used to verify response signatures and encrypt requests.

Private Key Alias

  Specifies the alias of the certificate in the key store used to sign requests and decrypt responses.

Key Store Usage

  If you use your own, custom key store, specify how to access it here.

End Points properties

Security Token Service End Point

  Specifies the URL to the Security Token Service end point.

Security Token Service MEX End Point

  Specifies the URL to the Security Token Service message exchange end point.

Kerberos Configuration properties

Kerberos Domain Server

  Specifies the fully qualified domain name of the Kerberos Distribution Center service.

Kerberos Domain

  Specifies the Kerberos Distribution Center domain name. For Windows environments this is the domain controller domain name.

Kerberos Service Principal

  Specifies the Kerberos principal used by OpenAM, using the form `HTTP/`openam-fqdn`@`krb-domain``, where `openam-fqdn` is the fully qualified domain name for OpenAM, and `krb-domain` is the Kerberos Domain.

Kerberos Ticket Cache Directory

  Specifies the directory in which Kerberos Ticket Granting Tickets (TGT) are cached. The kinit command stores the TGT from the KDC here.

## 6.10. Configuring Version 2.2 Policy Agents

This section covers version 2.2 agent properties. Version 2.2 agents store their configurations locally, with a user name, password combination used to connect to OpenAM.

After creating the agent profile, you access agent properties in the OpenAM console under Access Control > `Realm Name` > Agents > 2.2 Agents > `Agent Name`.

Password

  Specifies the password the agent uses to connect to OpenAM.

Status

  Specifies whether the agent profile is active, and so can be used.

Description

  Specifies a short description for the agent.

Agent Key Value(s)

  Additional key-value pairs that OpenAM uses to receive agent requests concerning credential assertions.

  OpenAM currently supports one property, `agentRootURL=`protocol`://`host`:`port`/` where the key is case-sensitive.

## 6.11. Configuring OAuth 2.0 & OpenID Connect 1.0 Clients

When you want to register an OAuth 2.0 client with OpenAM as the OAuth 2.0 authorization server, or register an OpenID Connect 1.0 client through OpenAM console, then create an OAuth 2.0 Client agent profile. After creating the agent profile, you can further configure the properties in the OpenAM console under Access Control > `Realm Name` > Agents > OAuth 2.0 Client > `Client Name`.

The topmost configuration fields are for both OAuth 2.0 and OpenID Connect 1.0, whereas others are specifically for OpenID Connect 1.0.

- Common Client Configuration

- OpenID Connect 1.0 Client Configuration

Common Client Configuration

The following configuration fields are common to OAuth 2.0 and OpenID Connect 1.0 clients.

Group

  Set this if you have configured an OAuth 2.0 Client agent group.

Status

  Whether the client profile is active for use.

Client password

  The client password as described by RFC 6749 in the section, Client Password.

Client type

  Confidential clients can maintain confidentiality of their credentials. Public clients cannot.

  A web application running on a server where its credentials are protected is an example of a confidential client.

  A JavaScript client running in a browser is an example of a public client.

Redirection URIs

  Specify client redirection endpoint URIs as described by RFC 6749 in the section, Redirection Endpoint. OpenAM's OAuth 2.0 authorization service redirects the the resource owner's user-agent back to this endpoint during the authorization code grant process. If your client has more than one redirection URI, then it must specify the redirection URI to use in the authorization request.

  Redirection URIs are required for OpenID Connect 1.0 clients.

Scopes

  Specify scopes in ``scope`` or ``scope`|`locale`|`localized description`` format. These scopes are to be presented to the resource owner when the resource owner is asked to authorize client access to protected resources.

Display name

  Specify a client name to display to the resource owner when the resource owner is asked to authorize client access to protected resources. Valid formats include ``name`` or ``locale`|`localized name``.

Display description

  Specify a client description to display to the resource owner when the resource owner is asked to authorize client access to protected resources. Valid formats include ``description`` or ``locale`|`localized description``.

Default Scope(s)

  Specify scopes in ``scope`` or ``scope`|`locale`|`localized description`` format. These scopes are set automatically when tokens are issued.

OpenID Connect 1.0 Client Configuration

The following optional configuration fields are for OpenID Connect 1.0 clients.

ID Token Signed Response Algorithm

  Algorithm that the ID Token for this client must be signed with

  Default: `HmacSHA256`

  Valid values are listed in JSON Web Algorithms (JWA): "alg" (Algorithm) Header Parameter Values for JWS. OpenAM supports `HmacSHA256`, `HmacSHA384`, and `HmacSHA512`.

Post Logout Redirect URI

  URI to which to redirect the user-agent after the client logout process

The access token used to update the client

  The `registration_access_token` value that you provide when registering the client, and then subsequently when reading or updating the client profile.

URI of the Client Application

  The relying party (client) URI to which the OpenID Connect Provider sends session changed notification messages using the HTML 5 postMessage API.

## 6.12. Configuring Agent Authenticators

An agent authenticator has read-only access to multiple agent profiles defined in the same realm, typically allowing an agent to read web service agent profiles.

After creating the agent profile, you access agent properties in the OpenAM console under Access Control > `Realm Name` > Agents > Agent Authenticator > `Agent Name`.

Password

  Specifies the password the agent uses to connect to OpenAM.

Status

  Specifies whether the agent profile is active, and so can be used.

Agent Profiles allow to Read

  Specifies which agent profiles in the realm the agent authenticator can read.

Agent Root URL for CDSSO

  Specifies the list of agent root URLs for CDSSO. The valid value is in the format ``protocol`://`hostname`:`port`/` where `protocol` represents the protocol used, such as `http` or `https`, `hostname` represents the host name of the system where the agent resides, and `port` represents the port number on which the agent is installed. The slash following the port number is required.

  If your agent system also has virtual host names, add URLs with the virtual host names to this list as well. OpenAM checks that `goto` URLs match one of the agent root URLs for CDSSO.

[5] The configuration file syntax is that of a standard Java properties file, though backslash escapes can be used only to wrap long lines. See java.util.Properties.load for a description of the format. The value of a property specified multiple times is not defined.

[6] The configuration file syntax is that of a standard Java properties file, though backslash escapes can be used only to wrap long lines. See java.util.Properties.load for a description of the format. The value of a property specified multiple times is not defined.

Prev |  | Next
Chapter 5. Configuring Realms | Home | Chapter 7. Working with Mobile Devices & Applications