Chapter 6. Configuring Policy Agent Profiles
Prev		Next

Chapter 6. Configuring Policy Agent Profiles

Table of Contents

6.1. Identity Gateway or Policy Agent?
6.2. Kinds of Agent Profiles
6.3. Creating Agent Profiles
6.4. Delegating Agent Profile Creation
6.5. Configuring Web Policy Agents
6.6. Configuring J2EE Policy Agents
6.7. Configuring Web Service Provider Policy Agents
6.8. Configuring Web Service Client Policy Agents
6.9. Configuring Security Token Service Client Policy Agents
6.10. Configuring Version 2.2 Policy Agents
6.11. Configuring OAuth 2.0 & OpenID Connect 1.0 Clients
6.12. Configuring Agent Authenticators

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.

On the Access Control tab page of the OpenAM console, click the link for the realm in which you manage agents.
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.
Provide a name for the agent, and also the URLs to OpenAM and to the application to protect, then click Create.

[D]
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.

On the Access Control tab page of the OpenAM console, click the link for the realm in which you manage agents.
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.
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.

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

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

Set up a password file used when authenticating to OpenAM.
```
$ echo password > /tmp/pwd.txt
$ chmod 400 /tmp/pwd.txt
```

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.

In OpenAM console, browse to Access Control > Realm Name > Subjects.
Under Group click New... and create a group for agent administrators.
Switch to the Privileges tab for the realm, and click the name of the group you created.
Select "Read and write access to all configured Agents," and then Save your work.
Return to the Subjects tab, and under User create as many agent administrator users as needed.
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.
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

6.5.1. Configuring Web Policy Agent Global Properties
6.5.2. Configuring Web Policy Agent Application Properties
6.5.3. Configuring Web Policy Agent SSO Properties
6.5.4. Configuring Web Policy Agent OpenAM Services Properties
6.5.5. Configuring Web Policy Agent Miscellaneous Properties
6.5.6. Configuring Web Policy Agent Advanced Properties

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.

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.

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.

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

6.6.1. Configuring J2EE Policy Agent Global Properties
6.6.2. Configuring J2EE Policy Agent Application Properties
6.6.3. Configuring J2EE Policy Agent SSO Properties
6.6.4. Configuring J2EE Policy Agent OpenAM Services Properties
6.6.5. Configuring J2EE Policy Agent Miscellaneous Properties
6.6.6. Configuring J2EE Policy Agent Advanced Properties

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

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

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

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

6.6.2. Configuring J2EE Policy Agent Application 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.

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.

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.

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

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

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.

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.

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

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

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.

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

Client Identification properties

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

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