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

Identity Gateway 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 works well with applications where you want to protect access, but you cannot install a policy agent. For example, you might have a web application running in a server for which no policy agent has been developed. Or you might be protecting an application where you simply cannot install a policy agent. 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.

When you open the OpenAM console to configure agents for the top level realm, you see a number of different kinds to choose. Web and J2EE policy agents are the most common, requiring the least integration effort. Policy agents Profiles 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. 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.

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. 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. Creating a new web agent profile At first, you provide only minimal configuration for your new agent. After creating the agent profile, you can click the link to the new profile to adjust and export the configuration. Policy agents Group inheritance 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.

Policy agents Configuring 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.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. 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 for the changes to take effect.

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. 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. Agent Configuration Change Notification Enable agent to receive notfication 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: no 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. 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. 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 3000 bytes, and lower values are reset to 3000 bytes. Default: 10 MB. Property: com.sun.identity.agents.config.debug.file.size 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 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 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.com, enter myserver in the Map Key field, and enter myserver.mydomain.com in the Corresponding Map Value field. This corresponds to com.sun.identity.agents.config.fqdn.mapping[myserver]=myserver.mydomain.com. Invalid FQDN values can cause the web server to become unusable or render resources inaccessible. Property: com.sun.identity.agents.config.fqdn.mapping

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. 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. Property: com.sun.identity.agents.config.ignore.path.info.for.not.enforced.list 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. Do not 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 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 attributes for not enforced URLs by doing policy evaluation. Property: com.sun.identity.agents.config.notenforced.url.attributes.enable 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. 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.0 to 192.168.1.255, use the following setting. com.sun.identity.agents.config.notenforced.ip = 192.168.1.0/24 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.10 to 192.168.1.127 inclusive, use the following setting. com.sun.identity.agents.config.notenforced.ip = 192.168.1.10-192.168.1.127 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 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 Attribute Fetch Mode When set to HTTP_COOKIE or HTTP_HEADER, response attributes are introduced into the cookie or the headers, respectively. Property: com.sun.identity.agents.config.response.attribute.fetch.mode Response Attribute Map Maps the policy response attributes to HTTP headers for the currently authenticated user. The response attribute is the attribute in the policy response to be fetched. To populate the value of response attribute uid under CUSTOM-User-Name: enter uid in the Map Key field, and enter CUSTOM-User-Name in the Corresponding Map Value field. This corresponds to com.sun.identity.agents.config.response.attribute.mapping[uid]=Custom-User-Name. In most cases, in a destination application where an HTTP header name shows up as a request header, it is prefixed by HTTP_, lower case letters become upper case, and hyphens (-) become underscores (_). For example, response-attr-one becomes HTTP_RESPONSE_ATTR_ONE. Property: com.sun.identity.agents.config.response.attribute.mapping Session Attribute Fetch Mode When set to HTTP_COOKIE or HTTP_HEADER, session attributes are introduced into the cookie or the headers, respectively. Property: com.sun.identity.agents.config.session.attribute.fetch.mode Session Attribute Map Maps session attributes to HTTP headers for the currently authenticated user. The session attribute is the attribute in the session to be fetched. To populate the value of session attribute UserToken under CUSTOM-userid: enter UserToken in the Map Key field, and enter CUSTOM-userid in the Corresponding Map Value field. This corresponds to com.sun.identity.agents.config.session.attribute.mapping[UserToken]=CUSTOM-userid. In most cases, in a destination application where an HTTP header name shows up as a request header, it is prefixed by HTTP_, lower case letters become upper case, and hyphens (-) become underscores (_). For example, success-url becomes HTTP_SUCCESS_URL. Property: com.sun.identity.agents.config.session.attribute.mapping 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

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 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 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/cdcservelet. 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.cookie.domain 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

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) This takes the incoming request URL to match, a comma, and then a comma-separated list of URLs to which to redirect incoming users. Property: com.forgerock.agents.conditional.login.url Agent Connection Timeout Timeout period in seconds for an agent connection with OpenAM auth server. Property: com.sun.identity.agents.config.auth.connection.timeout 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 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 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 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 Cookies List for Reset 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 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 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

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. 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 Agent Locale The default locale for the agent. Property: com.sun.identity.agents.config.locale Hot swap: no Anonymous User Enable or disable REMOTE_USER processing for anonymous users. Property: com.sun.identity.agents.config.anonymous.user.enable 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 Comparison Case Sensitivity Check When enabled, enforce case sensitivity 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 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 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 in Request URL When enabled, strip path info from the request URL while doing the Not Enforced List check, and URL policy evaluation. This is designed to prevent a user from accessing a URI by appending the matching pattern in the policy or not enforced list. For example, if the not enforced list includes 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 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 Property used only when CDSSO is enabled. Only change the default value, goto when the login URL has a landing page specified such as, com.sun.identity.agents.config.cdsso.cdcservlet.url = http://openam.example.com:8080/openam/cdcservlet?goto= http://www.example.com/landing.jsp. The agent uses this parameter to append the original request URL to this cdcserlet URL. The landing page consumes this parameter to redirect to the original URL. As an example, if you set this value to goto2, then the complete URL sent for authentication is http://openam.example.com:8080/openam/cdcservlet?goto= http://www.example.com/landing.jsp?goto2=http://www.example.com/original.jsp. Property: com.sun.identity.agents.config.redirect.param Anonymous User Default Value User ID of unauthenticated users. Default: anonymous. Property: com.sun.identity.agents.config.anonymous.user.id

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. 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 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. 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. 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. 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. Property: com.sun.identity.agents.config.override.notification.url 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 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 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 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 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

Policy agents Configuring 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.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. 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.

This section covers global web agent properties. After creating the agent profile, you access these properties in the OpenAM console under Access Control > Realm Name > Agents > J2EE > Agent Name > Global. 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. Configuration Reload Interval Interval in seconds to fetch agent configuration from OpenAM. Used if notifications are disabled. Default: 3600 (1 hour). Property: com.sun.identity.agents.config.load.interval Agent Configuration Change Notification Enable agent to receive notfication messages from OpenAM server for configuration changes. Property: com.sun.identity.agents.config.change.notification.enable Agent Root URL for CDSSO The agent root URL for CDSSO. The valid value is in the format protocol://hostname:port/ where protocol represents the protocol used, such as http or https, hostname represents the host name of the system where the agent resides, and port represents the port number on which the agent is installed. The slash following the port number is required. 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 or even All for fine-grained detail. Property: com.iplanet.services.debug.level 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 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 FQDN Check Enables checking of FQDN default value and FQDN map values. Property: com.sun.identity.agents.config.fqdn.check.enable FQDN Default Fully qualified domain name that the users should use in order to access resources. This property ensures that when users access protected resources on the web server without specifying the FQDN, the agent can redirect the users to URLs containing the correct FQDN. Property: com.sun.identity.agents.config.fqdn.default FQDN Virtual Host Map Enables virtual hosts, partial hostname and IP address to access protected resources. Maps invalid or virtual name keys to valid FQDN values so the agent can properly redirect users and the agents receive cookies belonging to the domain. To map myserver to myserver.mydomain.com, enter myserver in the Map Key field, and enter myserver.mydomain.com in the Corresponding Map Value field. This corresponds to com.sun.identity.agents.config.fqdn.mapping[myserver]=myserver.mydomain.com. Property: com.sun.identity.agents.config.fqdn.mapping

This section covers application web agent properties. After creating the agent profile, you access these properties in the OpenAM console under Access Control > Realm Name > Agents > J2EE > Agent Name > Application. Login 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 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 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 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. Do not 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 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.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 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 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 Profile Attribute Fetch Mode When set to HTTP_COOKIE or HTTP_HEADER, profile attributes are introduced into the cookie or the headers, respectively. When set to REQUEST_ATTRIBUTE, profile attributes are part of the HTTP request. Property: com.sun.identity.agents.config.profile.attribute.fetch.mode Profile Attribute Map Maps the profile attributes to HTTP headers for the currently authenticated user. Map Keys are LDAP attribute names, and Map Values are HTTP header names. To populate the value of profile attribute CN under CUSTOM-Common-Name: enter CN in the Map Key field, and enter CUSTOM-Common-Name in the Corresponding Map Value field. This corresponds to com.sun.identity.agents.config.profile.attribute.mapping[cn]=CUSTOM-Common-Name. In most cases, in a destination application where an HTTP header name shows up as a request header, it is prefixed by HTTP_, lower case letters become upper case, and hyphens (-) become underscores (_). For example, common-name becomes HTTP_COMMON_NAME. Property: com.sun.identity.agents.config.profile.attribute.mapping Response Attribute Fetch Mode When set to HTTP_COOKIE or HTTP_HEADER, response attributes are introduced into the cookie or the headers, respectively. When set to REQUEST_ATTRIBUTE, response attributes are part of the HTTP response. Property: com.sun.identity.agents.config.response.attribute.fetch.mode Response Attribute Map Maps the policy response attributes to HTTP headers for the currently authenticated user. The response attribute is the attribute in the policy response to be fetched. To populate the value of response attribute uid under CUSTOM-User-Name: enter uid in the Map Key field, and enter CUSTOM-User-Name in the Corresponding Map Value field. This corresponds to com.sun.identity.agents.config.response.attribute.mapping[uid]=Custom-User-Name. In most cases, in a destination application where an HTTP header name shows up as a request header, it is prefixed by HTTP_, lower case letters become upper case, and hyphens (-) become underscores (_). For example, response-attr-one becomes HTTP_RESPONSE_ATTR_ONE. Property: com.sun.identity.agents.config.response.attribute.mapping Cookie Separator Character Specifies the separator for multiple values of the same attribute when it is set as a cookie. Default: |. 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 Attribute Fetch Mode When set to HTTP_COOKIE or HTTP_HEADER, session attributes are introduced into the cookie or the headers, respectively. When set to REQUEST_ATTRIBUTE, session attributes are part of the HTTP response. Property: com.sun.identity.agents.config.session.attribute.fetch.mode Session Attribute Map Maps session attributes to HTTP headers for the currently authenticated user. The session attribute is the attribute in the session to be fetched. To populate the value of session attribute UserToken under CUSTOM-userid: enter UserToken in the Map Key field, and enter CUSTOM-userid in the Corresponding Map Value field. This corresponds to com.sun.identity.agents.config.session.attribute.mapping[UserToken]=CUSTOM-userid. In most cases, in a destination application where an HTTP header name shows up as a request header, it is prefixed by HTTP_, lower case letters become upper case, and hyphens (-) become underscores (_). For example, success-url becomes HTTP_SUCCESS_URL. Property: com.sun.identity.agents.config.session.attribute.mapping 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 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 UserTokenm 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.session.attribute 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

This section covers SSO web agent properties. After creating the agent profile, you access these properties in the OpenAM console under Access Control > Realm Name > Agents > J2EE > Agent Name > SSO Cookie 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 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 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/cdcservelet. 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 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

This section covers OpenAM services web agent properties. After creating the agent profile, you access these properties in the OpenAM console under Access Control > Realm Name > Agents > J2EE > Agent Name > OpenAM Services. 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 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 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 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 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 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 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 Hot swap: no Policy Client Boolean Action Values Specifies the values, such as allow and deny, that are associated with boolean policy decisions. Default: iPlanetAMWebAgentService|GET|allow|deny:iPlanetAMWebAgentService|POST|allow|deny Property: com.sun.identity.policy.client.booleanActionValues Hot swap: no Policy Client Resource Comparators Specifies the comparators used for service names in policy. Default: serviceType=iPlanetAMWebAgentService| class=com.sun.identity.policy.plugins.HttpURLResourceName|wildcard=*| delimiter=/|caseSensitive=false Property: com.sun.identity.policy.client.resourceComparators Hot swap: no Policy Client Clock Skew Time in seconds used adjust time difference between agent system and OpenAM. Clock skew in seconds = AgentTime - OpenAMServerTime. Default: 10. Property: com.sun.identity.agents.config.policy.clock.skew 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 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 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 Hot swap: no 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 Hot swap: no

This section covers miscellaneous web agent properties. After creating the agent profile, you access these properties in the OpenAM console under Access Control > Realm Name > Agents > J2EE > Agent Name > Miscellaneous. Locale 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 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 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 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 in Request URL When enabled, strip path info from the request URL while doing the Not Enforced List check, and URL policy evaluation. This is designed to prevent a user from accessing a URI by appending the matching pattern in the policy or not enforced list. For example, if the not enforced list includes /*.gif, then stripping path info from the request URL prevents access to http://host/index.html by using http://host/index.html?hack.gif. Property: com.sun.identity.agents.config.ignore.path.info Goto Parameter Name Property used only when CDSSO is enabled. Only change the default value, goto when the login URL has a landing page specified such as, com.sun.identity.agents.config.cdsso.cdcservlet.url = http://openam.example.com:8080/openam/cdcservlet?goto= http://www.example.com/landing.jsp. The agent uses this parameter to append the original request URL to this cdcserlet URL. The landing page consumes this parameter to redirect to the original URL. As an example, if you set this value to goto2, then the complete URL sent for authentication is http://openam.example.com:8080/openam/cdcservlet?goto= http://www.example.com/landing.jsp?goto2=http://www.example.com/original.jsp. Property: com.sun.identity.agents.config.redirect.param Legacy User Agent Support Enable When enabled, provide support for legacy browsers. Property: com.sun.identity.agents.config.legacy.support.enable Legacy User Agent List List of header values that identify legacy browsers. Entries can use the wildcard character, *. Property: com.sun.identity.agents.config.legacy.user.agent Legacy User Agent Redirect URI Specifies a URI the agent uses to redirect legacy user agent requests. Property: com.sun.identity.agents.config.legacy.redirect.uri

This section covers advanced web agent properties. After creating the agent profile, you access these properties in the OpenAM console under Access Control > Realm Name > Agents > J2EE > Agent Name > Advanced. If the agent is behind a proxy or load balancer, then the agent can get client IP and host name values from the proxy or load balancer. For proxies and load balancer that support providing the client IP and host name in HTTP headers, you can use the following properties. When multiple proxies are load balancers sit in the request path, the header values can include a comma-separated list of values with the first value representing the client, as in client,next-proxy,first-proxy. Client IP Address Header HTTP header name that holds the IP address of the client. Property: com.sun.identity.agents.config.client.ip.header Client Hostname Header HTTP header name that holds the hostname of the client. Property: com.sun.identity.agents.config.client.hostname.header Web Service 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 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 WebAuthentication Available When enabled, allow programmatic authentication with the JBoss container using the WebAuthentication feature. Property: com.sun.identity.agents.config.jboss.webauth.available 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.preservce.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 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

Policy agents Configuring 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. 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 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 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. 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. 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. 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 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.

Policy agents Configuring 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. 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 Mechanism Specifies the mechanism used to secure web service requests. STS Configuration Specifies the agent used to secure requests to the Security Token Service. Discovery Configuration Specifies the agent used to secure requests to the Discovery Service. 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 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. 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. 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. 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 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.

Policy agents Configuring This section covers Discover Service Client properties. Discovery Service clients get Liberty security tokens from a Liberty Discovery Service. After creating a Discovery Client profile, you access Discovery agent properties in the OpenAM console under Access Control > Realm Name > Agents > STS Client > Agent Name. 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. Private Key Alias Specifies the alias of the private key used to sign requests and decrypt responses. Discovery Service End Point Specifies the end point with which the trust authority client communicates for service registration and service lookups. Authentication Web Service End Point Specifies the end point with which the web services client communicates to get end user SSOTokens and Discover Service resource offerings.

Policy agents Configuring 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. 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 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 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. 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. 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. 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 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.

Policy agents Configuring 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.

Policy agents Configuring 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.