Configuring Policy Agent Profiles

You install policy agents in web servers and web application containers to enforce access policies OpenAM applies to protected web sites and web applications. Policy agents depend on OpenAM for all authentication and authorization decisions. Their primary responsibility consists of 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. Typically, 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. In this way, you manage all agent configuration changes centrally. This chapter describes how to set up policy agent profiles in OpenAM for centralized configuration.

OpenIG or Policy Agent?

OpenAM supports both OpenIG and also a variety of policy agents. OpenIG and the policy agents can both enforce policy, redirecting users to authenticate when necessary, and controlling access to protected resources. OpenIG 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.

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

For organizations with both servers on which 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 OpenIG for the latter.

Types of Agent

You can configure a number of different types of agents.

Each agent type requires an agent profile in OpenAM. The agent profile contains essential configuration for agent operation, such as a password to authenticate the agent, and the URL the agent resides at. For agents that support it, the agent profile can store all agent configuration centrally, rather than locally on the agent server.

Web and J2EE policy agents are the most common, requiring the least integration effort. The available agent types are:

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.
2.2 Agents: Version 2.2 web and Java EE policy agents hold their configuration locally, connecting to OpenAM with a username/password combination. This agent type is provided for backwards compatibility.
OAuth 2.0/OpenID Connect Client: Register OAuth 2.0 and OpenID Connect clients using this type of 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.
SOAP STS Agent: Secure requests from a SOAP STS deployment to OpenAM using this type of agent profile.

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.

To Create an Agent Profile

To create a new Web or Java EE policy agent profile, you need to create a name and password for the agent. You also need the URLs to OpenAM and the application to protect:

Login to OpenAM Console as an administrative user.
On the Realms menu of the OpenAM console, select the realm in which the agent profile is to be managed.
Click the Agents link, click the tab page for the kind of agent profile you want to create, and then click the New button in the Agent table.
In the Name field, enter a name for the agent profile.
In the Password and Re-Enter Password fields, enter a password for the new agent profile.
Click Local or Centralized (Default) to determine where the agent properties are stored. If you select Local, the properties are stored on the server on which the agent is running. If you select Centralized, the properties are stored on the OpenAM server.
In the Server URL field, enter the URL to OpenAM. For example, http://openam.example.com:8080/openam.
In the Agent URL field, enter the primary URL of the web or application server protected by the policy agent. Note for web agents, an example URL would look like: http://www.example.com:80. For Java EE policy agents, an example URL must include the agentapp context: http://www.example.com:8080/agentapp.
Click Create. After creating the agent profile, you can click the link to the new profile to adjust and export the configuration.

To Create an Agent Profile Group and Inherit Settings

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

Login to OpenAM Console as an administrative user.
On the Realms menu of the OpenAM console, Select the realm in which you manage agents.
Click the Agents link, click the tab page for the kind of agent group you want to create, and then in the Group table, click New.

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.

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 policy agent profile using the ssoadm command:

Make sure the ssoadm command is installed. See "To Set Up Administration Tools" in the Installation Guide.

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

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

$ cat myAgent.properties
com.iplanet.am.server.port=8443
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
sunIdentityServerDeviceKeyValue[0]=agentRootURL=http://www.example.com:80/
sunIdentityServerDeviceStatus=Active
userpassword=password

Create a password file, for example $HOME/.pwd.txt. The file should only contain the password string, on a single line.

The password file must be read-only for the user who creates the policy agent profile, and must not be accessible to other users:
```
$ chmod 400 $HOME/.pwd.txt
```

Create the profile in OpenAM:

$ ssoadm create-agent \
  --realm / \
  --agentname myAgent \
  --agenttype J2EEAgent \
  --adminid amadmin \
  --password-file $HOME/.pwd.txt \
  --datafile myAgent.properties

Agent configuration was created.

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

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 you delegate policy agent installation, then you might not want to share OpenAM administrator credentials with everyone who installs policy agents.

To Create Agent Administrators for a Realm

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

In OpenAM console, browse to Realms > 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. For silent installs, you can add the --acceptLicense option to auto-accept the software license agreement.

Configuring Web Policy Agent 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. For information on the properties used in a centralized configuration, and the corresponding properties for use in a local configuration file where applicable, see Configuring Web Policy Agent Properties in the OpenAM Web Policy Agent User’s Guide.

Configuring Java EE Policy Agents

When you create a Java EE 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 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. ^[1]

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 application server or web server, or the agent’s container.

Configuring Java EE Policy Agent Global Properties

This section covers global Java EE agent properties. After creating the agent profile, you access these properties in the OpenAM console under Realms > Realm Name > Agents > J2EE > Agent Name > Global.

Profile Properties

Group: For assigning the agent to a previously configured Java EE agent group in order to inherit selected properties from the group.
Password: Agent password used when creating the password file and when installing the agent.
Status: Status of the agent configuration.
Agent Notification URL: URL used by agent to register notification listeners.

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

Hot swap: no
Location of Agent Configuration Repository: Indicates agent’s configuration located either on agent’s host or centrally on OpenAM server.

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

Property: com.sun.identity.agents.config.repository.location
Configuration Reload Interval: Interval in seconds to fetch agent configuration from OpenAM. Used if notifications are disabled. Default: 0

Property: com.sun.identity.agents.config.load.interval
Agent Configuration Change Notification: Enable agent to receive notification messages from OpenAM server for configuration changes.

Property: com.sun.identity.agents.config.change.notification.enable
Agent Root URL for CDSSO: The agent root URL for CDSSO. The valid value is in the format protocol://hostname:port/ where protocol represents the protocol used, such as http or https, hostname represents the host name of the system where the agent resides, and port represents the port number on which the agent is installed. The slash following the port number is required.

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

General Properties

Agent Filter Mode

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

ALL: Enforce both the Java EE 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 URL resource-based policies defined in OpenAM.

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 File Name: 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: When 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: FQDN users should use to access resources.

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

Property: com.sun.identity.agents.config.fqdn.default
FQDN Virtual Host Map: Enables virtual hosts, partial hostname and IP address to access protected resources. Maps invalid or virtual name keys to valid FQDN values so the agent can properly redirect users and the agents receive cookies belonging to the domain.

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

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

Configuring Java EE Policy Agent Application Properties

This section covers application J2EE agent properties. After creating the agent profile, you access these properties in the OpenAM console under Realms > 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

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 resets the stateful session idle time when granting access to a not enforced URI, prolonging the time before the user must authenticate again. This setting has no effect on users with stateless sessions.

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

Loopback addresses are not considered valid IPs on the Not Enforced IP list. If specified, the policy agent ignores the loopback address.

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 Mapping: Maps the profile attributes to HTTP headers for the currently authenticated user. Map Keys are attribute names, and Map Values are HTTP header names. The user profile can be stored in LDAP or any other arbitrary data store.

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

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

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

Response Attributes Processing Properties

Response Attribute Fetch Mode: When set to HTTP_COOKIE or HTTP_HEADER, response attributes are introduced into the cookie or the headers, respectively. When set to REQUEST_ATTRIBUTE, response attributes are part of the HTTP request.

Property: com.sun.identity.agents.config.response.attribute.fetch.mode
Response Attribute Mapping: Maps the policy response attributes to HTTP headers for the currently authenticated user. The response attribute is the attribute in the policy response to be fetched.

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

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

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

Common Attributes Fetching Processing Properties

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

Property: com.sun.identity.agents.config.attribute.cookie.separator
Fetch Attribute Date Format: Specifies the java.text.SimpleDateFormat of date attribute values used when an attribute is set in an HTTP header. Default: EEE, d MMM yyyy hh:mm:ss z.

Property: com.sun.identity.agents.config.attribute.date.format
Attribute Cookie Encode: When enabled, attribute values are URL-encoded before being set as a cookie.

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

Session Attributes Processing Properties

Session Attribute Fetch Mode: When set to HTTP_COOKIE or HTTP_HEADER, session attributes are introduced into the cookie or the headers, respectively. When set to REQUEST_ATTRIBUTE, session attributes are part of the HTTP request.

Property: com.sun.identity.agents.config.session.attribute.fetch.mode
Session Attribute Mapping: Maps session attributes to HTTP headers for the currently authenticated user. The session attribute is the attribute in the session to be fetched.

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

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

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

Privilege Attributes Processing Properties

Privileged attributes are used when the agent is running in ALL or J2EE_POLICY filter mode. Privileged attributes contain the list of declarative Java EE roles that the user can have:

Default Privileged Attribute: Specifies that every authenticated user with a valid OpenAM session will have the AUTHENTICATED_USERS role.

Property: com.sun.identity.agents.config.default.privileged.attribute
Privileged Attribute Type: Specifies the group and role memberships that will be turned into roles 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 when an authenticated user’s roles are store within a session property.

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

Configuring Java EE Policy Agent SSO Properties

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

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

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

Configuring Java EE Policy Agent OpenAM Services Properties

This section covers OpenAM services J2EE agent properties. After creating the agent profile, you access these properties in the OpenAM console under Realms > 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 that they can authenticate. If CDSSO is enabled, this property is not used, instead the CDCServlet URL will be used.

Property: com.sun.identity.agents.config.login.url
OpenAM Conditional Login URL (Not yet in OpenAM console): To conditionally redirect users based on the incoming request URL, set this property.

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

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

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

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

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

CDSSO examples: com.sun.identity.agents.config.conditional.login.url[0]= login.example.com|http://openam1.example.com/openam/cdcservlet, http://openam2.example.com/openam/cdcservlet, com.sun.identity.agents.config.conditional.login.url[1]= signin.example.com|http://openam3.example.com/openam/cdcservlet, http://openam4.example.com/openam/cdcservlet
Login URL Prioritized: When enabled, OpenAM uses the priority defined in the OpenAM Login URL list as the priority for Login and CDSSO URLs when handling failover.

Property: com.sun.identity.agents.config.login.url.prioritized
Login URL Probe: When enabled, OpenAM checks the availability of OpenAM Login URLs before redirecting to them.

Property: com.sun.identity.agents.config.login.url.probe.enabled
Login URL Probe Timeout: Timeout period in milliseconds for OpenAM to determine whether to failover between Login URLs when Login URL Probe is enabled.

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

Default: 2000

Logout URL Properties

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

Property: com.sun.identity.agents.config.logout.url
OpenAM Conditional Logout URL (Not yet in OpenAM console): The values take the incoming request URL to match and a comma-separated list of URLs to which to redirect users logging out.

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

Example: com.sun.identity.agents.config.conditional.logout.url[0]= logout.example.com|http://openam1.example.com/openam/UI/Logout, http://openam2.example.com/openam/UI/Logout
Logout URL Prioritized: When enabled, OpenAM uses the priority defined in the OpenAM Logout URL list as the priority for Logout URLs when handling failover.

Property: com.sun.identity.agents.config.logout.url.prioritized
Logout URL Probe: When enabled, OpenAM checks the availability of OpenAM Logout URLs before redirecting to them.

Property: com.sun.identity.agents.config.logout.url.probe.enabled
Logout URL Probe Timeout: Timeout period in milliseconds for OpenAM to determine whether to failover between Logout URLs when Logout URL Probe is enabled.

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

Default: 2000

Authentication Service Properties

OpenAM Authentication Service Protocol: Specifies the protocol used by the OpenAM authentication service.

Property: com.iplanet.am.server.protocol

Hot swap: no
OpenAM Authentication Service Host Name: Specifies the OpenAM authentication service host name.

Property: com.iplanet.am.server.host

Hot swap: no
OpenAM Authentication Service Port: Specifies the OpenAM authentication service port number.

Property: com.iplanet.am.server.port

Hot swap: no

Policy Client Service Properties

Realm: Realm where OpenAM starts policy evaluation for this policy agent.

Default: Top Level Realm (/)

Edit this property when OpenAM should start policy evaluation in a realm other than the Top Level Realm, /, when handling policy decision requests from this policy agent.

This property is recognized by OpenAM, not the policy agent.

Property: org.forgerock.openam.agents.config.policy.evaluation.realm

Hot swap: yes
Application: The name of the policy set where OpenAM looks for policies to evaluate for this policy agent.

Default: iPlanetAMWebAgentService

Edit this property when OpenAM should look for policies that belong to a policy set other than iPlanetAMWebAgentService when handling policy decision requests from this policy agent.

This property is recognized by OpenAM, not the policy agent.

Property: org.forgerock.openam.agents.config.policy.evaluation.application

Hot swap: yes
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. The string is presented below in multiple lines for readability purposes.

Default: iPlanetAMWebAgentService|GET|allow|deny: iPlanetAMWebAgentService|POST|allow|deny: iPlanetAMWebAgentService|PUT|allow|deny: iPlanetAMWebAgentService|DELETE|allow|deny: iPlanetAMWebAgentService|HEAD|allow|deny: iPlanetAMWebAgentService|OPTIONS|allow|deny: iPlanetAMWebAgentService|PATCH|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 to 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 set 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 set 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 set 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

Configuring Java EE Policy Agent Miscellaneous Properties

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

Locale Properties

Locale Language: The default language for the agent.

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

Hot swap: no
Locale Country: The default country for the agent.

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

Hot swap: no

Port Check Processing Properties

Port Check Enable: When enabled, activate port checking, correcting requests on the wrong port.

Property: com.sun.identity.agents.config.port.check.enable
Port Check File: Specifies the name of the file containing the content to handle requests on the wrong port when port checking is enabled.

Property: com.sun.identity.agents.config.port.check.file
Port Check Setting: Specifies which ports correspond to which protocols. The agent uses the map when handling requests with invalid port numbers during port checking.

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

Bypass Principal List Properties

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

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

Agent Password Encryptor Properties

Encryption Provider: Specifies the agent’s encryption provider class.

Default: com.iplanet.services.util.JCEEncryption

Property: com.iplanet.security.encryptor

Hot swap: no

Ignore Path Info Properties

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

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

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

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

Configuring Java EE Policy Agent Advanced Properties

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

Client Identification Properties

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

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

Client IP Address Header: HTTP header name that holds the IP address of the client.

Property: com.sun.identity.agents.config.client.ip.header
Client Hostname Header: HTTP header name that holds the hostname of the client.

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

Web Service Processing Properties

Web Service Enable: Enable web service processing.

Property: com.sun.identity.agents.config.webservice.enable
Web Service End Points: Specifies a list of web application end points that represent web services.

Property: com.sun.identity.agents.config.webservice.endpoint
Web Service Process GET Enable: When enabled, the agent processes HTTP GET requests for web service endpoints.

Property: com.sun.identity.agents.config.webservice.process.get.enable
Web Service Authenticator: Specifies a class implementing com.sun.identity.agents.filter.IWebServiceAuthenticator, used to authenticate web service requests.

Property: com.sun.identity.agents.config.webservice.authenticator
Web Service Response Processor: Specifies a class implementing com.sun.identity.agents.filter.IWebServiceResponseProcessor, used to process web service responses.

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 certain versions of JBoss when the J2EE_POLICY or ALL filter mode is in use.

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

This setting is not necessary for the JBoss v7 agent.

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 enabled: 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
PDP 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

TCP Connection Timeout

TCP Connection Timeout: Sets the TCP connection timeout for outbound HTTP connections created by the Java EE policy agent. Set the property in the OpenSSOAgentBootstrap.properties file.

Property: org.forgerock.openam.url.connectTimeout

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

Configuring Version 2.2 Policy Agents

This section covers version 2.2 policy agent properties. Version 2.2 agents store their configurations locally with a username-password combination used to connect to OpenAM.

Open Identity Platform Community no longer supports 2.2 policy agents. Documentation exists only for legacy systems. Do not use 2.2 policy agents for new deployments.

After creating the agent profile, you access agent properties in the OpenAM console under Realms > Realm Name > Agents > 2.2 Agents > Agent Name. Properties include:

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.

Configuring OAuth 2.0 and OpenID Connect 1.0 Clients

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 Realms > Realm Name > Agents > OAuth 2.0/OpenID Connect Client > Client Name.

OAuth 2.0 and OpenID Connect 1.0 Client Configuration Fields

The following configuration fields are for OAuth 2.0 and OpenID Connect 1.0:

Group

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

Status

Specify whether the client profile is active for use or inactive.

Client password

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

Client type

Specify the client type.

Confidential clients can maintain the confidentiality of their credentials, such as a web application running on a server where its credentials are protected. Public clients run the risk of exposing their passwords to a host or user agent, such as a JavaScript client running in a browser.

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 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. The redirection URI must NOT contain a fragment (#).

Redirection URIs are required for OpenID Connect 1.0 clients.

Scopes

Specify scopes that are to be presented to the resource owner when the resource owner is asked to authorize client access to protected resources.

Scopes can be entered as simple strings, such as read, email, profile, or openid, or as a pipe-separated string in the format: scope|locale|localized description. For example, read|en|Permission to view email messages.

Locale strings have the format: language_country_variant. For example, en, en_GB, or en_US_WIN. If the locale and pipe is omitted, the localized description is displayed to all users having undefined locales. If the localized description is omitted, nothing is displayed to all users. For example, a scope of read| would allow the client to use the read scope but would not display it to the user when requested.

Claim(s)

Specify one or more claim name translations that will override those specified for the authentication session. Claims are values that are presented to the user to inform them what data is being made available to the client.

Claims can be in entered as simple strings, such as name, email, profile, or sub, or as a pipe-separated string in the format: scope|locale|localized description. For example, name|en|Full name of user.

Locale strings have the format: language_country_variant. For example, en, en_GB, or en_US_WIN. If the locale and pipe is omitted, the localized description is displayed to all users having undefined locales. If the localized description is omitted, nothing is displayed to all users. For example, a claim of name| would allow the client to use the name claim but would not display it to the user when requested.

If a value is not given, the value is computed from the OAuth2 provider.

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.

The Display name can be entered as a single string or as a pipe-separated string for locale and localized name, for example, en|My Example Company.

Locale strings have the format: language_country_variant. For example, en, en_GB, or en_US_WIN. If the locale is omitted, the name is displayed to all users having undefined locales.

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.

The Display description can be entered as a single string or as a pipe-separated string for locale and localized name, for example, en|The company intranet is requesting the following access permission.

Locale strings have the format: language_country_variant. For example, en, en_GB, or en_US_WIN. If the locale is omitted, the name is displayed to all users having undefined locales.

Default Scope(s)

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

Default scopes can be in entered as simple strings, such as read, email, profile, or openid, or as a pipe-separated string in the format: scope|locale|localized description. For example, read|en|Permission to view email messages.

Response Types

Specify the response type that the client uses. The response type value specifies the flow that determine how the ID token and access token are returned to the client. For more information, see OAuth 2.0 Multiple Response Type Encoding Practices.

By default, the following response types are available:

code. Specifies that the client application requests an authorization code grant.
token. Specifies that the client application requests an implicit grant type and requests a token from the API.
id_token. Specifies that the client application requests an ID token.
code token. Specifies that the client application requests an access token, access token type, and an authorization code.
token id_token. Specifies that the client application requests an access token, access token type, and an ID token.
code id_token. Specifies that the client application requests an authorization code and an ID token.
code token id_token. Specifies that the client application requests an authorization code, access token, access token type, and an ID token.

Contacts

Specify the email addresses of users who administer the client.

Token Endpoint Authentication Method

Specify the authentication method the token endpoint should use as specified in section 9 of the OpenID Connect Core 1.0 incorporating errata set 1.

client_secret_basic. Clients authenticate with OpenAM (as an authorization server) using the HTTP Basic authentication scheme after receiving a client_secret value.
client_secret_post. Clients authenticate with OpenAM (as an authorization server) by including the client credentials in the request body after receiving a client_secret value.
private_key_jwt. Clients sign a JSON web token (JWT) with a registered public key.

Json Web Key URI

Specify the URI that contains the client’s public keys in JSON web key format.

Json Web Key

Raw JSON web key value containing the client’s public keys.

Sector Identifier URI

Specify the host component of this URI, which is used in the computation of pairwise subject identifiers.

Subject Type

Specify the subject identifier type, which is a locally unique identifier that will be consumed by the client. Select one of two options:

public. Provides the same sub (subject) value to all clients.
pairwise. Provides a different sub (subject) value to each client.

ID Token Signing Algorithm

Specify the signing algorithm that the ID token must be signed with.

Enable ID Token Encryption

Enable ID token encryption using the specified ID token encryption algorithm.

ID Token Encryption Algorithm

Specify the algorithm that the ID token must be encrypted with.

Default value: RSA1_5 (RSAES-PKCS1-V1_5).

ID Token Encryption Method

Specify the method that the ID token must be encrypted with.

Default value: A128CBC-HS256.

Client ID Token Public Encryption Key

Specify the Base64-encoded public key for encrypting ID tokens.

Post Logout Redirect URIs

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

Access Token

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

Client Session URI

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

Client Name

Specify a human-readable name for the client.

Client JWT Bearer Public Key Certificate

Specify the public key certificate of the client’s key pair that is used to sign JWTs issued by the client and used for client authentication or to request access tokens.

This is the base64-encoded X509 certificate containing the public key in PEM format, as in the following example.

You can generate a key pair and export the certificate by using the Java keytool command.

$ keytool \
 -genkeypair \
 -keysize 2048 \
 -alias self-signed \
 -keyalg rsa \
 -dname "CN=jwt-bearer-client,O=openam.example.com" \
 -keystore keystore.jceks \
 -storetype JCEKS \
 -keypass changeit \
 -storepass changeit \
 -validity 3650 \
 -v
Generating 2,048 bit RSA key pair and self-signed certificate (SHA256withRSA)
 with a validity of 3,650 days
    for: CN=jwt-bearer-client, O=openam.example.com
[Storing keystore.jceks]

$ keytool \
 -list \
 -alias self-signed \
 -rfc \
 -keystore keystore.jceks \
 -storepass JCEKS \
 -keypass changeit \
 -storepass changeit
Alias name: self-signed
Creation date: Oct 27, 2014
Entry type: PrivateKeyEntry
Certificate chain length: 1
Certificate[1]:
 -----BEGIN CERTIFICATE-----
 MIIDETCCAfmgAwIBAgIEQKeM1DANBgkqhkiG9w0BAQsFADA5MRswGQYDVQQKExJv
 cGVuYW0uZXhhbXBsZS5jb20xGjAYBgNVBAMTEWp3dC1iZWFyZXItY2xpZW50MB4X
 DTE2MDgyMjIzMjIzMFoXDTI2MDgyMDIzMjIzMFowOTEbMBkGA1UEChMSb3BlbmFt
 LmV4YW1wbGUuY29tMRowGAYDVQQDExFqd3QtYmVhcmVyLWNsaWVudDCCASIwDQYJ
 KoZIhvcNAQEBBQADggEPADCCAQoCggEBAOGbrYP1phjab8GpHKJ93EvPi209RyTs
 g/iaSetgaOeVIepEqKjIpj91v69a2VlrJCeaUDCcCF/JiCBGuyfA8AngtP85bZcY
 MLNdRVmkA3G/wVdE9buzMFWUcl5teVS8Xcgut9mXCjd7GEcCkfLbMU8B1s5nm2dE
 +a8Y1+QXJ1hA4MpI+SdlyRTYkfrn8L3dyJOuFtsedAnv9AbNx2y3Qi315OUykoRo
 ewS7gokWeZsjf0sJuJrtN7drjx8Tx7w0QCxKB0XFRqJpMoRWAWQwgrTpoBEHGbWp
 eeMko50fLcflI8ZUpmN8afJDW72c7ppk80pe/7K//tY/tg22Or/f1IUCAwEAAaMh
 MB8wHQYDVR0OBBYEFMUXBJzh5UFlDJc/lbd8mnbdzu56MA0GCSqGSIb3DQEBCwUA
 A4IBAQCpiDgSaNaEYuEKeI2edkiaVDx2wX+XE7pP0AfImNPfQkKpPNmlMQY9fY+l
 Uy/eS5bTt7983NzqvySpaxJHqaWpW8udZ3kBbfFBiON44uk7st+Kf3PDSQp4oCdi
 qB8KTqTFaX1B368jIMCpbYkRZSPQEXoZfHRv1omRD3YT2dmhOoIIj/JM7XTtS03I
 dZeyQgiUOKIkn2DJN6qB7wcH1pql7tFtRBnnOYinAJuC3FcSGSTzWeCKQn29yb39
 4ab5bHMDpS+F34qqjHBKmIj9TrL9EC5AOh8746i9orat1OEwtLsFh2r1Ia8Nz6a8
 U/tcxzZSu9pNnCEC7Pi0oZ++6Fo/
 -----END CERTIFICATE-----

Default Max Age

Specify the maximum time in seconds that a user can be authenticated. If the user last authenticated earlier than this value, then the user must be authenticated again. If specified, the request parameter max_age overrides this setting.

Minimum value: 1.

Default: 600

Default Max Age Enabled

Enable the default max age feature.

Public key selector

Select the public key for this client, which comes from either the JWKs_URI, manual JWKs, or X.509 field.

Authorization Code Lifetime (seconds)

Specify the time in seconds for an authorization code to be valid. If this field is set to zero, the authorization code lifetime of the OAuth2 provider is used.

Default: 6000

Refresh Token Lifetime (seconds)

Specify the time in seconds for a refresh token to be valid. If this field is set to zero, the refresh token lifetime of the OAuth2 provider is used. If the field is set to -1, the token will never expire.

Default: 6000

Access Token Lifetime (seconds)

Specify the time in seconds for an access token to be valid. If this field is set to zero, the access token lifetime of the OAuth2 provider is used.

Default: 6000

OpenID Connect JWT Token Lifetime (seconds)

Specify the time in seconds for a JWT to be valid. If this field is set to zero, the JWT token lifetime of the OAuth2 provider is used.

Default: 6000

Implied Consent

Enable the implied consent feature. When enabled, the resource owner will not be asked for consent during authorization flows. The OAuth2 Provider must also be configured to allow clients to skip consent.

JWKs URI content cache timeout in ms

Specify the maximum amount of time, in milliseconds, that the content of the JWKS URI can be cached before being refreshed. This avoids fetching the JWKS URI content for every token encryption.

Default: 3600000

JWKs URI content cache miss cache time

Specify the minimum amount of time, in milliseconds, that the content of the JWKS URI is cached. This avoids fetching the JWKS URI content for every token signature verification, for example if the key ID (kid) is not in the JWKS content already cached.

Default: 60000

User info signed response algorithm

Specify the JSON Web Signature (JWS) algorithm for signing UserInfo Responses. If specified, the response will be JSON Web Token (JWT) serialized, and signed using JWS.

The default, if omitted, is for the UserInfo Response to return the claims as a UTF-8-encoded JSON object using the application/json content type.

User info encrypted response algorithm

Specify the JSON Web Encryption (JWE) algorithm for encrypting UserInfo Responses.

If both signing and encryption are requested, the response will be signed then encrypted, with the result being a nested JWT.

The default, if omitted, is that no encryption is performed.

User info encrypted response encryption algorithm

Specify the JWE encryption method for encrypting UserInfo Responses. If specified, you must also specify an encryption algorithm in the User info encrypted response algorithm property.

OpenAM supports the following encryption methods:

A128GCM, A192GCM, and A256GCM - AES in Galois Counter Mode (GCM) authenticated encryption mode.
A128CBC-HS256, A192CBC-HS384, and A256CBC-HS512 - AES encryption in CBC mode, with HMAC-SHA-2 for integrity.

Default: A128CBC-HS256

User info response format

Specify the output format from the UserInfo endpoint.

The supported output formats are as follows:

User info JSON response format.
User info encrypted JWT response format.
User info signed JWT response format.
User info signed then encrypted response format.

For more information on the output format of the UserInfo Response, see Successful UserInfo Response in the OpenID Connect Core 1.0 incorporating errata set 1 specification.

Default: User info JSON response format.

Token Endpoint Authentication Signing Algorithm

Specify the JWS algorithm that must be used for signing JWTs used to authenticate the client at the Token Endpoint.

JWTs that are not signed with the selected algorithm in token requests from the client using the private_key_jwt or client_secret_jwt authentication methods will be rejected.

Default: RS256

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

Configuring SOAP STS Agents

A SOAP STS deployment accesses OpenAM using a SOAP STS agent.

After creating the agent profile, you access agent properties in the OpenAM console under Realms > Realm Name > Agents > SOAP STS Agent > Agent Name.

Group: Assigns the agent to a previously configured SOAP STS agent group in order to inherit selected properties from the group.
Password: Specifies the password the SOAP STS deployment uses when accessing OpenAM.
Poll Interval: Specifies how often the SOAP STS deployment should poll OpenAM for configuration changes to SOAP STS instances in the deployment.

1. The configuration file syntax is that of a standard Java properties file. Seejava.util.Properties.load()for a description of the format. The value of a property specified multiple times is not defined.