Guide to configuring and using OpenAM features. OpenAM provides open source Authentication, Authorization, Entitlement, and Federation software.

Preface

This guide shows you how to configure, maintain, and troubleshoot OpenAM for single sign on and authorization, password reset, account lockout, cross-domain single sign on, and federation.

1. Who Should Use This Guide

This guide is written for access management designers and administrators who build, deploy, and maintain OpenAM services for their organizations. This guide covers the tasks you might repeat throughout the life cycle of an OpenAM release used in your organization.

This guide starts by introducing the OpenAM administrative interfaces and tools, and by showing how to manage OpenAM services. This guide continues by showing how to configure the principle features of OpenAM. It then demonstrates how to backup, restore, monitor, tune, and troubleshoot, OpenAM services.

You do not need to be an OpenAM wizard to learn something from this guide, though a background in access management and maintaining web application software can help. You do need some background in managing services on your operating systems and in your application servers. You can nevertheless get started with this guide, and then learn more as you go along.

2. Formatting Conventions

Most examples in the documentation are created in GNU/Linux or Mac OS X operating environments. If distinctions are necessary between operating environments, examples are labeled with the operating environment name in parentheses. To avoid repetition file system directory names are often given only in UNIX format as in /path/to/server, even if the text applies to C:\path\to\server as well.

Absolute path names usually begin with the placeholder /path/to/. This path might translate to /opt/, C:\Program Files\, or somewhere else on your system.

Command-line, terminal sessions are formatted as follows:

$ echo $JAVA_HOME
/path/to/jdk

Command output is sometimes formatted for narrower, more readable output even though formatting parameters are not shown in the command.

Program listings are formatted as follows:

class Test {
    public static void main(String [] args)  {
        System.out.println("This is a program listing.");
    }
}

3. Accessing Documentation Online

ForgeRock publishes comprehensive documentation online:

The ForgeRock Knowledge Base offers a large and increasing number of up-to-date, practical articles that help you deploy and manage ForgeRock software.
While many articles are visible to community members, ForgeRock customers have access to much more, including advanced information for customers using ForgeRock software in a mission-critical capacity.
ForgeRock product documentation, such as this document, aims to be technically accurate and complete with respect to the software documented. It is visible to everyone and covers all product features and examples of how to use them.

4. Using the ForgeRock.org Site

The ForgeRock.org site has links to source code for ForgeRock open source software, as well as links to the ForgeRock forums and technical blogs.

If you are a ForgeRock customer, raise a support ticket instead of using the forums. ForgeRock support professionals will get in touch to help you.

5. Getting Support and Contacting ForgeRock

ForgeRock provides support services, professional services, training through ForgeRock University, and partner services to assist you in setting up and maintaining your deployments. For a general overview of these services, see https://www.forgerock.com.

ForgeRock has staff members around the globe who support our international customers and partners. For details, visit https://www.forgerock.com, or send an email to ForgeRock at info@forgerock.com.

Chapter 1. Administration Interfaces and Tools

This chapter provides a brief introduction to the web-based OpenAM console. It also lists and describes each command-line interface (CLI) administration tool.

1.1. OpenAM Web-Based Console

After you install OpenAM, log in to the web-based console as OpenAM administrator, amadmin with the password you set during installation. Navigate to a URL, such as http://openam.example.com:8080/openam. In this case, communications proceed over the HTTP protocol to a FQDN (openam.example.com), over a standard Java EE web container port number (8080), to a specific deployment URI (/openam).

OpenAM Administration Console

When you log in as the OpenAM administrator, amadmin, you have access to the complete OpenAM console. In addition, OpenAM has set a cookie in your browser that lasts until the session expires, you logout, or you close your browser.^[1]

When you log in to the OpenAM console as a non-administrative end user, you do not have access to the administrative console. Your access is limited to self-service profile pages and user dashboard.

OpenAM Console for Non-Administrative Users

If you configure OpenAM to grant administrative capabilities to another user, then that user is able to access both the administration console in the realms they can administrate, and their self-service profile pages.

OpenAM Console for a Delegated Administrator

For more on delegated administration, see "Delegating Realm Administration Privileges".

1.1.1. OpenAM Console Responsiveness

The OpenAM web-based console is a responsive website, which means it would resize some of its features to fit the size of your screen and the layout design.

For example, the header menu would change into a dropdown menu, and those pages with many tabs would shed most of them for a dropdown menu to the left-hand side.

OpenAM Console Responsiveness

1.1.2. OpenAM Console Search Feature

Use the search box to find any configuration attribute on the section you are in. It can autocomplete the word you are typing, or you can click on the box and display the list of available attributes for you.

OpenAM Console Search Feature

1.2. OpenAM Command-Line Tools

The script tools in the following list have .bat versions for use on Microsoft Windows.

You can install the following OpenAM command-line tools:

agentadmin

This tool lets you manage OpenAM policy agent installations.

Unpack this tool as part of policy agent installation.

ampassword

This tool lets you change OpenAM Administrator passwords, and display encrypted password values.

Install this from the SSOAdminTools-13.5.2.zip.

amverifyarchive

This tool checks log archives for tampering.

Install this from SSOAdminTools-13.5.2.zip.

openam-distribution-configurator-13.5.2.jar

This executable .jar file lets you perform a silent installation of an OpenAM server with a configuration file. For example, the java -jar configurator.jar -f config.file command couples the configurator.jar archive with the config.file. The sampleconfiguration file provided with the tool is set up with the format for the config.file, and it must be adapted for your environment.

Install this from SSOConfiguratorTools-13.5.2.zip.

ssoadm

This tool provides a rich command-line interface for the configuration of OpenAM core services.

In a test environment, you can activate ssoadm.jsp to access the same functionality in your browser. Once active, you can use many features of the ssoadm command by navigating to the ssoadm.jsp URI, in a URL, such as http://openam.example.com:8080/openam/ssoadm.jsp.

Install this from SSOAdminTools-13.5.2.zip.

To translate settings applied in OpenAM console to service attributes for use with ssoadm, log in to the OpenAM console as amadmin and access the services page, in a URL, such as http://openam.example.com:8080/openam/services.jsp.

The commands access the OpenAM configuration over HTTP (or HTTPS). When using the administration commands in a site configuration, the commands access the configuration through the front end load balancer.

Sometimes a command cannot access the load balancer because:

Network routing restrictions prevent the tool from accessing the load balancer.
For testing purposes, the load balancer uses a self-signed certificate for HTTPS, and the tool does not have a way of trusting the self-signed certificate.
The load balancer is temporarily unavailable.

In such cases you can work around the problem by adding an option for each node, such as the following to the java command in the tool's script.

Node 1:

   -D"com.iplanet.am.naming.map.site.to.server=https://lb.example.com:443/openam=
   http://server1.example.com:8080/openam"

Node 2:

   -D"com.iplanet.am.naming.map.site.to.server=https://lb.example.com:443/openam=
   http://server2.example.com:8080/openam"

In the above example the load balancer is on the lb host, https://lb.example.com:443/openam is the site name, and the OpenAM servers in the site are on server1 and server2.

The ssoadm command will only use the latest value in the map, so if you have a mapping like:

   -D"com.iplanet.am.naming.map.site.to.server=https://lb.example.com:443/openam=
   http://server1.example.com:8080/openam, https://lb.example.com:443/openam=
   http://server2.example.com:8080/openam"

The ssoadm command will always talk to:

   http://server2.example.com:8080/openam

1.3. OpenAM ssoadm.jsp

You can use the ssoadm.jsp page to access a large subset of the configuration capabilities of the ssoadm command. Yet, ssoadm.jsp is disabled by default to prevent potential misuse.

To Enable ssoadm.jsp

Log in as OpenAM administrator, amadmin.
Navigate to Deployment > Servers > Server Name > Advanced.
Add a new advanced property called ssoadm.disabled with the value of false.
To see if the change worked, navigate to the URL of OpenAM with the /ssoadm.jsp URI. For example, navigate to http://openam.example.com:8080/openam/ssoadm.jsp.

^[1]Persistent cookies can remain valid when you close your browser. This section reflects OpenAM default behavior before you configure additional functionality.

Chapter 2. Defining Authentication Services

An authentication service confirms the identity of a user or a client application.

This chapter describes how to configure authentication in OpenAM.

2.1. About Authentication in OpenAM

Access management is about controlling access to resources. OpenAM plays a role similar to border control at an international airport. Instead of having each and every airline company deal with access to each destination, all airlines redirects passengers to border control. Redirect control then determines who each passenger is according to passport credentials. Redirect control also checks whether the identified passenger is authorized to fly to the destination corresponding to the ticket, perhaps based on visa credentials. Then, at the departure gate, an agent enforces the authorization from border control, allowing the passenger to board the plane as long as the passenger has not gotten lost, or tried to board the wrong plane, or swapped tickets with someone else. Thus, border control handles access management at the airport.

OpenAM is most frequently used to protect web-accessible resources. Users browse to a protected web application page. An agent installed on the server with the web application redirects the user to OpenAM for access management. OpenAM determines who the user is, and whether the user has the right to access the protected page. OpenAM then redirects the user back to the protected page, with authorization credentials that can be verified by the agent. The agent allows OpenAM authorized users access the page.

Notice that OpenAM basically needs to determine two things for access management: the identity of the user, and whether the user has access rights to the protected page. Authentication is how OpenAM identifies the user. This chapter covers how to set up the authentication process. Authorization is how OpenAM determines whether a user has access to a protected resource. Authorization is covered later.

For authentication, OpenAM uses credentials from the user or client application. It then uses defined mechanisms to validate credentials and complete the authentication. The authentication methods can vary. For example, passengers travelling on international flights authenticate with passports and visas. In contrast, passengers travelling on domestic flights might authenticate with an identity card or a driver's license. Customers withdrawing cash from an ATM authenticate with a card and a PIN.

OpenAM allows you to configure authentication processes and then customize how they are applied. OpenAM uses authentication modules to handle different ways of authenticating. Basically, each authentication module handles one way of obtaining and verifying credentials. You can chain different authentication modules together. In OpenAM, this is called authentication chaining. Each authentication module can be configured to specify the continuation and failure semantics with one of the following four criteria: requisite, sufficient, required, or optional.

Authentication modules in a chain can assign a pass or fail flag to the authorization request. To successfully complete an authentication chain at least one pass flag must have been achieved, and there must be no fail flags.

Flags are assigned when completing a module as shown in the table below:

Authentication Criteria, Flags, and Continuation Semantics

Criteria	Fail	Pass	Example
Requisite	Assigns fail flag. Exits chain.	Assigns pass flag. Continues chain.	Active Directory, Data Store, and LDAP authentication modules are often set as requisite because of a subsequent requirement in the chain to identify the user. For example, the Device ID (Match) authentication module needs a user's ID before it can retrieve information about the user's devices.
Sufficient	Assigns no flag. Continues chain.	Assigns pass flag. Exits chain.	You could set Windows Desktop SSO as sufficient, so authenticated Windows users are let through, whereas web users must traverse another authentication module, such as one requiring a username and password. One exception is that if you pass a sufficient module after having failed a required module, you will continue through the chain and will not exit at that point. Consider using a requisite module instead of a required module in this situation.
Required	Assigns fail flag. Continues chain.	Assigns pass flag. Continues chain.	You could use a required module for login with email and password, so that it can fail through to another module to handle new users who have not yet signed up.
Optional	Assigns no flag. Continues chain.	Assigns pass flag. Continues chain.	You could use an optional module to assign a higher authentication level if it passes. Consider a chain with a requisite Data Store module and an optional Certificate module. Users who only passed the Data Store module could be assigned a lower authentication level than users who passed both the Data Store and Certificate modules. The users with the higher authentication level could be granted access to more highly-secured resources.

Tip

In authentication chains with a single module, requisite and required are equivalent. For authentication chains with multiple modules, use required only when you want the authentication chain to continue evaluating modules even after the required criterion fails.

The OpenAM authentication chain editor displays the flags that could be assigned by each module in the chain, and whether execution of the chain continues downwards through the chain or exits out, as shown below:

Authentication Chain with Each Criteria

With OpenAM, you can further set authentication levels per module, with higher levels being used typically to allow access to more restricted resources. The OpenAM SPIs also let you develop your own authentication modules, and post authentication plugins. Client applications can specify the authentication level, module, user, and authentication service to use among those you have configured. As described later in this guide, you can use realms to organize which authentication process applies for different applications or different domains, perhaps managed by different people.

OpenAM leaves the authentication process flexible so that you can adapt how it works to your situation. Although at first the number of choices can seem daunting, now that you understand the basic process, you begin to see how choosing authentication modules and arranging them in authentication chains lets you use OpenAM to protect access to a wide range of applications used in your organization.

2.2. About Authentication Levels

When a user successfully authenticates, OpenAM creates a session, which allows OpenAM to manage the user's access to resources. The session is assigned an authentication level, which is calculated to be the highest authentication level of any authentication module that passed. If the user's session does not have the appropriate authentication level, then the user may need to re-authenticate again at a higher authentication level to access the requested resource.

If an authentication chain contains requisite or required modules that were not executed due to the presence of a passing sufficient module in front of them, the session's authentication level is calculated to be whichever is greater: the highest authentication level of any authentication module that passed, or the highest authentication level of requisite or required modules that were not executed.

You can modify OpenAM's default behavior, so that a session's authentication level is always the highest authentication level of any authentication module that passed, even if there are requisite or required modules in the authentication chain that were not executed.

To modify the default behavior, set the org.forgerock.openam.authLevel.excludeRequiredOrRequisite property to true under Deployment > Servers > Server Name > Advanced and restart the OpenAM server.

In some deployments, you need to limit how many active sessions a user can have at a given time. For example, you might want to prevent a user from using more than two devices at once. See "Configuring Session Quotas" for instructions.

2.4. Configuring Core Authentication Attributes

Use core authentication attributes to configure:

The list of available authentication modules
Which types of clients can authenticate with which modules
Connection pools for access to directory servers
Whether to retain objects used during authentication so they can be used at logout
Defaults for configuring authentication in a particular realm

To configure core authentication attributes in the OpenAM console, navigate to Configure > Authentication, and then click Core Attributes.

The Core Authentication Attributes Page

The core authentication attributes page is divided into seven tabs, which are explained in the following sections:

"Core Authentication Attributes - Global"
"Core Authentication Attributes - Core"
"Core Authentication Attributes - User Profile"
"Core Authentication Attributes - Account Lockout"
"Core Authentication Attributes - General"
"Core Authentication Attributes - Security"
"Core Authentication Attributes - Post Authentication Processing"

ssoadm service name: iPlanetAMAuthService

2.4.1. Core Authentication Attributes - Global

The Global tab includes attributes for the list of available modules, LDAP connection settings, authentication process options, and an option to disable the XUI and make the classic UI the default end user interface. The global attributes are defined in "Authentication Configuration" in the Reference.

2.4.2. Core Authentication Attributes - Core

Administrator Authentication Configuration: Specifies the default authentication chain used when an administrative user, such as amAdmin, logs in to the OpenAM console.
Organization Authentication Configuration: Specifies the default authentication chain used when a non-administrative user logs in to OpenAM.

2.4.3. Core Authentication Attributes - User Profile

User Profile

Specifies whether a user profile needs to exist in the user data store, or should be created on successful authentication.

Dynamic: Specifies that on successful authentication, OpenAM creates a user profile if one does not already exist. OpenAM then issues the SSO token. OpenAM creates the user profile in the user data store configured for the realm.
Dynamic with User Alias: Specifies that on successful authentication, OpenAM creates a user profile that contains the User Alias List attribute, which defines one or more aliases for mapping a user's multiple profiles.
Ignored: Specifies that a user profile is not required for OpenAM to issue an SSO token after a successful authentication.
Required: Specifies that on successful authentication, the user must have a user profile in the user data store configured for the realm in order for OpenAM to issue an SSO token.

ssoadm attribute: iplanet-am-auth-dynamic-profile-creation. Set this attribute's value to one of the following:

true for Dynamic
createAlias for Dynamic With User Alias
ignore for Ignored
false for Required

User Profile Dynamic Creation Default Roles

Specifies the distinguished name (DN) of a role to be assigned to a new user whose profile is created when either the true or createAlias options are selected under the User Profile property. There are no default values. The role specified must be within the realm for which the authentication process is configured.

This role can be either an OpenAM or Sun DSEE role, but it cannot be a filtered role. If you wish to automatically assign specific services to the user, you have to configure the Required Services property in the user profile.

This functionality is deprecated.

ssoadm attribute: iplanet-am-auth-default-role

Alias Search Attribute Name

After a user is successfully authenticated, the user's profile is retrieved. OpenAM first searches for the user based on the data store settings. If that fails to find the user, OpenAM will use the attributes listed here to look up the user profile. This setting accepts any data store specific attribute name.

ssoadm attribute: iplanet-am-auth-alias-attr-name

Note

If the Alias Search Attribute Name property is empty, OpenAM uses the iplanet-am-auth-user-naming-attr property from the iPlanetAmAuthService. The iplanet-am-auth-user-naming-attr property is only configurable through the ssoadm command-line tool and not through the OpenAM console.

$ ssoadm get-realm-svc-attrs \
--adminid amadmin \
--password-file PATH_TO_PWDFILE \
--realm REALM \
--servicename iPlanetAMAuthService

$ ssoadm set-realm-svc-attrs \
--adminid amadmin \
--password-file PATH_TO_PWDFILE \
--realm REALM \
--servicename iPlanetAMAuthService \
--attributevalues iplanet-am-auth-user-naming-attr=SEARCH_ATTRIBUTE

2.4.4. Core Authentication Attributes - Account Lockout

Login Failure Lockout Mode

Selecting this attribute enables a physical lockout. Physical lockout inactivates an LDAP attribute (defined in the Lockout Attribute Name property) in the user's profile. This attribute works in conjunction with the other account lockout and notification attributes.

ssoadm attribute: iplanet-am-auth-login-failure-lockout-mode

Login Failure Lockout Count

Defines the number of attempts that a user has to authenticate within the time interval defined in Login Failure Lockout Interval before being locked out.

ssoadm attribute: iplanet-am-auth-login-failure-count

Login Failure Lockout Interval

Defines the time in minutes during which failed login attempts are counted. If one failed login attempt is followed by a second failed attempt within this defined lockout interval time, the lockout count starts, and the user is locked out if the number of attempts reaches the number defined by the Login Failure Lockout Count property. If an attempt within the defined lockout interval time proves successful before the number of attempts reaches the number defined by the Login Failure Lockout Count property, the lockout count is reset.

ssoadm attribute: iplanet-am-auth-login-failure-duration

Email Address to Send Lockout Notification

Specify one or more email addresses to which notification is sent if a user lockout occurs.

Separate multiple addresses with spaces, and append |locale|charset to addresses for recipients in non-English locales.

ssoadm attribute: iplanet-am-auth-lockout-email-address

Warn User After N Failures

Specifies the number of authentication failures after which OpenAM displays a warning message that the user will be locked out.

ssoadm attribute: iplanet-am-auth-lockout-warn-user

Login Failure Lockout Duration

Defines how many minutes a user must wait after a lockout before attempting to authenticate again. Entering a value greater than 0 enables memory lockout and disables physical lockout. Memory lockout means the user's account is locked in memory for the number of minutes specified. The account is unlocked after the time period has passed.

ssoadm attribute: iplanet-am-auth-lockout-duration

Lockout Duration Multiplier

Defines a value with which to multiply the value of the Login Failure Lockout Duration attribute for each successive lockout. For example, if Login Failure Lockout Duration is set to 3 minutes, and the Lockout Duration Multiplier is set to 2, the user is locked out of the account for 6 minutes. After the 6 minutes has elapsed, if the user again provides the wrong credentials, the lockout duration is then 12 minutes. With the Lockout Duration Multiplier, the lockout duration is incrementally increased based on the number of times the user has been locked out.

ssoadm attribute: sunLockoutDurationMultiplier

Lockout Attribute Name

Defines the LDAP attribute used for physical lockout. The default attribute is inetuserstatus, although the field in the OpenAM console is empty. The Lockout Attribute Value field must also contain an appropriate value.

ssoadm attribute: iplanet-am-auth-lockout-attribute-name

Lockout Attribute Value

Specifies the action to take on the attribute defined in Lockout Attribute Name. The default value is inactive, although the field in the OpenAM console is empty. The Lockout Attribute Name field must also contain an appropriate value.

ssoadm attribute: iplanet-am-auth-lockout-attribute-value

Invalid Attempts Data Attribute Name

Specifies the LDAP attribute used to hold the number of failed authentication attempts towards Login Failure Lockout Count.

ssoadm attribute: sunAMAuthInvalidAttemptsDataAttrName

Store Invalid Attempts in Data Store

Enables the storage of information regarding failed authentication attempts as the value of the Invalid Attempts Data Attribute Name in the user data store. Information stored includes number of invalid attempts, time of last failed attempt, lockout time and lockout duration. Storing this information in the identity repository allows it to be shared among multiple instances of OpenAM.

ssoadm attribute: sunStoreInvalidAttemptsInDS

2.4.5. Core Authentication Attributes - General

Default Authentication Locale

Specifies the default language subtype to be used by the Authentication Service. The default value is en_US.

ssoadm attribute: iplanet-am-auth-locale

Identity Types

Lists the type or types of identities used during a profile lookup. You can choose more than one to search on multiple types if you would like OpenAM to conduct a second lookup if the first lookup fails. Default: Agent and User

Agent: Searches for identities under your agents.
agentgroup: Searches for identities according to your established agent group.
agentonly: Searches for identities only under your agents.
Group: Searches for identities according to your established groups.
User: Searches for identities according to your users.

ssoadm attribute: sunAMIdentityType

Pluggable User Status Event Classes

Specifies one or more Java classes used to provide a callback mechanism for user status changes during the authentication process. The Java class must implement the com.sun.identity.authentication.spi.AMAuthCallBack interface. OpenAM supports account lockout and password changes. OpenAM supports password changes through the LDAP authentication module, and so the feature is only available for the LDAP module.

A .jar file containing the user status event class belongs in the WEB-INF/lib directory of the deployed OpenAM instance. If you do not build a .jar file, add the class files under WEB-INF/classes.

ssoadm attribute: sunAMUserStatusCallbackPlugins

Default Authentication Level

Specifies the default authentication level for authentication modules.

ssoadm attribute: iplanet-am-auth-default-auth-level

Use Stateless Sessions

When selected, specifies that OpenAM users authenticating to this realm are assigned stateless sessions. Otherwise, OpenAM users authenticating to this realm are assigned stateful sessions.

For more information about session state, see "Configuring Session State".

ssoadm attribute: openam-auth-stateless-sessions

Two Factor Authentication Mandatory

When selected, specifies that users authenticating to a chain that includes a ForgeRock Authenticator (OATH) module will always be required to perform authentication using a registered device before they can access OpenAM. When not selected, users can opt to forego registering a device and providing a token and still successfully authenticate.

Letting users choose not to provide a verification token while authenticating carries implications beyond the required, optional, requisite, or sufficient flag settings on the ForgeRock Authenticator (OATH) module in the authentication chain. For example, suppose you configured authentication as follows:

The ForgeRock Authenticator (OATH) module is in an authentication chain.
The ForgeRock Authenticator (OATH) module has the required flag set.
Two Factor Authentication Mandatory is not selected.

Users authenticating to the chain can authenticate successfully without providing tokens from their devices. The reason for successful authentication in this case is that the required setting relates to the execution of the ForgeRock Authenticator (OATH) module itself. Internally, the ForgeRock Authenticator (OATH) module has the ability to forego processing a token while still returning a passing status to the authentication chain.

ssoadm attribute: forgerockTwoFactorAuthMandatory

2.4.6. Core Authentication Attributes - Security

Module Based Authentication

Enables users to authenticate using module-based authentication. Otherwise, all attempts at authentication using the module=module-name login parameter result in failure.

ForgeRock recommends disabling module-based authentication in production environments.

ssoadm attribute: sunEnableModuleBasedAuth

Persistent Cookie Encryption Certificate Alias

Specifies the keystore alias for encrypting persistent cookies.

Default: test

ssoadm attribute: iplanet-am-auth-key-alias

Zero Page Login

If enabled, allow users to authenticate using only GET request parameters without showing a login screen.

Caution

Enable this with caution as browsers can cache credentials and servers can log credentials when they are part of the URL.

OpenAM always allows HTTP POST requests for zero page login.

Default: false (disabled)

ssoadm attribute: openam.auth.zero.page.login.enabled

Zero Page Login Referer Whitelist

List of HTTP referer URLs for which OpenAM allows zero page login. These URLs are supplied in the Referer HTTP request header, allowing clients to specify the web page that provided the link to the requested resource.

If you enable zero page login, include the URLs here for the pages from which to allow zero page login, or leave this list blank to allow zero page login from any Referer.

This setting applies for both HTTP GET and also HTTP POST requests for zero page login.

ssoadm attribute: openam.auth.zero.page.login.referer.whitelist

Zero Page Login Allowed Without Referer?

If enabled and zero page login is enabled, allow zero page login for requests without an HTTP Referer request header.

Default: true (enabled)

ssoadm attribute: openam.auth.zero.page.login.allow.null.referer

Organization Authentication Signing Secret

Specifies an HMAC shared secret for signing a RESTful authentication request. When users attempt to authenticate to the XUI, OpenAM signs a JSON Web Token (JWT) with this shared secret. The JWT contains the authentication session ID, realm, and authentication index type value, but does not contain the user's credentials.

Default: An automatically generated key

ssoadm attribute: iplanet-am-auth-hmac-signing-shared-secret

2.4.7. Core Authentication Attributes - Post Authentication Processing

Default Success Login URL

Accepts a list of values that specifies where users are directed after successful authentication. The format of this attribute is client-type|URL although the only value you can specify at this time is a URL which assumes the type HTML. The default value is /openam/console. Values that do not specify HTTP have that appended to the deployment URI.

ssoadm attribute: iplanet-am-auth-login-success-url

Default Failure Login URL

Accepts a list of values that specifies where users are directed after authentication has failed. The format of this attribute is client-type|URL although the only value you can specify at this time is a URL which assumes the type HTML. Values that do not specify HTTP have that appended to the deployment URI.

ssoadm attribute: iplanet-am-auth-login-failure-url

Authentication Post Processing Classes

Specifies one or more Java classes used to customize post authentication processes for successful or unsuccessful logins. The Java class must implement the com.sun.identity.authentication.spi.AMPostAuthProcessInterface OpenAM interface.

A .jar file containing the post processing class belongs in the WEB-INF/lib directory of the deployed OpenAM instance. If you do not build a .jar file, add the class files under WEB-INF/classes. For deployment, add the .jar file or classes into a custom OpenAM .war file.

For information on creating post-authentication plugins, see "Creating a Post Authentication Plugin" in the Developer's Guide.

ssoadm attribute: iplanet-am-auth-post-login-process-class

Generate UserID Mode

When enabled, the Membership module generates a list of alternate user identifiers if the one entered by a user during the self-registration process is not valid or already exists. The user IDs are generated by the class specified in the Pluggable User Name Generator Class property.

ssoadm attribute: iplanet-am-auth-username-generator-enabled

Pluggable User Name Generator Class

Specifies the name of the class used to generate alternate user identifiers when Generate UserID Mode is enabled. The default value is com.sun.identity.authentication.spi.DefaultUserIDGenerator.

ssoadm attribute: iplanet-am-auth-username-generator-class

User Attribute Mapping to Session Attribute

Enables the authenticating user's identity attributes (stored in the identity repository) to be set as session properties in the user's SSO token. The value takes the format User-Profile-Attribute|Session-Attribute-Name. If Session-Attribute-Name is not specified, the value of User-Profile-Attribute is used. All session attributes contain the am.protected prefix to ensure that they cannot be edited by the Client SDK.

For example, if you define the user profile attribute as mail and the user's email address, available in the user session, as user.mail, the entry for this attribute would be mail|user.mail. After a successful authentication, the SSOToken.getProperty(String) method is used to retrieve the user profile attribute set in the session. The user's email address is retrieved from the user's session using the SSOToken.getProperty("am.protected.user.mail") method call.

Properties that are set in the user session using User Attribute Mapping to Session Attributes cannot be modified (for example, SSOToken.setProperty(String, String)). This results in an SSOException. Multivalued attributes, such as memberOf, are listed as a single session variable with a | separator.

When configuring authentication for a realm that uses stateless sessions, be careful not to add so many session attributes that the session cookie size exceeds the maximum allowable cookie size. For more information about stateless session cookies, see "Session Cookies".

ssoadm attribute: sunAMUserAttributesSessionMapping

2.5. Configuring Authentication Modules

The OpenAM console provides two places where the OpenAM administrator can configure authentication modules:

Under Configure > Authentication, you configure default properties for global authentication modules.
Under Realms > Realm Name > Authentication > Modules, you configure modules for your realm.

The configuration of individual modules depend on its function. The configuration of an Active Directory over LDAP user authentication module requires connection information and details about where to search for users. In contrast, the configuration of the HOTP module for OTP authentication requires data about the password length and the mail server or SMS gateway for to send the password during authentication.

2.5.1. Hints for the Active Directory Authentication Module

OpenAM connects to Active Directory over Lightweight Directory Access Protocol (LDAP). OpenAM provides separate Active Directory and LDAP modules to support the use of both Active Directory and another directory service in an authentication chain.

ssoadm service name: sunAMAuthADService

Primary Active Directory Server, Secondary Active Directory Server

The default port for LDAP is 389. If you are connecting to Active Directory over SSL, the default port for LDAP/SSL is 636.

To allow users to change passwords through OpenAM, Active Directory requires that you connect over SSL.

If you want to use SSL or TLS for security, then scroll down to enable SSL/TLS Access to Active Directory Server. Make sure that OpenAM can trust the Active Directory certificate when using this option.

OpenAM first attempts to contact primary servers. If no primary server is available, then OpenAM attempts to contact secondaries.

When authenticating users from a directory server that is remote to OpenAM, set the primary server values, and optionally the secondary server values. Primary servers have priority over secondary servers.

ssoadm attributes are: primary is iplanet-am-auth-ldap-server; secondary is iplanet-am-auth-ldap-server2.

Both properties take more than one value; thus, allowing more than one primary or secondary remote server, respectively. Assuming a multi-data center environment, OpenAM determines priority within the primary and secondary remote servers, respectively, as follows:

Every LDAP server that is mapped to the current OpenAM instance has highest priority.
For example, if you are connected to openam1.example.com and ldap1.example.com is mapped to that OpenAM instance, then OpenAM uses ldap1.example.com.
Every LDAP server that was not specifically mapped to a given OpenAM instance has the next highest priority.
For example, if you have another LDAP server, ldap2.example.com, that is not connected to a specific OpenAM server and if ldap1.example.com is unavailable, OpenAM connects to the next highest priority LDAP server, ldap2.example.com.
LDAP servers that are mapped to different OpenAM instances have the lowest priority.
For example, if ldap3.example.com is connected to openam3.example.com and ldap1.example.com and ldap2.example.com are unavailable, then openam1.example.com connects to ldap3.example.com.

DN to Start User Search

LDAP data is organized hierarchically, a bit like a file system on Windows or UNIX. More specific DNs likely result in better performance. When configuring the module for a particular part of the organization, you can perhaps start searches from a specific organizational unit, such as OU=sales,DC=example,DC=com.

If multiple entries exist with identical search attribute values, make this value specific enough to return only one entry.

ssoadm attribute: iplanet-am-auth-ldap-base-dn

Bind User DN, Bind User Password

If OpenAM stores attributes in Active Directory, for example to manage account lockout, or if Active Directory requires that OpenAM authenticate in order to read users' attributes, then OpenAM needs the DN and password to authenticate to Active Directory.

The default is amldapuser. If the administrator authentication chain (default: ldapService) has been configured to include only the Active Directory module, then make sure that the password is correct before you logout. If it is incorrect, you will be locked out. If you do get locked out, you can login with the superuser DN, which by default is uid=amAdmin,ou=People,OpenAM-deploy-base, where OpenAM-deploy-base was set during OpenAM configuration.

ssoadm attributes: iplanet-am-auth-ldap-bind-dn and iplanet-am-auth-ldap-bind-passwd

Attribute Used to Retrieve User Profile, Attributes Used to Search for a User to be Authenticated, User Search Filter, Search Scope

LDAP searches for user entries with attribute values matching the filter you provide. For example, if you search under CN=Users,DC=example,DC=com with a filter "(MAIL=bjensen@example.com)", then the directory returns the entry that has MAIL=bjensen@example.com. In this example the attribute used to search for a user is mail. Multiple attribute values mean the user can authenticate with any one of the values. For example, if you have both uid and mail, then Barbara Jensen can authenticate with either bjensen or bjensen@example.com.

The User Search Filter text box provides a more complex filter. For example, if you search on mail and add User Search Filter (objectClass=inetOrgPerson), then OpenAM uses the resulting search filter (&(mail=address) (objectClass=inetOrgPerson)), where address is the mail address provided by the user.

This controls how and the level of the directory that will be searched. You can set the search to run at a high level or against a specific area:

OBJECT will search only for the entry specified as the DN to Start User Search.
ONELEVEL will search only the entries that are directly children of that object.
SUBTREE will search the entry specified and every entry under it.

ssoadm attributes: iplanet-am-auth-ldap-user-naming-attribute, iplanet-am-auth-ldap-user-search-attributes, iplanet-am-auth-ldap-search-filter, and iplanet-am-auth-ldap-search-scope

LDAP Connection Mode

If you want to initiate secure communications to data stores using SSL or StartTLS, OpenAM must be able to trust Active Directory certificates, either because the Active Directory certificates were signed by a CA whose certificate is already included in the trust store used by the container where OpenAM runs, or because you imported the certificates into the trust store.

ssoadm attribute: openam-auth-ldap-connection-mode

Possible values: LDAP, LDAPS, and StartTLS

Return User DN to DataStore

When enabled, and OpenAM uses Active Directory as the user store, the module returns the DN rather than the User ID, so the bind for authentication can be completed without a search to retrieve the DN.

ssoadm attribute: iplanet-am-auth-ldap-return-user-dn

User Creation Attributes

This list lets you map (external) attribute names from Active Directory to (internal) attribute names used by OpenAM.

ssoadm attribute: iplanet-am-ldap-user-creation-attr-list

Trust All Server Certificates

When enabled, blindly trust server certificates, including self-signed test certificates.

ssoadm attribute: iplanet-am-auth-ldap-ssl-trust-all

LDAP Connection Heartbeat Interval

Specifies how often OpenAM should send a heartbeat request to the directory server to ensure that the connection does not remain idle. Some network administrators configure firewalls and load balancers to drop connections that are idle for too long. You can turn this off by setting the value to 0 or to a negative number. To set the units for the interval, use LDAP Connection Heartbeat Time Unit.

Default: 1

ssoadm attribute: openam-auth-ldap-heartbeat-interval

LDAP Connection Heartbeat Time Unit

Specifies the time unit corresponding to LDAP Connection Heartbeat Interval.

Default: minute

ssoadm attribute: openam-auth-ldap-heartbeat-timeunit

LDAP operations timeout

Defines the timeout in milliseconds that OpenAM should wait for a response from the directory server.

Default: 0 (means no timeout)

ssoadm attribute: openam-auth-ldap-operation-timeout

Authentication Level

Sets the authentication level used to indicate the level of security associated with the module. The value can range from 0 to any positive integer.

ssoadm attribute: sunAMAuthADAuthLevel

LDAPS Server Protocol Version

Defines which protocol version is used to establish the secure connection to the LDAP Directory Server.

Default: TLSv1

ssoadm attribute: openam-auth-ldap-secure-protocol-version

Possible values: TLSv1, TLSv1.1, TLSv1.2

2.5.2. Hints for the Adaptive Risk Authentication Module

The Adaptive Risk module is designed to assess risk during authentication so that OpenAM can determine whether to require the user to complete further authentication steps. After configuring the Adaptive Risk module, insert it in your authentication chain with criteria set to Sufficient as shown in the following example:

Adaptive Risk Module in an Authentication Chain

In the example authentication chain shown, OpenAM has users authenticate first using the LDAP module providing a user ID and password combination. Upon success, OpenAM calls the Adaptive Risk module. The Adaptive Risk module assesses the risk based on your configured parameters. If the Adaptive Risk module calculates a total score below the threshold you set, the module returns success, and OpenAM finishes authentication processing without requiring further credentials.

Otherwise, the Adaptive Risk module evaluates the score to be above the risk threshold, and returns failure. OpenAM then calls the HOTP module, requiring the user to authenticate with a one-time password delivered to her by email or by SMS to her mobile phone.

When you configure the Adaptive Risk module to save cookies and profile attributes after successful authentication, OpenAM performs the save as post-authentication processing, only after the entire authentication chain returns success. You must set up OpenAM to save the data as part of post-authentication processing by editing the authentication chain to add org.forgerock.openam.authentication.modules.adaptive.Adaptive to the list of post-authentication plugins.

When the Adaptive Risk module relies on the client IP address, and OpenAM lies behind a load balancer or proxy layer, configure the load balancer or proxy to send the address by using the X-Forwarded-For header, and configure OpenAM to consume and forward the header as necessary. For details, see "Handling HTTP Request Headers" in the Installation Guide.

ssoadm service name: sunAMAuthAdaptiveService

Tip

If you cannot find the attribute you are looking for, click on the dropdown button on the left-hand side of the tabs or use the Search box. For more information, see " OpenAM Console Responsiveness" and "OpenAM Console Search Feature".

General

Authentication Level

Sets the authentication level used to indicate the level of security associated with the module. The value can range from 0 to any positive integer.

ssoadm attribute: openam-auth-adaptive-auth-level

Risk Threshold

Risk threshold score. If the sum of the scores is greater than the threshold, the Adaptive Risk module returns failure.

Default: 1

ssoadm attribute: openam-auth-adaptive-auth-threshold

Failed Authentications

Failed Authentication Check

When enabled, check the user profile for authentication failures since the last successful login. This check therefore requires OpenAM to have access to the user profile, and Account Lockout to be enabled (otherwise, OpenAM does not record authentication failures).

ssoadm attribute: openam-auth-adaptive-failure-check

Score

Value to add to the total score if the user fails the Failed Authentication Check. Default: 1

ssoadm attribute: openam-auth-adaptive-failure-score

Invert Result

When selected, add the score to the total score if the user passes the Failed Authentication Check.

ssoadm attribute: openam-auth-adaptive-failure-invert

IP Address Range

IP Range Check

When enabled, check whether the client IP address is within one of the specified IP Ranges.

ssoadm attribute: openam-auth-adaptive-ip-range-check

IP Range

For IPv4, specifies a list of IP ranges either in CIDR-style notation (x.x.x.x/YY) or as a range from one address to another (x.x.x.x-y.y.y.y, meaning from x.x.x.x to y.y.y.y).

For IPv6, specifies a list of IP ranges either in CIDR-style notation (X:X:X:X:X:X:X:X/YY) or as a range from one address to another (X:X:X:X:X:X:X:X-Y:Y:Y:Y:Y:Y:Y:Y, meaning from X:X:X:X:X:X:X:X to Y:Y:Y:Y:Y:Y:Y:Y).

ssoadm attribute: openam-auth-adaptive-ip-range-range

Score

Value to add to the total score if the user fails the IP Range Check.

Default: 1

ssoadm attribute: openam-auth-adaptive-ip-range-score

Invert Result

When selected, add the Score to the total score if the user passes the IP Range Check.

ssoadm attribute: openam-auth-adaptive-ip-range-invert

IP Address History

IP History Check

When enabled, check whether the client IP address matches one of the known values stored on the profile attribute you specify. This check therefore requires that OpenAM have access to the user profile.

ssoadm attribute: openam-auth-adaptive-ip-history-check

History size

Specifies how many IP address values to retain on the profile attribute you specify.

Default: 5

ssoadm attribute: openam-auth-ip-adaptive-history-count

Profile Attribute Name

Name of the user profile attribute on which to store known IP addresses. Ensure the specified attribute exists in your user data store; the iphistory attribute does not exist by default, and it is not created when performing OpenAM schema updates.

Default: iphistory

ssoadm attribute: openam-auth-adaptive-ip-history-attribute

Save Successful IP Address

When enabled, save new client IP addresses to the known IP address list following successful authentication.

ssoadm attribute: openam-auth-adaptive-ip-history-save

Score

Value to add to the total score if the user fails the IP History Check.

Default: 1

ssoadm attribute: openam-auth-adaptive-ip-history-score

Invert Result

When selected, add the Score to the total score if the user passes the IP History Check.

ssoadm attribute: openam-auth-adaptive-ip-history-invert

Known Cookie

Cookie Value Check

When enabled, check whether the client browser request has the specified cookie and optional cookie value.

ssoadm attribute: openam-auth-adaptive-known-cookie-check

Cookie Name

Specifies the name of the cookie for which OpenAM checks when you enable the Cookie Value Check.

ssoadm attribute: openam-auth-adaptive-known-cookie-name

Cookie Value

Specifies the value of the cookie for which OpenAM checks. If no value is specified, OpenAM does not check the cookie value.

ssoadm attribute: openam-auth-adaptive-known-cookie-value

Save Cookie Value on Successful Login

When enabled, save the cookie as specified in the client's browser following successful authentication. If no Cookie Value is specified, the value is set to 1.

ssoadm attribute: openam-auth-adaptive-known-cookie-save

Score

Value to add to the total score if user passes the Cookie Value Check.

Default: 1

ssoadm attribute: openam-auth-adaptive-known-cookie-score

Invert Result

When selected, add the Score to the total score if the user passes the Cookie Value Check.

ssoadm attribute: openam-auth-adaptive-known-cookie-invert

Device Cookie

Device Registration Cookie Check

When enabled, check whether the client browser request has the specified cookie with the correct device registration identifier as the value.

ssoadm attribute: openam-auth-adaptive-device-cookie-check

Cookie Name

Specifies the name of the cookie for the Device Registration Cookie Check.

Default: Device

ssoadm attribute: openam-auth-adaptive-device-cookie-name

Save Device Registration on Successful Login

When enabled, save the specified cookie with a hashed device identifier value in the client's browser following successful authentication.

ssoadm attribute: openam-auth-adaptive-device-cookie-save

Score

Value to add to the total score if the user fails the Device Registration Cookie Check.

Default: 1

ssoadm attribute: openam-auth-adaptive-device-cookie-score

Invert Result

When selected, add the Score to the total score if the user passes the Device Registration Cookie Check.

ssoadm attribute: openam-auth-adaptive-device-cookie-invert

Time Since Last Login

Time since Last login Check

When enabled, check whether the client browser request has the specified cookie that holds the encrypted last login time, and check that the last login time is more recent than a maximum number of days you specify.

ssoadm attribute: openam-auth-adaptive-time-since-last-login-check

Cookie Name

Specifies the name of the cookie holding the encrypted last login time value.

ssoadm attribute: openam-auth-adaptive-time-since-last-login-cookie-name

Max Time since Last login

Specifies a threshold age of the last login time in days. If the client's last login time is more recent than the number of days specified, then the client successfully passes the check.

ssoadm attribute: openam-auth-adaptive-time-since-last-login-value

Save time of Successful Login

When enabled, save the specified cookie with the current time encrypted as the last login value in the client's browser following successful authentication.

ssoadm attribute: openam-auth-adaptive-time-since-last-login-save

Score

Value to add to the total score if the user fails the Time Since Last Login Check.

Default: 1

ssoadm attribute: openam-auth-adaptive-time-since-last-login-score

Invert Result

When selected, add the Score to the total score if the user passes the Time Since Last Login Check.

ssoadm attribute: openam-auth-adaptive-time-since-last-login-invert

Profile Attribute

Profile Risk Attribute check

When enabled, check whether the user profile contains the specified attribute and value.

ssoadm attribute: openam-auth-adaptive-risk-attribute-check

Attribute Name

Specifies the attribute to check on the user profile for the specified value.

ssoadm attribute: openam-auth-adaptive-risk-attribute-name

Attribute Value

Specifies the value to match on the profile attribute. If the attribute is multi-valued, a single match is sufficient to pass the check.

ssoadm attribute: openam-auth-adaptive-risk-attribute-value

Score

Value to add to the total score if the user fails the Profile Risk Attribute Check.

Default: 1

ssoadm attribute: openam-auth-adaptive-risk-attribute-score

Invert Result

When selected, add the Score to the total score if the user passes the Profile Risk Attribute Check.

ssoadm attribute: openam-auth-adaptive-risk-attribute-invert

Geo Location

Geolocation Country Code Check

When enabled, check whether the client IP address location matches a country specified in the Valid Country Codes list.

ssoadm attribute: forgerock-am-auth-adaptive-geo-location-check

Geolocation Database Location

Path to GeoIP data file used to convert IP addresses to country locations. The geolocation database is not packaged with OpenAM. You can download the GeoIP Country database from MaxMind. Use the binary .mmdb file format, rather than .csv. You can use the GeoLite Country database for testing.

ssoadm attribute: openam-auth-adaptive-geo-location-database

Valid Country Codes

Specifies the list of country codes to match. Use | to separate multiple values.

ssoadm attribute: openam-auth-adaptive-geo-location-values.

Score

Value to add to the total score if the user fails the Geolocation Country Code Check.

Default: 1

ssoadm attribute: openam-auth-adaptive-geo-location-score

Invert Result

When selected, add the Score to the total score if the user passes the Geolocation Country Code Check.

ssoadm attribute: openam-auth-adaptive-geo-location-invert

Request Header

Request Header Check

When enabled, check whether the client browser request has the specified header with the correct value.

ssoadm attribute: openam-auth-adaptive-req-header-check

Request Header Name

Specifies the name of the request header for the Request Header Check.

ssoadm attribute: openam-auth-adaptive-req-header-name

Request Header Value

Specifies the value of the request header for the Request Header Check.

ssoadm attribute: openam-auth-adaptive-req-header-value

Score

Value to add to the total score if the user fails the Request Header Check.

Default: 1

ssoadm attribute: openam-auth-adaptive-req-header-score

Invert Result

When selected, add the Score to the total score if the user passes the Request Header Check.

ssoadm attribute: openam-auth-adaptive-req-header-invert

2.5.3. Hints for the Anonymous Authentication Module

This module lets you configure and track anonymous users, who can log in to your application or web site without login credentials. Typically, you would provide such users with very limited access, for example, an anonymous user may have access to public downloads on your site. When the user attempts to access resources that require more protection, the module can force further authentication for those resources.

You can configure the Anonymous authentication module by specifying the ssoadm service name and Anonymous Authentication realm attributes: Valid Anonymous Users, Default User Name, Case Sensitive User IDs, and Authentication Level.

ssoadm service name: iPlanetAMAuthAnonymousService

Valid Anonymous Users

Specifies the list of valid anonymous user IDs that can log in without submitting a password.

ssoadm attribute: iplanet-am-auth-anonymous-users-list

When user accesses the default module instance login URL, then the module prompts the user to enter a valid anonymous user name.

The default module instance login URL is defined as follows:

protocol://hostname:port/deploy_URI/XUI/#login?module=Anonymous&org=org_name

Default Anonymous User Name

Specifies the user ID assigned by the module if the Valid Anonymous Users list is empty. The default value is anonymous. Note that the anonymous user must be defined in the realm.

ssoadm attribute: iplanet-am-auth-anonymous-default-user-name

Case Sensitive User IDs

Determines whether case matters for anonymous user IDs.

ssoadm attribute: iplanet-am-auth-anonymous-case-sensitive

Authentication Level

Sets the authentication level used to indicate the level of security associated with the module. The value can range from 0 (default) to any positive integer and is set for each authentication method. The higher number corresponds to a higher level of authentication. If you configured your authentication levels from a 0 to 5 scale, then an authentication level of 5 will require the highest level of authentication.

After a user has authenticated, OpenAM stores the authentication level in the session token. When the user attempts to access a protected resource, the token is presented to the application. The application uses the token's value to determine if the user has the correct authentication level required to access the resource. If the user does not have the required authentication level, the application can prompt the user to authenticate with a higher authentication level.

ssoadm attribute: iplanet-am-auth-anonymous-auth-level

Note

You can configure the Anonymous Authentication module using the OpenAM console by clicking Configure > Authentication > Anonymous.

2.5.4. Hints for the Certificate Authentication Module

X.509 digital certificates can enable secure authentication without the need for user names and passwords or other credentials. Certificate authentication can be handy to manage authentication by applications. If all certificates are signed by a recognized Certificate Authority (CA), then you might get away without additional configuration. If you need to look up public keys of OpenAM clients, this module can also look up public keys in an LDAP directory server.

When you store certificates and certificate revocation lists (CRL) in an LDAP directory service, you must configure both how to access the directory service and also how to look up the certificates and CRLs, based on the fields in the certificates that OpenAM clients present to authenticate.

Access to the LDAP server and how to search for users is similar to LDAP module configuration as in "Hints for the LDAP Authentication Module". The primary difference is that, unlike for LDAP configuration, OpenAM retrieves the user identifier from a field in the certificate that the client application presents, then uses that identifier to search for the LDAP directory entry that holds the certificate, which should match the certificate presented. For example, if the Subject field of a typical certificate has a DN C=FR, O=Example Corp, CN=Barbara Jensen, and Barbara Jensen's entry in the directory has cn=Barbara Jensen, then you can use CN=Barbara Jensen from the Subject DN to search for the entry with cn=Barbara Jensen in the directory.

ssoadm service name: iPlanetAMAuthCertService

Match Certificate in LDAP

When enabled, OpenAM searches for a match for the user's certificate in the LDAP directory. If a match is found and not revoked according to a CRL or OCSP validation, then authentication succeeds.

ssoadm attribute: iplanet-am-auth-cert-check-cert-in-ldap

Subject DN Attribute Used to Search LDAP for Certificates

Indicates which attribute and value in the certificate Subject DN is used to find the LDAP entry holding the certificate.

Default: CN

ssoadm attribute: iplanet-am-auth-cert-attr-check-ldap

Match Certificate to CRL

When enabled, OpenAM checks whether the certificate has been revoked according to a CRL in the LDAP directory.

ssoadm attribute: iplanet-am-auth-cert-check-crl

Issuer DN Attribute Used to Search LDAP for CRLs

Indicates which attribute and value in the certificate Issuer DN is used to find the CRL in the LDAP directory.

Default: CN

If only one attribute is specified, the LDAP search filter used to find the CRL based on the Subject DN of the CA certificate is (attr-name=attr-value-in-subject-DN).

For example, if the subject DN of the issuer certificate is C=US, CN=Some CA, serialNumber=123456, and the attribute specified is CN, then the LDAP search filter used to find the CRL is (CN=Some CA).

In order to distinguish among different CRLs for the same CA issuer, specify multiple attributes separated by commas (,) in the same order they occur in the subject DN. When multiple attribute names are provided in a comma-separated list, the LDAP search filter used is (cn=attr1=attr1-value-in-subject-DN,attr2=attr2-value-in-subject-DN,...,attrN=attrN-value-in-subject-DN).

For example, if the subject DN of the issuer certificate is C=US, CN=Some CA, serialNumber=123456, and the attributes specified are CN,serialNumber, then the LDAP search filter used to find the CRL is (cn=CN=Some CA,serialNumber=123456).

ssoadm attribute: iplanet-am-auth-cert-attr-check-crl

HTTP Parameters for CRL Update

Your certificate authority should provide the URL to use here, from which OpenAM can get CRL updates.

ssoadm attribute: iplanet-am-auth-cert-param-get-crl

Match CA Certificate to CRL

When enabled, OpenAM checks the CRL against the CA certificate to ensure it has not been compromised.

ssoadm attribute: sunAMValidateCACert

Cache CRLs in memory

When enabled, CRLs will be cached.

ssoadm attribute: openam-am-auth-cert-attr-cache-crl

Update CA CRLs from CRLDistributionPoint

When enabled, OpenAM updates CRLs from the LDAP directory store.

ssoadm attribute: openam-am-auth-cert-update-crl

OCSP Validation

Enable this to use Online Certificate Status Protocol (OCSP) instead of CRLs to check certificates' revocation status.

If you enable this, you also must configure OSCP for OpenAM under Configure > Server Defaults or Deployment > Servers > Server Name > Security.

ssoadm attribute: iplanet-am-auth-cert-check-ocsp

LDAP Server Where Certificates are Stored

Identifies the LDAP server with certificates. Remember to specify URLs with appropriate port numbers (389 for unencrypted LDAP, 636 for LDAP over SSL). When configuring a secure connection, scroll down to enable Use SSL/TLS for LDAP Access.

ssoadm attribute: iplanet-am-auth-cert-ldap-provider-url

LDAP Search Start or Base DN

Valid base DN for the LDAP search, such as dc=example,dc=com.

ssoadm attribute: iplanet-am-auth-cert-start-search-loc

LDAP Server Authentication User, LDAP Server Authentication Password

If OpenAM stores attributes in the LDAP directory, for example to manage account lockout, or if the LDAP directory requires that OpenAM authenticate in order to read users' attributes, then OpenAM needs the DN and password to authenticate to the LDAP directory.

ssoadm attributes: iplanet-am-auth-cert-principal-user, and iplanet-am-auth-cert-principal-passwd

Use SSL/TLS for LDAP Access

If you use SSL/TLS for LDAP access, OpenAM must be able to trust the LDAP server certificate.

ssoadm attribute: iplanet-am-auth-cert-use-ssl

Certificate Field Used to Access User Profile

If the user profile is in a different entry from the user certificate, then this can be different from subject DN attribute used to find the entry with the certificate. When you select other, provide an attribute name in the Other Certificate Field Used to Access User Profile text box.

ssoadm attribute: iplanet-am-auth-cert-user-profile-mapper

Other Certificate Field Used to Access User Profile

This field is only used if the Certificate Field Used to Access User Profile attribute is set to other. This field allows a custom certificate field to be used as the basis of the user search.

ssoadm attribute: iplanet-am-auth-cert-user-profile-mapper-other

SubjectAltNameExt Value Type to Access User Profile

Use this if you want to look up the user profile from an RFC 822 style name, or a User Principal Name as used in Active Directory.

ssoadm attribute: iplanet-am-auth-cert-user-profile-mapper-ext

Trusted Remote Hosts

Defines a list of hosts trusted to send certificates to OpenAM, such as load balancers doing SSL termination.

Valid values: none, any, and IP_ADDR, where IP_ADDR is one or more IP addresses of trusted hosts that can send client certificates to OpenAM.

ssoadm attribute: iplanet-am-auth-cert-gw-cert-auth-enabled

HTTP Header Name for Client Certificates

Specifies the name of the HTTP request header containing the PEM-encoded certificate. If Trusted Remote Hosts is set to any or specifies the IP address of the trusted host (for example, an SSL-terminated load balancer) that can supply client certificates to OpenAM, the administrator must specify the header name in this attribute.

ssoadm attribute: sunAMHttpParamName

Authentication Level

Sets the authentication level used to indicate the level of security associated with the module. The value can range from 0 to any positive integer.

ssoadm attribute: iplanet-am-auth-cert-auth-level

2.5.5. Hints for the Data Store Authentication Module

The Data Store authentication module allows a login using the Identity Repository of the realm to authenticate users. Using the Data Store module removes the requirement to write an authentication plugin module, load, and then configure the authentication module if you need to authenticate against the same data store repository. Additionally, you do not need to write a custom authentication module where flatfile authentication is needed for the corresponding repository in that realm.

Yet, the Data Store module is generic. It does not implement data store-specific capabilities, such as the password policy and password reset features provided by LDAP modules. Therefore, the Data Store module returns failure when such capabilities are invoked.

ssoadm service name: sunAMAuthDataStoreService

Authentication Level

Sets the authentication level used to indicate the level of security associated with the module. The value can range from 0 to any positive integer.

ssoadm attribute: sunAMAuthDataStoreAuthLevel

2.5.6. Hints for the Device ID (Match) Authentication Module

The Device ID (Match) module provides device fingerprinting functionality for risk-based authentication. The Device ID (Match) module collects the unique characteristics of a remote user's computing device and compares them to characteristics on a saved device profile. The module computes any variances between the collected characteristics to those stored on the saved device profile and assigns penalty points for each difference.

In general, you can configure and gather the following device print items:

User agents associated with the configuration of a web browser
Installed fonts
The plugins installed for the web browser
The resolution and color depth associated with a display
The timezone or even the geolocation of a device

For example, when a user who typically authenticates to OpenAM using Firefox and then logs on using Chrome, the Device ID (Match) module notes the difference and assigns penalty points to this change in behavior. If the module detects additional differences in behavior, such as browser fonts, geolocation, and so forth, then additional points are assessed and calculated.

If the total maximum number of penalty points exceeds a pre-configured threshold value, the Device ID (Match) module fails and control is determined by how you configured your authentication chain. If you include the HOTP module in your authentication chain, and if the Device ID (Match) module fails after the maximum number of penalty points have been exceeded, then the authentication chain issues a HOTP request to the user, requiring the user to identify himself using two-factor authentication.

Important

By default, the maximum penalty points is set to 0, which you can adjust in the server-side script.

The Device ID (Match) module comes pre-configured with default client-side and server-side JavaScript code, supplying the logic necessary to fingerprint the user agent and computer. Scripting allows you to customize the code, providing more control over the device fingerprint elements that you would like to collect. While OpenAM scripting supports both the JavaScript (default) and Groovy languages, only server-side scripts can be writtern in either language. The client-side scripts must be written in the JavaScript language.

Caution

The Device ID (Match) module's default JavaScript client-side and server-side scripts are fully functional. If you change the client-side script, you must also make a corresponding change to the server-side script. For a safer option, if you want to change the behavior of the module, you can make a copy of the scripts, customize the behavior, and update the Device ID (Match) modules to use the new scripts.

The Device ID (Match) does not stand on its own within an authentication chain and requires additional modules. For example, you can have any module that identifies the user (for example, DataStore, Active Directory or others), Device ID (Match), any module that provides two-factor authentication, for example the ForgeRock Authenticator (OATH) or ForgeRock Authenticator (Push) authentication modules, and Device ID (Save) within your authentication chain.

As an example, you can configure the following modules with the specified criteria:

DataStore - Requisite. The Device ID (Match) module requires user authentication information to validate the username. You can also use other modules that identify the username, such as LDAP, Active Directory, or RADIUS.
Device ID (Match) - Sufficient. The Device ID (Match) runs the client-side script, which invokes the device fingerprint collectors, captures the data, and converts it into a JSON string. It then auto-submits the data in a JSP page to the server-side scripting engine.
The server-side script calculates the penalty points based on differences between the client device and stored device profile, and or whether the client device successfully "matches" the stored profile. If a match is successful, OpenAM determines that the client's device has the required attributes for a successful authentication.
If the device does not have a match, then the module fails and falls through to the HOTP module for further processing.
HOTP - Requisite. If the user's device does not match a stored profile, OpenAM presents the user with a HMAC One-Time Password (HOTP) screen either by SMS or email, prompting the user to enter a password.
You can also use any other module that provides two-factor authentication.
After the HOTP has successfully validated the user, the Device ID (Save) module gathers additional data from the user. For specific information about the HOTP module, see "Hints for the HOTP Authentication Module".
Device ID (Save) - Required. The Device ID (Save) module provides configuration options to enable an auto-save feature on the device profile as well as set a maximum number of stored device profiles on the user entry or record. Once the maximum number of stored device profiles is reached, OpenAM deletes the old data from the user record as new ones are added. User records could thus contain both old and new device profiles.
If the auto-save feature is not enabled, OpenAM presents the user with a screen to save the new device profile.
The module also takes the device print and creates a JSON object that includes the ID, name, last selected date, selection counter, and device print. For specific information about the Device ID (Save) module, see "Hints for the Device ID (Save) Module".
Note
If a user has multiple device profiles, the profile that is the closest match to the current client details is used for the comparison result.

The Device ID (Match) module has the following properties:

Client-Side Script Enabled

Enable Device ID (Match) to send JavaScript in an authentication page to the device to collect data about the device by a self-submitting form.

ssoadm attribute: iplanet-am-auth-scripted-client-script-enabled

Client-Side Script

You can see default client-side JavaScript code that you can modify if necessary. Note that if you change the client-side script, you must make a corresponding change in the server-side script to account for the specific addition or removal of an element.

ssoadm attribute: iplanet-am-auth-scripted-client-script

Server-side Script

You can see default server-side JavaScript code that you can modify if necessary. Note that a change in the client-side script requires a corresponding change in the server-side script to account for the specific addition or removal of an element.

ssoadm attribute: iplanet-am-auth-scripted-server-script

Authentication Level

Sets the authentication level used to indicate the level of security associated with the module. The value can range from 0 to any positive integer.

ssoadm attribute: iplanet-am-auth-scripted-auth-level

To Configure the Device ID (Match) Authentication Module

Log into the OpenAM console as an administrator.
On the Realms page, click the realm from which you want to work.
Click Authentication > Modules.
To add the Device ID (Match) module, do the following substeps:
1. Click Add Module.
2. In the Module Name box, enter Device-ID-Match.
3. In the Type box, select Device Id (Match), and then click Create.
4. Click Save Changes.
  Device ID (Match) Module
To make adjustments to the default scripts, click Scripts drop-down list, and then click Device Id (Match) - Client Side.
To make corresponding changes to the server-side script, click Scripts drop-down list, and then click Device Id (Match) - Server Side. For more information, see "Managing Scripts".

To Configure an Authentication Chain With a Device ID (Match) Authentication Module

Log into the OpenAM console as an administrator.
On the Realms page, click the realm from which you want to work.
Click Authentication > Chains.
On the Authentication Chains page, do the following steps:
1. Click Add Chain. In the Chain Name box, enter a descriptive label for your authentication chain, and then click Create.
2. Click Add Module.
3. On the New Module dialog, select the authentication module, select the criteria, and then click Ok to save your changes. Repeat the last two steps to enter each module to your chain.
  For example, you can enter the following modules and criteria:
  Device ID Chain
  Module Criteria
  DataStore REQUISITE
  Device-ID-Match SUFFICIENT
  HOTP REQUISITE
  Device-ID-Save REQUIRED
  
  It is assumed that you have added the Device Id (Match) and Device Id (Save) modules. If you have not added these modules, see "To Configure the Device ID (Match) Authentication Module" and "To Configure the Device ID (Save) Authentication Module".
Review your authentication chain, and then click Save Changes.

2.5.6.1. What the User Sees During Authentication

When the user logs on to the console, OpenAM determines if the user's device differs from that of the stored profile. If the differences exceed the maximum number of penalty points or a device profile has not yet been stored, OpenAM sends an "Enter OTP" page, requiring the user to enter a one-time password, which is sent to the user via email or SMS. The user also has the option to request a one-time password.

Next, because the Device ID (Save) module is present, OpenAM presents the user with a "Add to Trusted Devices?" page, asking if the user wants to add the device to the list of trusted device profiles. If the user clicks "Yes", OpenAM prompts the user to enter a descriptive name for the trusted device.

Next, OpenAM presents the user with the User Profile page, where the user can click the Dashboard link at top to access the My Applications and Authentication Devices page. Once on the Dashboard, the user can view the list of trusted devices or remove the device by clicking the Delete Device link.

2.5.7. Hints for the Device ID (Save) Module

The Device ID (Save) module saves a user's device profile. The module can either save the profile upon request, requiring the user to provide a name for the device and explicitly save it, or it can save the profile automatically.

Note

If a user has multiple device profiles, the profile that is the closest match to the current client details is used for the comparison result.

Within its configured authentication chain, the Device ID (Save) module also takes the device print and creates a JSON object that consists of the ID, name, last selected date, selection counter, and device print itself.

The Device ID (Save) module has the following properties:

Automatically store new profiles

Select the checkbox to automatically store new profiles. After successful HOTP confirmation, OpenAM stores the new profile automatically.

ssoadm attribute: iplanet-am-auth-device-id-save-auto-store-profile

Maximum stored profile quantity

Sets the maximum number of stored profiles on the user's record.

ssoadm attribute: iplanet-am-auth-device-id-save-max-profiles-allowed

Authentication Level

Sets the authentication level used to indicate the level of security associated with the module. The value can range from 0 to any positive integer.

ssoadm attribute: iplanet-am-auth-device-id-save-auth-level

To Configure the Device ID (Save) Authentication Module

Log into the OpenAM console as an administrator.
Click the realm from which you want to work.
Click Authentication > Modules.
To add the Device ID (Save) module, click Add Module.
In the Module Name box, enter Device-ID-Save.
In the Type box, select Device Id (Save), and then click Create.
To configure the Device-Id (Save) module, do the following:
1. Click the Automatically store new profiles checkbox. If this box is left unchecked, the user will be prompted to give consent to store new profiles.
2. In the Maximum stored profile quantity box, enter the max number of stored profiles. Any profile that exceeds this number will not be stored.
3. In the Authentication Level box, enter a number corresponding to the authentication level of the module.
4. Click Save Changes.
  Device ID (Save) Module

2.5.8. Hints for the Federation Authentication Module

The Federation authentication module is used by a service provider to create a user session after validating single sign-on protocol messages. This authentication module is used by the SAML, SAMLv2, ID-FF, and WS-Federation protocols.

ssoadm service name: sunAMAuthFederationService

Authentication Level

Sets the authentication level used to indicate the level of security associated with the module. The value can range from 0 to any positive integer.

ssoadm attribute: sunAMAuthFederationAuthLevel

2.5.9. Hints for the ForgeRock Authenticator (OATH) Authentication Module

The ForgeRock Authenticator (OATH) module provides a more secure method for users to access their accounts with the help of a device such as a mobile phone. For detailed information about two-step verification with the ForgeRock Authenticator (OATH) module in OpenAM, see "Multi-Factor Authentication".

Note

OpenAM provides two authentication modules that support OATH:

The ForgeRock Authenticator (OATH) authentication module, which is optimized for use with the ForgeRock Authenticator app and provides device profile encryption.
The OATH authentication module, which is a raw OATH implementation requiring more configuration for users and the OpenAM administrator.

We recommend using the ForgeRock Authenticator (OATH) authentication module when possible.

Also, the ForgeRock Authenticator (OATH), HOTP, and OATH authentication modules all support HOTP passwords, but the way that users obtain passwords differs. See "Differences Among OpenAM Authentication Modules That Support HOTP" for more information.

ssoadm service name: iPlanetAMAuthAuthenticatorOATHService

Authentication Level

Sets the authentication level used to indicate the level of security associated with the module. The value can range from 0 to any positive integer.

ssoadm attribute: iplanet-am-auth-fr-oath-auth-level

One-Time Password Length

Sets the length of the OTP to six digits or longer. The default value is six.

ssoadm attribute: iplanet-am-auth-fr-oath-password-length

Minimum Secret Key Length

The minimum number of hexadecimal characters allowed for the secret key.

ssoadm attribute: iplanet-am-auth-fr-oath-min-secret-key-length

OATH Algorithm to Use

Select whether to use HOTP or TOTP. You can create an authentication chain to allow for a greater variety of devices. The default value is HOTP.

ssoadm attribute: iplanet-am-auth-fr-oath-algorithm

HOTP Window Size

The window that the OTP device and the server counter can be out of sync. For example, if the window size is 100 and the server's last successful login was at counter value 2, then the server will accept an OTP from device counter 3 to 102. The default value is 100.

ssoadm attribute: iplanet-am-auth-fr-oath-hotp-window-size

Add Checksum Digit

Adds a checksum digit at the end of the HOTP password to verify the OTP was generated correctly. This is in addition to the actual password length. Set this only if your device supports it. The default value is No.

ssoadm attribute: iplanet-am-auth-fr-oath-add-checksum

Truncation Offset

Advanced feature that is device-specific. Let this value default unless you know your device uses a truncation offset. The default value is -1.

ssoadm attribute: iplanet-am-auth-fr-oath-truncation-offset

TOTP Time Step Interval

The time interval for which an OTP is valid. For example, if the time step interval is 30 seconds, a new OTP will be generated every 30 seconds, and an OTP will be valid for 30 seconds. The default value is 30 seconds.

ssoadm attribute: iplanet-am-auth-fr-oath-size-of-time-step

TOTP Time Steps

The number of time step intervals that the system and the device can be off before password resynchronization is required. For example, if the number of TOTP time steps is 2 and the TOTP time step interval is 30 seconds, the server will allow an 89 second clock skew between the client and the server—two 30 second steps plus 29 seconds for the interval in which the OTP arrived. The default value is 2.

ssoadm attribute: iplanet-am-auth-fr-oath-steps-in-window

Maximum Allowed Clock Drift

The maximum acceptable clock skew before authentication fails. When this value is exceeded, the user must re-register the device.

ssoadm attribute: openam-auth-fr-oath-maximum-clock-drift

Name of the Issuer

A value that appears as an identifier on the user's device. Common choices are a company name, a web site, or an OpenAM realm.

ssoadm attribute: openam-auth-fr-oath-issuer-name

2.5.10. Hints for the ForgeRock Authenticator (Push) Authentication Module

The ForgeRock Authenticator (Push) module provides a way to send push notification messages to a device such as a mobile phone, enabling multi-factor authentication. For detailed information about multi-factor authentication with the ForgeRock Authenticator (Push) module in OpenAM, see "Multi-Factor Authentication".

ssoadm service name: iPlanetAMAuthAuthenticatorPushService

Authentication Level

Sets the authentication level used to indicate the level of security associated with the module. The value can range from 0 to any positive integer.

ssoadm attribute: forgerock-am-auth-push-auth-level

Return Message Timeout (ms)

The period of time (in milliseconds) within which a push notification should be replied to.

Default: 120000

ssoadm attribute: forgerock-am-auth-push-message-response-timeout

Login Message

Text content of the push message, which is used for the notification displayed on the registered device. The following variables can be used in the message:

{{user}}: Replaced with the username value of the account registered in the ForgeRock Authenticator app, for example Demo.
{{issuer}}: Replaced with the issuer value of the account registered in the ForgeRock Authenticator app, for example ForgeRock.

Default: Login attempt from {{user}} at {{issuer}}

ssoadm attribute: forgerock-am-auth-push-message

2.5.11. Hints for the ForgeRock Authenticator (Push) Registration Authentication Module

The ForgeRock Authenticator (Push) Registration module provides a way to register a device such as a mobile phone for multi-factor authentication. For detailed information about multi-factor authentication with the ForgeRock Authenticator (Push) module in OpenAM, see "Managing Devices for Multi-Factor Authentication".

ssoadm service name: iPlanetAMAuthAuthenticatorPushRegistrationService

Authentication Level

Sets the authentication level used to indicate the level of security associated with the module. The value can range from 0 to any positive integer.

ssoadm attribute: forgerock-am-auth-push-reg-auth-level

Issuer Name

A value that appears as an identifier on the user's device. Common choices are a company name, a web site, or an OpenAM realm.

ssoadm attribute: forgerock-am-auth-push-reg-issuer

Registration Response Timeout (ms)

The period of time (in milliseconds) to wait for a response to the registration QR code. If no response is received during this time the QR code times out and the registration process fails.

Default: 120000

ssoadm attribute: forgerock-am-auth-push-message-registration-response-timeout

Background Color

The background color in hex notation to display behind the issuer's logo within the ForgeRock Authenticator app.

Default: #519387

ssoadm attribute: forgerock-am-auth-hex-bgcolour

Image URL

The location of an image to download and display as the issuer's logo within the ForgeRock Authenticator app.

ssoadm attribute: forgerock-am-auth-img-url

App Store App URL

URL of the app to download on the App Store.

Default: https://itunes.apple.com/app/forgerock-authenticator /id1038442926 (the ForgeRock Authenticator app)

ssoadm attribute: forgerock-am-auth-apple-link

Google Play URL

URL of the app to download on Google Play.

Default: https://play.google.com/store/apps/details?id=com.forgerock.authenticator (the ForgeRock Authenticator app)

ssoadm attribute: forgerock-am-auth-google-link

2.5.12. Hints for the HOTP Authentication Module

The HOTP authentication module works with an authentication chain with any module that stores the username attribute. The module uses the username from the sharedState set by the previous module in the chain and retrieves the user's email address or telephone number to send a one-time password to the user. The user then enters the password on a Login page and completes the authentication process if successful.

For example, to set up HOTP in an authentication chain, you can configure the Data Store module (or any module that stores the user's username) as the requisite first module, and the HOTP module as the second requisite module. When authentication succeeds against the Data Store module, the HOTP module retrieves the Email Address and Telephone Number attributes from the data store based on the username value. For the HOTP module to use either attribute, the Email Address must contain a valid email address, or the Telephone Number must contain a valid SMS telephone number.

You can set the HOTP module to automatically generate a password when users begin logging into the system. You can also set up mobile phone, mobile carrier, and email attributes for tighter controls over where the messages are generated and what provider the messages go through to reach the user.

Note

The ForgeRock Authenticator (OATH), HOTP, and OATH authentication modules all support HOTP passwords, but the way that users obtain passwords differs. See "Differences Among OpenAM Authentication Modules That Support HOTP" for more information.

ssoadm service name: sunAMAuthHOTPService

Authentication Level

Sets the authentication level used to indicate the level of security associated with the module. The value can range from 0 to any positive integer.

ssoadm attribute: sunAMAuthHOTPAuthLevel

SMS Gateway Implementation Class

Change this if you must customize the SMS gateway implementation. The default class sends an SMS or email, depending on the configuration.

ssoadm attribute: sunAMAuthHOTPSMSGatewayImplClassName

Mail Server Host Name

Host name of the mail server supporting SMTP for electronic mail.

ssoadm attribute: sunAMAuthHOTPSMTPHostName

Mail Server Host Port

The default outgoing mail server port is 25, 465 (when connecting over SSL).

ssoadm attribute: sunAMAuthHOTPSMTPHostPort

Mail Server Authentication Username

User name for OpenAM to connect to the mail server.

ssoadm attribute: sunAMAuthHOTPSMTPUserName

Mail Server Authentication Password

Password for OpenAM to connect to the mail server.

ssoadm attribute: sunAMAuthHOTPSMTPUserPassword

Mail Server Secure Connection

If OpenAM connects to the mail server securely, OpenAM must be able to trust the server certificate.

ssoadm attribute: sunAMAuthHOTPSMTPSSLEnabled

One-Time Password Validity Length (in minutes)

One-time passwords are valid for five minutes after they are generated by default.

Note

You may also also need to configure the login page session timeouts in OpenAM. For more information, see How do I configure login page session timeouts in OpenAM (All versions)?

ssoadm attribute: sunAMAuthHOTPPasswordValidityDuration

One-Time Password Length

Set the length of the OTP to 6 or 8.

ssoadm attribute: sunAMAuthHOTPPasswordLength

One-Time Password Delivery

Send the one-time password by SMS, by mail, or both.

ssoadm attribute: sunAMAuthHOTPasswordDelivery

Mobile Phone Number Attribute Name

Provides the attribute name used for the text message. The default value is telephoneNumber.

ssoadm attribute: openamTelephoneAttribute

Mobile Carrier Attribute Name

Specifies a user profile attribute that contains a mobile carrier domain for sending SMS messages.

The uncustomized OpenAM user profile does not have an attribute for the mobile carrier domain. You can:

Customize the OpenAM user profile by adding a new attribute to it. Then you can populate the new attribute with users' SMS messaging domains.
All mobile carriers and bulk SMS messaging services have associated SMS messaging domains. For example, Verizon uses vtext.com, T-Mobile uses tmomail.net, and the TextMagic service uses textmagic.com. If you plan to send text messages internationally, determine whether the messaging service requires a country code.
Leave the value for Mobile Carrier Attribute Name blank, and let OpenAM default to sending SMS messages using txt.att.net for all users.

ssoadm attribute: openamSMSCarrierAttribute

Email Attribute Name

Provides the attribute name used to email the OTP. The default value is mail (email).

ssoadm attribute: openamEmailAttribute

Auto Send OTP Code

Set up the HOTP module to automatically generate an email or text message when users begin the login process.

ssoadm attribute: sunAMAuthHOTPAutoClicking

Email From Address

Specifies the From: address when sending a one-time password by mail.

ssoadm attribute: sunAMAuthHOTPSMTPFromAddress

One Time Password Max Retry

Sets the number of times an OTP may be entered. Minimum is 1, maximum is 10.

Default: 3

ssoadm attribute: forgerock-oath-max-retry

2.5.13. Hints for the HTTP Basic Authentication Module

HTTP basic authentication takes a user name and password from HTTP authentication and tries authentication against the backend module in OpenAM, depending on what you configure as the Backend Module Name.

ssoadm service name: iPlanetAMAuthHTTPBasicService

Backend Module Name

Specifies the module that checks the user credentials. The credentials are then supplied to either a data store or other identity repository module for authentication.

ssoadm attribute: iplanet-am-auth-http-basic-module-configured

Authentication Level

Sets the authentication level used to indicate the level of security associated with the module. The value can range from 0 to any positive integer.

ssoadm attribute: iplanet-am-auth-httpbasic-auth-level

2.5.14. Hints for the JDBC Authentication Module

The Java Database Connectivity (JDBC) module lets OpenAM connect to a database, such as MySQL or Oracle DB to authenticate users.

ssoadm service name: sunAMAuthJDBCService

Connection Type

Choose Connection pool is retrieved via JNDI to connect using the Java Naming and Directory Interface connection pool supported by the web container in which OpenAM runs. Choose Non-persistent JDBC connection to connect directly through the JDBC driver.

ssoadm attribute: sunAMAuthJDBCConnectionType

Connection Pool JNDI Name

When using Connection pool is retrieved via JNDI, this specifies the pool. How you configure connection pooling depends on the web container where you run OpenAM. Refer to the documentation for your web container for instructions on setting up connection pooling.

ssoadm attribute: sunAMAuthJDBCJndiName

JDBC Driver

When using a non-persistent JDBC connection, this specifies the JDBC driver provided by the database.

The .jar containing the JDBC driver belongs in the WEB-INF/lib directory of the deployed OpenAM instance, and so you should add it to a custom OpenAM .war file that you deploy.

ssoadm attribute: sunAMAuthJDBCDriver

JDBC URL

When using a non-persistent JDBC connection, this specifies the URL to connect to the database.

ssoadm attribute: sunAMAuthJDBCUrl

Database Username

Specify the user name to open the database connection.

ssoadm attribute: sunAMAuthJDBCDbuser

Database Password

Specify the password for the user opening the database connection.

ssoadm attribute: sunAMAuthJDBCDbpassword

Password Column Name

Specify the database column name where passwords are stored.

ssoadm attribute: sunAMAuthJDBCPasswordColumn

Prepared Statement

Specify the SQL query to return the password corresponding to the user to authenticate.

ssoadm attribute: sunAMAuthJDBCStatement

Class to Transform Password Syntax

Specify the class that transforms the password retrieved to the same format as provided by the user.

The default class expects the password in clear text. Custom classes must implement the JDBCPasswordSyntaxTransform interface.

ssoadm attribute: sunAMAuthJDBCPasswordSyntaxTransformPlugin

Authentication Level

Sets the authentication level used to indicate the level of security associated with the module. The value can range from 0 to any positive integer.

ssoadm attribute: sunAMAuthJDBCAuthLevel

Note

OpenAM provides two properties, iplanet-am-admin-console-invalid-chars and iplanet-am-auth-ldap-invalid-chars, that store LDAP-releated special characters that are not allowed in username searches.

When using JDBC databases, consider adding the '%' wildcard character to the iplanet-am-admin-console-invalid-chars and iplanet-am-auth-ldap-invalid-chars properties. By default, the '%' character is not included in the properties.

2.5.15. Hints for the LDAP Authentication Module

OpenAM connects to directory servers using Lightweight Directory Access Protocol (LDAP). To build an easy-to-manage, high-performance, pure Java, open source directory service, try OpenDJ directory services.

ssoadm service name: iPlanetAMAuthLDAPService

Primary LDAP Server, Secondary LDAP Server

Directory servers generally use built-in data replication for high availability. Thus, a directory service likely consists of a pool of replicas to which OpenAM can connect to retrieve and update directory data. You set up primary and secondary servers in case a replica is down due to maintenance or to a problem with a particular server.

Set one or more primary and optionally, one or more secondary directory server for each OpenAM server. For the current OpenAM server, specify each directory server as a host:port combination. For other OpenAM servers in the deployment, you can specify each directory server as server-name|host:port, where server-name is the FQDN portion of the OpenAM server from the list under Deployment > Servers, and host:port identifies the directory server.

For example, if the server-name that is listed is http://openam.example.com:8080/openam, and the directory server is accessible at opendj.example.com:1389, you would enter openam.example.com|opendj.example.com:1389.

When authenticating users from a directory server that is remote to OpenAM, set the primary server values, and optionally the secondary server values. Primary servers have priority over secondary servers.

ssoadm attributes are: primary is iplanet-am-auth-ldap-server; secondary is iplanet-am-auth-ldap-server2.

Both properties take more than one value; thus, allowing more than one primary or secondary remote server, respectively. Assuming a multi-data center environment, OpenAM determines priority within the primary and secondary remote servers, respectively, as follows:

Every LDAP server that is mapped to the current OpenAM instance has highest priority.
For example, if you are connected to openam1.example.com and ldap1.example.com is mapped to that OpenAM instance, then OpenAM uses ldap1.example.com.
Every LDAP server that was not specifically mapped to a given OpenAM instance has the next highest priority.
For example, if you have another LDAP server, ldap2.example.com, that is not connected to a specific OpenAM server and if ldap1.example.com is unavailable, OpenAM connects to the next highest priority LDAP server, ldap2.example.com.
LDAP servers that are mapped to different OpenAM instances have the lowest priority.
For example, if ldap3.example.com is connected to openam3.example.com and ldap1.example.com and ldap2.example.com are unavailable, then openam1.example.com connects to ldap3.example.com.

If you want use SSL or StartTLS to initiate a secure connection to a data store, then scroll down to enable SSL/TLS Access to LDAP Server. Make sure that OpenAM can trust the server's certificates when using this option.

ssoadm attributes: openam-auth-ldap-connection-mode

Possible values: LDAP, LDAPS, and StartTLS

DN to Start User Search

LDAP data is organized hierarchically, a bit like a file system on Windows or UNIX. More specific DNs likely result in better search performance. When configuring the module for a particular part of the organization, you can perhaps start searches from a specific organizational unit, such as ou=sales,dc=example,dc=com.

If multiple entries exist with identical search attribute values, make this value specific enough to return only one entry.

ssoadm attribute: iplanet-am-auth-ldap-base-dn

Bind User DN, Bind User Password

If OpenAM stores attributes in the directory, for example to manage account lockout, or if the directory requires that OpenAM authenticate in order to read users' attributes, then OpenAM needs the DN and password to authenticate to the directory.

The default is cn=Directory Manager. Make sure that password is correct before you log out. If it is incorrect, you will be locked out. If this should occur, you can login with the superuser DN, which by default is uid=amAdmin,ou=People,OpenAM-deploy-base, where OpenAM-deploy-base you set during OpenAM configuration.

ssoadm attributes: iplanet-am-auth-ldap-bind-dn, iplanet-am-auth-ldap-bind-passwd

Attribute Used to Retrieve User Profile, Attributes Used to Search for a User to be Authenticated, User Search Filter, Search Scope

LDAP searches for user entries return entries with attribute values matching the filter you provide. For example, if you search under ou=people,dc=example,dc=com with a filter "(mail=bjensen@example.com)", then the directory returns the entry that has mail=bjensen@example.com. In this example the attribute used to search for a user is mail. Multiple attribute values mean the user can authenticate with any one of the values. For example, if you have both uid and mail, then Barbara Jensen can authenticate with either bjensen or bjensen@example.com.

Should you require a more complex filter for performance, you add that to the User Search Filter text box. For example, if you search on mail and add User Search Filter (objectClass=inetOrgPerson), then OpenAM uses the resulting search filter (&(mail=address)(objectClass=inetOrgPerson)), where address is the mail address provided by the user.

Scope OBJECT means search only the entry specified as the DN to Start User Search, whereas ONELEVEL means search only the entries that are directly children of that object. SUBTREE means search the entry specified and every entry under it.

ssoadm attributes: iplanet-am-auth-ldap-user-naming-attribute, iplanet-am-auth-ldap-user-search-attributes, iplanet-am-auth-ldap-search-filter, and iplanet-am-auth-ldap-search-scope

LDAP Connection Mode

If you want use SSL or StartTLS to initiate a secure connection to a data store, OpenAM must be able to trust LDAP certificates, either because the certificates were signed by a CA whose certificate is already included in the trust store used by the container where OpenAM runs, or because you imported the certificates into the trust store.

ssoadm attribute: openam-auth-ldap-connection-mode

Possible values: LDAP, LDAPS, and StartTLS

Return User DN to DataStore

When enabled, and OpenAM uses the directory service as the user store, the module returns the DN, rather than the User ID. From the DN value, OpenAM uses the RDN to search for the user profile. For example, if a returned DN value is uid=demo,ou=people,dc=openam,dc=example,dc=org, OpenAM uses uid=demo to search the data store.

ssoadm attribute: iplanet-am-auth-ldap-return-user-dn

User Creation Attributes

This list lets you map (external) attribute names from the LDAP directory server to (internal) attribute names used by OpenAM.

ssoadm attribute: iplanet-am-ldap-user-creation-attr-list

Minimum Password Length

Specify the minimum acceptable password length.

ssoadm attribute: iplanet-am-auth-ldap-min-password-length

LDAP Behera Password Policy Support

When enabled, support interoperability with servers that implement the Internet-Draft, Password Policy for LDAP Directories.

Support for this Internet-Draft is limited to the LDAP authentication module. Other components of OpenAM, such as the password change functionality in the /idm/EndUser page, do not support the Internet-Draft. In general, outside of the LDAP authentication module, OpenAM binds to the directory server as an administrator, such as Directory Manager. When OpenAM binds to the directory server as an administrator rather than as an end user, many features of the Internet-Draft password policies do not apply.

ssoadm attribute: iplanet-am-auth-ldap-behera-password-policy-enabled

Trust All Server Certificates

When enabled, blindly trust server certificates, including self-signed test certificates.

ssoadm attribute: iplanet-am-auth-ldap-ssl-trust-all

LDAP Connection Heartbeat Interval

Specifies how often OpenAM should send a heartbeat request to the directory server to ensure that the connection does not remain idle. Some network administrators configure firewalls and load balancers to drop connections that are idle for too long. You can turn this off by setting the value to 0 or to a negative number. To set the units for the interval use LDAP Connection Heartbeat Time Unit.

Default: 1

ssoadm attribute: openam-auth-ldap-heartbeat-interval

LDAP Connection Heartbeat Time Unit

Specifies the time unit corresponding to LDAP Connection Heartbeat Interval.

Default: minute

ssoadm attribute: openam-auth-ldap-heartbeat-timeunit

LDAP operations timeout

Defines the timeout in milliseconds that OpenAM should wait for a response from the directory server.

Default: 0 (means no timeout)

ssoadm attribute: openam-auth-ldap-operation-timeout

Authentication Level

Sets the authentication level used to indicate the level of security associated with the module. The value can range from 0 to any positive integer.

ssoadm attribute: iplanet-am-auth-ldap-auth-level

LDAPS Server Protocol Version

Defines which protocol version is used to establish the secure connection to the LDAP Directory Server.

Default: TLSv1

ssoadm attribute: openam-auth-ldap-secure-protocol-version

Possible values: TLSv1, TLSv1.1, TLSv1.2

2.5.16. Hints for the MSISDN Authentication Module

The Mobile Station Integrated Services Digital Network (MSISDN) authentication module enables non-interactive authentication using a mobile subscriber ISDN associated with a terminal, such as a mobile phone. The module checks the subscriber ISDN against the value found on a user's entry in an LDAP directory service.

ssoadm service name: sunAMAuthMSISDNService

Trusted Gateway IP Address

Specifies a list of IP addresses of trusted clients that can access MSISDN modules. Either restrict the clients allowed to access the MSISDN module by adding each IPv4 or IPv6 address here, or leave the list empty to allow all clients to access the module. If you specify the value none, no clients are allowed access.

ssoadm attribute: sunAMAuthMSISDNTrustedGatewayList

MSISDN Number Search Parameter Name

Specifies a list of parameter names that identify which parameters to search in the request header or cookie header for the MSISDN number. For example, if you define x-Cookie-Param, AM_NUMBER, and COOKIE-ID, the MSISDN authentication service checks those parameters for the MSISDN number.

ssoadm attribute: sunAMAuthMSISDNParameterNameList

LDAP Server and Port

If you want to use SSL or TLS for security, then scroll down to enable SSL/TLS Access to LDAP. Make sure that OpenAM can trust the servers' certificates when using this option.

ssoadm attribute: sunAMAuthMSISDNLdapProviderUrl

LDAP Start Search DN

Specify the DN of the entry where the search for the user's MSISDN number should start.

ssoadm attribute: sunAMAuthMSISDNBaseDn

Attribute To Use To Search LDAP

Specify the name of the attribute in the user's profile that contains the MSISDN number to search for the user. The default is sunIdentityMSISDNNumber.

ssoadm attribute: sunAMAuthMSISDNUserSearchAttribute

LDAP Server Authentication User

If OpenAM must authenticate to the directory server in order to search, then specify the bind DN. The default is cn=amldapuser,ou=DSAME Users,dc=example,dc=com.

ssoadm attribute: sunAMAuthMSISDNPrincipalUser

LDAP Server Authentication Password

Specify the password corresponding to the bind DN.

ssoadm attribute: sunAMAuthMSISDNPrincipalPasswd

SSL/TLS for LDAP Access

If you choose to enable SSL or TLS, then make sure that OpenAM can trust the servers' certificates.

ssoadm attribute: sunAMAuthMSISDNUseSsl

MSISDN Header Search Attribute

Specify the headers to use for searching the request for the MSISDN number:

Cookie Header tells OpenAM to search the cookie.
Request Header tells OpenAM to search the request header.
Request Parameter tells OpenAM to search the request parameters.

ssoadm attribute: sunAMAuthMSISDNHeaderSearch

LDAP Attribute Used to Retrieve User Profile

Specify the LDAP attribute that is used during a search to return the user profile for MSISDN authentication service. The default is uid.

ssoadm attribute: sunAMAuthMSISDNUserNamingAttribute

Return User DN to DataStore

Enable this option only when the OpenAM directory is the same as the directory configured for MSISDN searches. When enabled, this option allows the authentication module to return the DN instead of the User ID. OpenAM thus does not need to perform an additional search with the user ID to find the user's entry.

ssoadm attribute: sunAMAuthMSISDNReturnUserDN

Authentication Level

Sets the authentication level used to indicate the level of security associated with the module. The value can range from 0 to any positive integer.

ssoadm attribute: sunAMAuthMSISDNAuthLevel

2.5.17. Hints for the OATH Authentication Module

The Open Authentication (OATH) module provides a more secure method for users to access their accounts with the help of a device, such as their mobile phone or Yubikey. Users can log into OpenAM and update their information more securely from a one-time password (OTP) displayed on their device. The OATH module includes the OATH standard protocols (RFC 4226 and RFC 6238). The OATH module has several enhancements to the HMAC One-Time Password (HOTP) Authentication Module, but does not replace the original module for those already using HOTP prior to the 10.1.0 release. The OATH module includes HOTP authentication and Time-Based One-Time Password (TOTP) authentication. Both types of authentication require an OATH compliant device that can provide the OTP.

HOTP authentication generates the OTP every time the user requests a new OTP on their device. The device tracks the number of times the user requests a new OTP, called the counter. The OTP displays for a period of time you designate in the setup, so the user may be further in the counter on their device than on their account. OpenAM will resynchronize the counter when the user finally logs in. To accommodate this, you set the number of passwords a user can generate before their device cannot be resynchronized. For example, if you set the number of HOTP Window Size to 50 and someone presses the button 30 on the user's device to generate a new OTP, the counter in OpenAM will review the OTPs until it reaches the OTP entered by the user. If someone presses the button 51 times, you will need to reset the counter to match the number on the device's counter before the user can login to OpenAM. HOTP authentication does not check earlier passwords, so if the user attempts to reset the counter on their device, they will not be able to login until you reset the counter in OpenAM to match their device. See "Deleting Registered Devices by using REST" for more information.

TOTP authentication constantly generates a new OTP based on a time interval you specify. The device tracks the last two passwords generated and the current password. The Last Login Time monitors the time when a user logs in to make sure that user is not logged in several times within the present time period. Once a user logs into OpenAM, they must wait for the time it takes TOTP to generate the next two passwords and display them. This prevents others from being able to access the users account using the OTP they entered. The user's account can be accessed again after the generation of the third new OTP is generated and displayed on their device. For this reason, the TOTP Time-Step Interval should not be so long as to lock users out, with a recommended time of 30 seconds.

An authentication chain can be created to generate an OTP from either HOTP or TOTP.

Note

OpenAM provides two authentication modules that support OATH:

The ForgeRock Authenticator (OATH) authentication module, which is optimized for use with the ForgeRock Authenticator app and provides device profile encryption.
The OATH authentication module, which is a raw OATH implementation requiring more configuration for users and the OpenAM administrator.

We recommend using the ForgeRock Authenticator (OATH) authentication module when possible.

Also, the ForgeRock Authenticator (OATH), HOTP, and OATH authentication modules all support HOTP passwords, but the way that users obtain passwords differs. See "Differences Among OpenAM Authentication Modules That Support HOTP" for more information.

ssoadm service name: iPlanetAMAuthOATHService

Authentication Level

Sets the authentication level used to indicate the level of security associated with the module. The value can range from 0 to any positive integer.

ssoadm attribute: iplanet-am-auth-oath-auth-level

One Time Password Length

Sets the length of the OTP to six digits or longer. The default value is six.

ssoadm attribute: iplanet-am-auth-oath-password-length

Minimum Secret Key Length

The minimum number of hexadecimal characters allowed for the secret key.

ssoadm attribute: iplanet-am-auth-oath-min-secret-key-length

Secret Key Attribute Name

The name of the attribute where the key will be stored in the user profile.

ssoadm attribute: iplanet-am-auth-oath-secret-key-attribute

OATH Algorithm to Use

Select whether to use HOTP or TOTP. You can create an authentication chain to allow for a greater variety of devices. The default value is HOTP.

ssoadm attribute: iplanet-am-auth-oath-algorithm

HOTP Window Size

The window that the OTP device and the server counter can be out of sync. For example, if the window size is 100 and the server's last successful login was at counter value 2, then the server will accept an OTP from device counter 3 to 102. The default value is 100.

ssoadm attribute: iplanet-am-auth-oath-hotp-window-size

Counter Attribute Name

The name of the HOTP attribute where the counter will be stored in the user profile.

ssoadm attribute: iplanet-am-auth-oath-hotp-counter-attribute

Add Checksum Digit

Adds a checksum digit at the end of the HOTP password to verify the OTP was generated correctly. This is in addition to the actual password length. Set this only if your device supports it. The default value is No.

ssoadm attribute: iplanet-am-auth-oath-add-checksum

Truncation Offset

Advanced feature that is device-specific. Let this value default unless you know your device uses a truncation offset. The default value is -1.

ssoadm attribute: iplanet-am-auth-oath-truncation-offset

TOTP Time Step Interval

The time interval for which an OTP is valid. For example, if the time step interval is 30 seconds, a new OTP will be generated every 30 seconds, and an OTP will be valid for 30 seconds. The default value is 30 seconds.

ssoadm attribute: iplanet-am-auth-oath-size-of-time-step

TOTP Time Steps

The number of time step intervals that the system and the device can be off before password resynchronization is required. For example, if the number of TOTP time steps is 2 and the TOTP time step interval is 30 seconds, the server will allow an 89 second clock skew between the client and the server—two 30 second steps plus 29 seconds for the interval in which the OTP arrived. The default value is 2.

ssoadm attribute: iplanet-am-auth-oath-steps-in-window

Last Login Time Attribute

The name of the attribute where both HOTP and TOTP authentication will store information on when a person last logged in.

ssoadm attribute: iplanet-am-auth-oath-last-login-time-attribute-name

The Shared Secret Provider Class

The class that processes the user profile attribute where the user's secret key is stored. The name of this attribute is specified in the Secret Key Attribute Name property.

Default: org.forgerock.openam.authentication.modules.oath.plugins.DefaultSharedSecretProvider

ssoadm attribute: forgerock-oath-sharedsecret-implementation-class

Clock Drift Attribute Name

The user profile attribute where the clock drift is stored. If this field is not specified, then OpenAM does not check for clock drift.

ssoadm attribute: forgerock-oath-observed-clock-drift-attribute-name

Maximum Allowed Clock Drift

The maximum acceptable clock drift before authentication fails. If this value is exceeded, the user must register their device again.

The Maximum Allowed Clock Drift value should be greater than the TOTP Time Steps value.

ssoadm attribute: forgerock-oath-maximum-clock-drift

One Time Password Max Retry

Sets the number of times an OTP may be entered. Minimum is 1, maximum is 10.

Default: 3

ssoadm attribute: forgerock-oath-max-retry

2.5.18. Hints for the OAuth 2.0/OpenID Connect Authentication Module

The OAuth 2.0/OpenID Connect authentication module lets OpenAM authenticate clients of OAuth resource servers. References in this section are to RFC 6749, The OAuth 2.0 Authorization Framework.

Tip

OpenAM provides a wizard for configuring common OAuth 2.0/OpenID Connect authentication providers, such as Facebook, Google, and Microsoft. For more information, see "Configuring Pre-Populated Social Authentication Providers".

If the module is configured to create an account if none exists, then you must provide valid SMTP settings. As part of account creation, the OAuth 2.0/OpenID Connect client authentication module sends the resource owner an email with an account activation code. To send email, OpenAM uses the SMTP settings from the configuration for the OAuth 2.0/OpenID Connect authentication module.

Note

The default settings are for Facebook.

ssoadm service name: sunAMAuthOAuthService

Client id

OAuth client_id as described in section 2.2 of RFC 6749.

ssoadm attribute: iplanet-am-auth-oauth-client-id

Client Secret

OAuth client_secret as described in section 2.3 of RFC 6749.

ssoadm attribute: iplanet-am-auth-oauth-client-secret

Authentication Endpoint URL

URL to the end point handling OAuth authentication as described in section 3.1 of RFC 6749.

Default:https://www.facebook.com/dialog/oauth.

ssoadm attribute: iplanet-am-auth-oauth-auth-service

Access Token Endpoint URL

URL to the end point handling access tokens as described in section 3.2 of RFC 6749.

Default:https://graph.facebook.com/oauth/access_token.

ssoadm attribute: iplanet-am-auth-oauth-token-service

User Profile Service URL

User profile URL that returns profile information in JSON format.

Default:https://graph.facebook.com/me.

ssoadm attribute: iplanet-am-auth-oauth-user-profile-service

Scope

According to The OAuth 2.0 Authorization Framework, a space-separated list of user profile attributes that the client application requires. The list depends on the permissions that the resource owner, such as the end user, grants to the client application.

Some authorization servers use non-standard separators for scopes. Facebook, for example, takes a comma-separated list.

Default: email,read_stream (Facebook example)

ssoadm attribute: iplanet-am-auth-oauth-scope

OAuth2 Access Token Profile Service Parameter name

Access token parameter name.

Default: access_token.

ssoadm attribute: iplanet-am-auth-oauth-user-profile-param

Proxy URL

URL to the /oauth2c/OAuthProxy.jsp file, part of OpenAM.

Default: @SERVER_PROTO@://@SERVER_HOST@:@SERVER_PORT@/@SERVER_URI@/oauth2c/OAuthProxy.jsp.

ssoadm attribute: iplanet-am-auth-oauth-sso-proxy-url

Account Provider

An account provider class.

Default: org.forgerock.openam.authentication.modules.common.mapping.DefaultAccountProvider

ssoadm attribute: org-forgerock-auth-oauth-account-provider

Account Mapper

Class implementing account mapping.

Default: Depends on how the module is created:

If the OAuth2 authentication module is created from the OpenAM console authentication tab of a realm, the default is: org.forgerock.openam.authentication.modules.common.mapping.JsonAttributeMapper.
If the OAuth2 authentication module is created from the OpenAM console Facebook authentication wizard, the default is: org.forgerock.openam.authentication.modules.common.mapping.JsonAttributeMapper|*|facebook-.
If the OAuth2 authentication module is created from the OpenAM console Google authentication wizard, the default is: org.forgerock.openam.authentication.modules.oidc.JwtAttributeMapper|*|Google-.

ssoadm attribute: org-forgerock-auth-oauth-account-mapper

Account Mapper Configuration

Map of OAuth Provider user account attributes used to find the local profile of the authenticated user, with values in the form provider-attr=local-attr.

Default: email=mail and id=facebook-id.

ssoadm attribute: org-forgerock-auth-oauth-account-mapper-configuration

Attribute Mapper

Specifies the list of fully qualified class names for implementations that map attributes from the OAuth 2.0 authorization server or OpenID Connect provider to OpenAM profile attributes.

Default: org.forgerock.openam.authentication.modules.common.mapping.JsonAttributeMapper

Provided implementations are:

org.forgerock.openam.authentication.modules.common.mapping.JsonAttributeMapper

org.forgerock.openam.authentication.modules.oidc.JwtAttributeMapper (can only be used when using the openid scope)

Tip

You can provide string constructor parameters by appending pipe (|) separated values.

For example, the org.forgerock.openam.authentication.modules.oidc.JwtAttributeMapper class can take two constructor parameters: a comma-separated list of attributes and a prefix to apply to their values. Specify these as follows:

org.forgerock.openam.authentication.modules.oidc.JsonAttributeMapper

ssoadm attribute: org-forgerock-auth-oauth-attribute-mapper

Attribute Mapper Configuration

Map of OAuth Provider user account attributes to local user profile attributes, with values in the form provider-attr=local-attr.

Default: first_name=givenname, last_name=sn, name=cn, email=mail, id=facebook-id, first_name=facebook-fname, last_name=facebook-lname, email=facebook-email.

ssoadm attribute: org-forgerock-auth-oauth-attribute-mapper-configuration

Save attributes in the session

When enabled, add the mapped attributes to the session saved.

Valid values: true, false.

Default: true.

ssoadm attribute: org-forgerock-auth-oauth-save-attributes-to-session-flag

Email attribute in OAuth2 Response

Specifies the attribute identifying email address in the response from the profile service in the OAuth provider. This setting is used to send an email address with an activation code for accounts created dynamically.

ssoadm attribute: org-forgerock-auth-oauth-mail-attribute

Create account if it does not exist

When enabled, if the user profile does not exist, optionally retrieve a password and activation code from the user, and then create the profile.

Valid values: true, false.

Default: true.

When the OAuth 2.0/OpenID Connect client is configured to create new accounts, the SMTP settings must also be valid. As part of account creation, the OAuth 2.0/OpenID Connect client authentication module sends the resource owner an email with an account activation code. To send the mail, OpenAM uses the SMTP settings you provide here in the OAuth 2.0/OpenID Connect client configuration.

ssoadm attribute: org-forgerock-auth-oauth-createaccount-flag

Prompt for password setting and activation code

When enabled, the user sets a password, receives an activation code by email. The user must correctly set both in order for the account to be created.

Valid values: true, false.

Default: true.

ssoadm attribute: org-forgerock-auth-oauth-prompt-password-flag

Map to anonymous user

When enabled, map the OAuth authenticated user to the anonymous user you specify. No account is created, even if Create account if it does not exist is enabled.

Valid values: true, false.

Default: false.

ssoadm attribute: org-forgerock-auth-oauth-map-to-anonymous-flag

Anonymous User

Specifies an anonymous user that exists in the current realm.

Default: anonymous.

ssoadm attribute: org-forgerock-auth-oauth-anonymous-user

OAuth 2.0 Provider logout service

Specifies the optional URL of the OAuth Provider.

ssoadm attribute: org-forgerock-auth-oauth-logout-service-url

Logout options

Specifies whether not to log the user out without prompting from the OAuth Provider on logout, to log the user out without prompting, or to prompt the user regarding whether to log out from the OAuth provider.

Valid values: prompt, logout, donotlogout.

Default: prompt.

ssoadm attribute: org-forgerock-auth-oauth-logout-behaviour

Mail Server Gateway implementation class

Class to interact with the mail server.

Default: org.forgerock.openam.authentication.modules.oauth2.DefaultEmailGatewayImpl

ssoadm attribute: org-forgerock-auth-oauth-email-gwy-impl

SMTP host

Host name of the mail server.

Default: localhost.

ssoadm attribute: org-forgerock-auth-oauth-smtp-hostname

SMTP port

SMTP port number for the mail server.

Default: 25.

ssoadm attribute: org-forgerock-auth-oauth-smtp-port

SMTP User Name

If the mail server requires authentication to send mail, specifies the user name.

ssoadm attribute: org-forgerock-auth-oauth-smtp-username

SMTP User Password

If the mail server requires authentication to send mail, specifies the password.

ssoadm attribute: org-forgerock-auth-oauth-smtp-password

SMTP SSL Enabled

When enabled, connect to the mail server over SSL. OpenAM must be able to trust the SMTP server certificate.

Valid values: true, false.

ssoadm attribute: org-forgerock-auth-oauth-smtp-ssl_enabled

SMTP From address

Specifies the message sender address, such as no-reply@example.com.

Default: info@forgerock.com.

ssoadm attribute: org-forgerock-auth-oauth-smtp-email-from

Authentication Level

Sets the authentication level used to indicate the level of security associated with the module. The value can range from 0 to any positive integer.

Default: 0.

ssoadm attribute: iplanet-am-auth-oauth-auth-level

OpenID Connect validation configuration type

Validates the ID Token from the OpenID Connect provider, the module needs either a URL to get the public keys for the provider, or the symmetric key for an ID Token signed with a HMAC-based algorithm.

By default, the configuration type is .well-known/openid-configuration_url. This means the module should retrieve the keys based on information in the OpenID Connect provider configuration document.

You can instead configure the authentication module to validate the ID Token signature with the client secret key you provide, or to validate the ID token with the keys retrieved from the URL to the OpenID Connect provider's JSON Web Key Set.

/oauth2/.well-known/openid-configuration_url (Default)

Retrieve the provider keys based on the information provided in the OpenID Connect Provider Configuration Document.

Specify the URL to the document as the discovery URL.

client_secret

Use the client secret that you specify as the key to validate the ID Token signature according to the HMAC by using the client secret to the decrypt the hash, and then checking that the hash matches the hash of the ID token JWT.

jwk_url

Retrieve the provider's JSON web key set as the URL that you specify.

ssoadm attribute: openam-auth-openidconnect-crypto-context-type

OpenID Connect validation configuration value

Edit this field depending on the Configuration type you specified.

ssoadm attribute: openam-auth-openidconnect-crypto-context-value

Token Issuer

Required when the openid scope is included. Value must match the iss field in the issued ID token. For example, accounts.google.com.

The issuer value MUST be provided when OAuth 2.0 mix-up mitigation is enabled. For more information, see "OAuth 2.0 Mix-Up Mitigation".

ssoadm attribute: openam-auth-openidconnect-issuer-name

Note

Old uses of DefaultAccountMapper are automatically upgraded to the equivalent default implementations.

The following tables show endpoint URLs for OpenAM when configured as an OAuth 2.0 provider. For details, see "Managing OAuth 2.0 Authorization". The default endpoints are for Facebook as the OAuth 2.0 provider.

In addition to the endpoint URLs you can set other fields, like scope and attribute mapping, depending on the provider you use:

Endpoint URLs for OpenAM

OpenAM Field	Details
Authorization Endpoint URL	`/oauth2/authorize` under the deployment URL.^[a] Example: `https://openam.example.com:8443/openam/oauth2/authorize`.
Access Token Endpoint URL	`/oauth2/access_token` under the deployment URL.^[a] Example: `https://openam.example.com:8443/openam/oauth2/access_token`.
User Profile Service URL	`/oauth2/tokeninfo` under the deployment URL. Example: `https://openam.example.com:8443/openam/oauth2/tokeninfo`.
^[a]This OpenAM endpoint can take additional parameters. In particular, you must specify the realm if the OpenAM OAuth 2.0 provider is configured for a subrealm rather than the Top Level Realm (/). For example, if the OAuth 2.0 provider is configured for the realm `/customers`, then the authentication endpoint URL is as follows: `https://openam.example.com:8443/openam/oauth2/authorize?realm=/customers` The `/oauth2/authorize` endpoint can also take `module` and `service` parameters. Use either as described in "Authenticating To OpenAM", where `module` specifies the authentication module instance to use or `service` specifies the authentication chain to use when authenticating the resource owner.

2.5.18.1. OAuth 2.0 Mix-Up Mitigation

OpenAM has added a new property to the OAuth 2.0 authentication module, openam-auth-oauth-mix-up-mitigation-enabled. This OAuth 2.0 mix-up mitigation property controls whether the OAuth 2.0 authentication module carries out additional verification steps when it receives the authorization code from the authorization server. This setting should be only enabled when the authorization server also supports OAuth 2.0 mix-up mitigation.

OAuth 2.0 Mix-Up Mitigation Enabled

Specifies that the client must compare the issuer identifier of the authorization server upon registration with the issuer value returned in the iss response parameter. If they do not match, the client must abort the authorization process. The client must also confirm that the authorization server's response is intended for the client by comparing the client's client identifier to the value of the client_id response parameter.

For more information, see section 4 of OAuth 2.0 Mix-Up Mitigration Draft.

Note

At the time of this release, Facebook, Google, and Microsoft identity providers do not support this draft.

ssoadm attribute: openam-auth-oauth-mix-up-mitigation-enabled

On the OpenAM console, the field Token Issuer must be provided when the OAuth 2.0 mix-up mitigation feature is enabled. The authorization code response will contain an issuer value (iss) that will be validated by the client. When the module is an OAuth2-only module (that is, OIDC is not used), the issuer value needs to be explicitly set in the Token Issuer field, so that the validation can succeed.

Note

Consult with the authorization server's documentation on what value it uses for the issuer field.

2.5.19. Hints for the OpenID Connect id_token bearer Module

The OpenID Connect id_token bearer module lets OpenAM rely on an OpenID Connect 1.0 provider's ID Token to authenticate an end user.

Note

This module validates an OpenID Connect ID token and matches it with a user profile. You should not use this module if you want OpenAM to act as a client in the full OpenID Connect authentication flow.

To provision OpenAM as an OpenID Connect client, you should instead configure an OAuth 2.0/OpenID Connect module. OpenAM provides a wizard to configure an OAuth 2.0/OpenID Connect module that will authenticate against an OpenID Connect 1.0 provider. For more information, see "Configuring Custom Social Authentication Providers".

The OpenID Connect id_token bearer module expects an OpenID Connect ID Token in an HTTP request header. It validates the ID Token, and if successful, looks up the OpenAM user profile corresponding to the end user for whom the ID Token was issued. Assuming the ID Token is valid and the profile is found, the module authenticates the OpenAM user.

You configure the OpenID Connect id_token bearer module to specify how OpenAM gets the information needed to validate the ID Token, which request header contains the ID Token, the issuer identifier for the provider who issued the ID Token, and how to map the ID Token claims to an OpenAM user profile.

Note

The default settings are for Google's provider.

ssoadm service name: amAuthOpenIdConnect

Account provider class

The account provider provides the means to search for and create OpenID Connect users given a set of attributes.

Default: org.forgerock.openam.authentication.modules.common.mapping.DefaultAccountProvider

ssoadm attribute: openam-auth-openidconnect-account-provider-class

OpenID Connect validation configuration type

In order to validate the ID Token from the OpenID Connect provider, the module needs either a URL to get the public keys for the provider, or the symmetric key for an ID Token signed with a HMAC-based algorithm.

By default, the configuration type is .well-known/openid-configuration_url. This means the module should retrieve the keys based on information in the OpenID Connect Provider Configuration Document.

You can instead configure the authentication module to validate the ID Token signature with the client secret key you provide, or to validate the ID token with the keys retrieved from the URL to the OpenID Connect provider's JSON Web Key Set.

.well-known/openid-configuration_url (Default)

Retrieve the provider keys based on the information provided in the OpenID Connect Provider Configuration Document.

Specify the URL to the document as the discovery URL.

client_secret

Use the client secret that you specify as the key to validate the ID Token signature according to the HMAC, using the client secret to the decrypt the hash and then checking that the hash matches the hash of the ID Token JWT.

jwk_url

Retrieve the provider's JSON Web Key Set at the URL that you specify.

ssoadm attribute: openam-auth-openidconnect-crypto-context-type

OpenID Connect validation configuration value

Edit this field depending on the Configuration type you specified.

ssoadm attribute: openam-auth-openidconnect-crypto-context-value

Name of header referencing the ID Token

The module looks for the ID Token in this HTTP request header.

Default: oidc_id_token

ssoadm attribute: openam-auth-openidconnect-header-name

Token Issuer

This corresponds to the expected issue identifier value in the iss of the ID Token.

Default: accounts.google.com

ssoadm attribute: openam-auth-openidconnect-issuer-name

Mapping of jwt attributes to local LDAP attributes

This setting maps OpenID Connect ID Token claims to local user profile attributes, allowing the module to retrieve the user profile based on the ID Token.

In OpenID Connect, an ID Token is represented as a JSON Web Token (JWT). The ID Token section of the OpenID Connect Core 1.0 specification defines a number of claims included in the ID Token for all flows. Additional claims depend on the scopes requested of the OpenID Connect provider.

For each item in the map, the key is the ID Token field name and the value is the local user profile attribute name.

Default: mail=email, uid=sub

ssoadm attribute: openam-auth-openidconnect-local-to-jwt-attribute-mappings

Audience name

The audience name for this OpenID Connect authentication module. Used to check that the ID token received is intended for this module as an audience.

Default: example

ssoadm attribute: openam-auth-openidconnect-audience-name

List of accepted authorized parties

A list of case-sensitive strings and/or URIs from which this authentication module accepts ID tokens. This list is checked against the authorized party claim of the ID token.

Default: AuthorizedPartyExample http://www.example.com/authorized/party

ssoadm attribute: openam-auth-openidconnect-accepted-authorized-parties

Principal Mapper class

The principal mapper matches the OpenID Connect end user with an OpenAM account. The default principal mapper uses the mapping of local attributes to ID Token attributes to find a user profile.

Default: org.forgerock.openam.authentication.modules.oidc.JwtAttributeMapper

ssoadm attribute: openam-auth-openidconnect-principal-mapper-class

2.5.21. Hints for the RADIUS Authentication Module

The Remote Authentication Dial-In User Service (RADIUS) module lets OpenAM authenticate users against RADIUS servers.

ssoadm service name: iPlanetAMAuthRadiusService

Primary Radius Servers, Secondary Radius Servers

Specify the IP address or fully qualified domain name of one or more primary RADIUS server. The default is 127.0.0.1 (localhost loopback), and optionally, set secondary servers.

ssoadm attribute: primary is iplanet-am-auth-radius-server1; secondary is iplanet-am-auth-radius-server2

When authenticating users from a directory server that is remote to OpenAM, set the primary values, and optionally, the secondary server values. Primary servers have priority over secondary servers.

Both properties take more than one value; thus, allowing more than one primary or secondary remote server, respectively. Assuming a multi-data center environment, OpenAM determines priority within the primary and secondary remote servers, respectively, as follows:

Every RADIUS server that is mapped to the current OpenAM instance has highest priority.
Every RADIUS server that was not specifically mapped to a given OpenAM instance has the next highest priority.
RADIUS servers that are mapped to different OpenAM instances have the lowest priority.

Shared Secret

Specify the shared secret for RADIUS authentication. The shared secret should be as secure as a well-chosen password.

ssoadm attribute: iplanet-am-auth-radius-secret

Port Number

Specify the RADIUS server port.

Default is 1645.

ssoadm attribute: iplanet-am-auth-radius-server-port

Timeout

Specify how many seconds to wait for the RADIUS server to respond. The default value is 3 seconds.

ssoadm attribute: iplanet-am-auth-radius-timeout

Health Check Interval

Used for failover. Specify how often OpenAM performs a health check on a previously unavailable RADIUS server by sending an invalid authentication request.

Default: 5 minutes

ssoadm attribute: openam-auth-radius-healthcheck-interval

Authentication Level

Sets the authentication level used to indicate the level of security associated with the module. The value can range from 0 to any positive integer.

ssoadm attribute: iplanet-am-auth-radius-auth-level

2.5.22. Hints for the SAE Authentication Module

The Secure Attribute Exchange (SAE) module lets OpenAM authenticate a user who has already authenticated with an entity that can vouch for the user to OpenAM, so that OpenAM creates a session for the user. This module is useful in virtual federation, where an existing entity instructs the local OpenAM instance to use federation protocols to transfer authentication and attribute information to a partner application.

ssoadm attribute: sunAMAuthSAEService

Authentication Level

Sets the authentication level used to indicate the level of security associated with the module. The value can range from 0 to any positive integer.

ssoadm service name: sunAMAuthSAEAuthLevel

2.5.23. Hints for the SAML2 Authentication Module

The SAML2 authentication module lets administrators integrate SAML v2.0 single sign-on and single logout into an OpenAM authentication chain.

You use the SAML2 authentication module when deploying SAML v2.0 single sign-on in integrated mode. In addition to configuring SAML2 authentication module properties, integrated mode deployment requires that you make several changes to service provider configurations. Before attempting to configure a SAML2 authentication module instance, review "Implementing SAML v2.0 Single Sign-On in Integrated Mode" and make sure that you have made any required changes to your service provider configuration.

ssoadm service name: iPlanetAMAuthSAML2Service

Authentication Level

Sets the authentication level used to indicate the level of security associated with the module. The value can range from 0 to any positive integer.

ssoadm attribute: iplanet-am-auth-saml2-auth-level

IdP Entity ID

The identity provider (IdP) for authentication requests to this module. Specify the name of a SAML v2.0 entity provider that is defined in the SAML2 authentication module's realm.

You can find configured entity providers in the OpenAM console under Federation. The Realm column identifies the realm in which an entity provider has been configured.

ssoadm attribute: forgerock-am-auth-saml2-entity-name

SP MetaAlias

Specifies the local alias for the service provider (SP).

For service providers configured in the Top Level Realm, use the format /SP Name.

For service providers configured in subrealms, use the format /Realm Name/SP Name.

You can find the local aliases for entity providers in the OpenAM console under Federation > Entity Provider Name > Services.

ssoadm attribute: forgerock-am-auth-saml2-meta-alias

Allow IdP to Create NameID

Specifies whether the IdP should create a new identifier for the authenticating user if none exists.

A value of true permits the IdP to create an identifier for the authenticating user if none exists. A value of false indicates a request to constrain the IdP from creating an identifier.

For detailed information, see the section on the AllowCreate property in SAML Version 2.0 Errata 05.

Default: true

ssoadm attribute: forgerock-am-auth-saml2-allow-create

Linking Authentication Chain

Specifies an authentication chain that is invoked when a user requires authentication to the SP.

Authentication to the SP is required when the authentication module running on the SP is unable to determine the user's identity based on the assertion received from the IdP. In this case, the linking authentication chain is invoked to allow the end user to link their remote and local accounts.

ssoadm attribute: forgerock-am-auth-saml2-login-chain

Comparison Type

Specifies a comparison method to evaluate authentication context classes or statements. The value specified in this property overrides the value set in the SP configuration under Federation > Entity Providers > Service Provider Name > Assertion Content > Authentication Context > Comparison Type.

Valid comparison methods are exact, minimum, maximum, or better.

For more information about the comparison methods, see the section on the <RequestedAuthnContext> element in Assertions and Protocols for the OASIS Security Assertion Markup Language (SAML) V2.0.

Default: exact

ssoadm attribute: forgerock-am-auth-saml2-auth-comparison

Authentication Context Class Reference

Specifies one or more URIs for authentication context classes to be included in the SAML request. Authentication context classes are unique identifiers for an authentication mechanism. The SAML v2.0 protocol supports a standard set of authentication context classes, defined in Authentication Context for the OASIS Security Assertion Markup Language (SAML) V2.0. In addition to the standard authentication context classes, you can specify customized authentication context classes.

Any authentication context class that you specify in this field must be supported for the service provider. To determine which authentication context classes are supported, locate the list of authentication context classes that are available to the SP under Federation > Entity Providers > Service Provider Name > Assertion Content > Authentication Context, and then review the values in the Supported column.

When specifying multiple authentication context classes, use the | character to separate the classes.

Example value: urn:oasis:names:tc:SAML:2.0:ac:classes:Password|urn:oasis:names:tc:SAML:2.0:ac:classes:TimesyncToken

ssoadm attribute: forgerock-am-auth-saml2-authn-context-class-ref

Authentication Context Declaration Reference

Specifies one or more URIs that identify authentication context declarations.

This field is optional.

When specifying multiple URIs, use the | character to separate the URIs.

For more information, see the section on the <RequestedAuthnContext> element in Assertions and Protocols for the OASIS Security Assertion Markup Language (SAML) V2.0.

ssoadm attribute: forgerock-am-auth-saml2-authn-context-decl-ref

Request Binding

Specifies the format used to send the authentication request from the SP to the IdP.

Valid values are HTTP-Redirect and HTTP-POST.

Default: HTTP-Redirect

ssoadm attribute: forgerock-am-auth-saml2-req-binding. When using the ssoadm command, set this attribute's value to urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect or urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST.

Response Binding

Specifies the format used to send the response from the IdP to the SP.

A value of HTTP-POST indicates that the HTTP POST binding with a self-submitting form should be used in assertion processing. A value of HTTP-Artifact indicates that the HTTP Artifact binding should be used.

Default: HTTP-Artifact

ssoadm attribute: forgerock-am-auth-saml2-binding. When using the ssoadm command, set this attribute's value to urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Artifact or urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST.

Force IdP Authentication

Specifies whether the IdP should force authentication or can reuse existing security contexts.

A value of true indicates that the IdP should force authentication. A value of false indicates that the IdP can reuse existing security contexts.

ssoadm attribute: forgerock-am-auth-saml2-force-authn

Passive Authentication

Specifies whether the IdP should use passive authentication or not. Passive authentication requires the IdP to only use authentication methods that do not require user interaction. For example, authenticating using an X.509 certificate.

A value of true indicates that the IdP should authenticate passively. A value of false indicates that the IdP should not authenticate passively.

ssoadm attribute: forgerock-am-auth-saml2-is-passive

NameID Format

Specifies a SAML name ID format to be requested in the SAML authentication request.

Default: urn:oasis:names:tc:SAML:2.0:nameid-format:persistent

ssoadm attribute: forgerock-am-auth-saml2-name-id-format

Single Logout Enabled

Specifies whether OpenAM should attempt to log out of the user's IdP session during session logout.

When enabling SAML v2.0 single logout, you must also configure the post-authentication processing class for the authentication chain containing the SAML2 authentication module to org.forgerock.openam.authentication.modules.saml2.SAML2PostAuthenticationPlugin.

For more information about configuring single logout when implementing SAML v2.0 federation using the SAML2 authentication module, see "Configuring Single Logout in an Integrated Mode Implementation".

Default: false

ssoadm attribute: forgerock-am-auth-saml2-slo-enabled

Single Logout URL

Specifies the URL to which the user is forwarded after successful IdP logout. Configure this property only if you have enabled SAML v2.0 single logout by selecting the Single Logout Enabled check box.

ssoadm attribute: forgerock-am-auth-saml2-slo-relay

2.5.24. Hints for the Scripted Authentication Module

This section covers what to configure for scripted authentication modules.

A scripted authentication module runs scripts to authenticate a user. The configuration for the module can hold two scripts, one to include in the web page run on the client user-agent, another to run in OpenAM on the server side.

The client-side script is intended to retrieve data from the user-agent. This must be in a language the user-agent, such as JavaScript, even if the server-side script is written in Groovy.

The server-side script is intended to handle authentication.

Scripts are stored not as files, but instead as OpenAM configuration data. This makes it easy to update a script on one OpenAM server, and then to allow replication to copy it to other servers. You can manage the scripts through OpenAM console, where you can write them in the text boxes provided or upload them from files.

You can also upload scripts and associate them with a scripted authentication module by using the ssoadm command.

The following example shows how to upload a server-side script from a file, create a scripted authentication module, and then associate the uploaded script with the new module.

#
# Upload a server-side script from a script file, myscript.groovy.
#

ssoadm create-sub-cfg \
    --realm / \
    --adminid amadmin \
    --password-file /tmp/pwd.txt \
    --servicename ScriptingService \
    --subconfigname scriptConfigurations/scriptConfiguration \
    --subconfigid myScriptId \
    --attributevalues \
        "name=My Scripted Auth Module Script" \
        "script-file=myscript.groovy" \
        "context=AUTHENTICATION_SERVER_SIDE" \
        "language=GROOVY"
#
# Create a scripted authentication module, myScriptedAuthModule.
#

ssoadm create-auth-instance \
    --realm / \
    --adminid amadmin \
    --password-file /tmp/pwd.txt \
    --authtype Scripted \
    --name myScriptedAuthModule

#
# Associate the script with the auth module, and disable client-side scripts.
#

ssoadm update-auth-instance \
    --realm / \
    --adminid amadmin \
    --password-file /tmp/pwd.txt \
    --name myScriptedAuthModule \
    --attributevalues \
        "iplanet-am-auth-scripted-server-script=myScriptId" \
        "iplanet-am-auth-scripted-client-script-enabled=false"

If you have multiple separate sets of client-side and server-side scripts, then configure multiple modules, one for each set of scripts.

For details on writing authentication module scripts, see "Default Server-side Authentication Script" in the Developer's Guide.

ssoadm service name: iPlanetAMAuthScriptedService

Use the following settings at the realm level when configuring an individual scripted authentication module, in OpenAM console under Realms > Realm Name > Authentication > Modules.

Client-Side Script Enabled

When selected, include the specified client-side script in the login page to be executed on the user-agent prior to the server-side script.

ssoadm attribute: iplanet-am-auth-scripted-client-script-enabled

Client-Side Script

The ID of the script to include in the login page. This script is run on the user-agent prior to the server-side script.

This script must be written in a language the user-agent can interpret, such as JavaScript, even if the server-side script is written in Groovy.

ssoadm attribute: iplanet-am-auth-scripted-client-script

Server Side Script

The ID of the script to run in OpenAM after the client-side script has completed.

ssoadm attribute: iplanet-am-auth-scripted-server-script

Authentication Level

Sets the authentication level used to indicate the level of security associated with the scripted authentication module.

The value can range from 0 to any positive integer.

ssoadm attribute: iplanet-am-auth-scripted-auth-level

In the OpenAM console, navigate to Configure > Global Services, click Scripting, click the script type in the Instances table, and then click Engine Configuration.

Note

Only server-side script context types have engine configurations.

On the Engine Configuration page, configure the following settings for the scripting engine of the selected type:

Server-side Script Timeout

The maximum execution time any individual script should take on the server (in seconds). OpenAM terminates scripts which take longer to run than this value.

ssoadm attribute: serverTimeout

Core thread pool size

The initial number of threads in the thread pool from which scripts operate. OpenAM will ensure the pool contains at least this many threads.

ssoadm attribute: coreThreads

Maximum thread pool size

The maximum number of threads in the thread pool from which scripts operate. If no free thread is available in the pool, OpenAM creates new threads in the pool for script execution up to the configured maximum.

ssoadm attribute: maxThreads

Thread pool queue size

The number of threads to use for buffering script execution requests when the maximum thread pool size is reached.

ssoadm attribute: queueSize

Thread idle timeout (seconds)

Length of time (in seconds) for a thread to be idle before OpenAM terminates created threads. If the current pool size contains the number of threads set in Core thread pool size, then idle threads will not be terminated, maintaining the initial pool size.

ssoadm attribute: idleTimeout

Java class whitelist

Specifies the list of class name patterns allowed to be invoked by the script. Every class accessed by the script must match at least one of these patterns.

You can specify the class name as-is or use a regular expression.

ssoadm attribute: whiteList

Java class blacklist

Specifies the list of class name patterns that are NOT allowed to be invoked by the script. The blacklist is applied AFTER the whitelist to exclude those classes. Access to a class specified in both the whitelist and the blacklist will be denied.

You can specify the class name to exclude as-is or use a regular expression.

ssoadm attribute: blackList

Use system SecurityManager

If enabled, OpenAM will make a call to System.getSecurityManager().checkPackageAccess(...) for each class that is accessed. The method throws SecurityException if the calling thread is not allowed to access the package.

Note

This feature only takes effect if the security manager is enabled for the JVM.

ssoadm attribute: useSecurityManager

2.5.25. Hints For the SecurID Authentication Module

The SecurID module lets OpenAM authenticate users with RSA Authentication Manager software and RSA SecurID authenticators.

Important

To use the SecurID authentication module, you must first build an OpenAM war file that includes the supporting library. For more information, see "Enabling RSA SecurID Support" in the Installation Guide.

ssoadm service name: iPlanetAMAuthSecurIDService

ACE/Server Configuration Path

Specify the directory where the SecurID ACE/Server sdconf.rec file is located, which by default is expected under the OpenAM configuration directory, such as $HOME/openam/openam/auth/ace/data. The directory must exist before OpenAM can use SecurID authentication.

ssoadm attribute: iplanet-am-auth-securid-server-config-path

Authentication Level

Sets the authentication level used to indicate the level of security associated with the module. The value can range from 0 to any positive integer.

ssoadm attribute: iplanet-am-auth-securid-auth-level

2.5.26. Hints for the Windows Desktop SSO Authentication Module

The Windows Desktop SSO module uses Kerberos authentication. The user presents a Kerberos token to OpenAM through the Simple and Protected GSS-API Negotiation Mechanism (SPNEGO) protocol. The Windows Desktop SSO authentication module enables desktop single sign on such that a user who has already authenticated with a Kerberos Key Distribution Center can authenticate to OpenAM without having to provide the login information again. Users might need to set up Integrated Windows Authentication in Internet Explorer or Microsoft Edge to benefit from single sign on when logged on to a Windows desktop.

Warning

If you are using the Windows Desktop SSO module as part of an authentication chain and Windows Desktop SSO fails, you may no longer be able to POST data to non-NTLM-authenticated web sites. For information on a possible workaround, see Microsoft knowledge base article KB251404.

ssoadm service name: iPlanetAMAuthWindowsDesktopSSOService

Service Principal

Specify the Kerberos principal for authentication in the following format.

HTTP/host.domain@dc-domain-name

Here, host and domain correspond to the host and domain names of the OpenAM instance, and dc-domain-name is the domain name of the Windows Kerberos domain controller server. The dc-domain-name can differ from the domain name for OpenAM.

You set up the account on the Windows domain controller, creating a computer account for OpenAM and associating the new account with a service provider name.

ssoadm attribute: iplanet-am-auth-windowsdesktopsso-principal-name

Keytab File Name

Specify the full path of the keytab file for the Service Principal. You generate the keytab file using the Windows ktpass utility.

ssoadm attribute: iplanet-am-auth-windowsdesktopsso-keytab-file

Kerberos Realm

Specify the Kerberos Key Distribution Center realm. For the Windows Kerberos service, this is the domain controller server domain name.

ssoadm attribute: iplanet-am-auth-windowsdesktopsso-kerberos-realm

Kerberos Server Name

Specify the fully qualified domain name of the Kerberos Key Distribution Center server, such as that of the domain controller server.

ssoadm attribute: iplanet-am-auth-windowsdesktopsso-kdc

Return Principal with Domain Name

When enabled, OpenAM automatically returns the Kerberos principal with the domain controller's domain name during authentication.

ssoadm attribute: iplanet-am-auth-windowsdesktopsso-returnRealm

Authentication Level

Sets the authentication level used to indicate the level of security associated with the module. The value can range from 0 to any positive integer.

ssoadm attribute: iplanet-am-auth-windowsdesktopsso-auth-level

Trusted Kerberos realms

List of trusted Kerberos realms for user Kerberos tickets. If realms are configured, then Kerberos tickets are only accepted if the realm part of the user principal name of the user's Kerberos ticket matches a realm from the list.

ssoadm attribute: iplanet-am-auth-windowsdesktopsso-kerberos-realms-trusted

Search for the user in the realm

Validates the user against the configured data stores. If the user from the Kerberos token is not found, authentication will fail. If an authentication chain is set, the user is able to authenticate through another module. This search uses the Alias Search Attribute Name from the core realm attributes. See "Core Authentication Attributes - User Profile".

ssoadm attribute: iplanet-am-auth-windowsdesktopsso-lookupUserInRealm

Note

Sending a ForceAuth=true authentication request when the user has a valid session may result in failed authentication unless the request hits the authoritative OpenAM server.

Authentication cross-talk requires an authorization header in the request that grants the new server access to the user's authentication token.

To ensure the authorization headers are included in the cross-talk requests, perform the following steps:

Navigate to Deployment > Servers > Server Name > Advanced.
Modify the following advanced properties:
- Add the WWW-Authenticate value to the openam.retained.http.headers property.
- Add the Authorization value to the openam.retained.http.request.headers property.
Save your changes.

2.5.27. Hints for the Windows NT Authentication Module

The Windows NT module lets OpenAM authenticate against a Microsoft Windows NT server.

This module requires that you install a Samba client in a bin directory under the OpenAM configuration directory, such as $HOME/openam/openam/bin.

ssoadm service name: iPlanetAMAuthNTService

Authentication Domain

Specify the Windows domain name to which users belong.

ssoadm attribute: iplanet-am-auth-nt-domain

Authentication Host

Specify the NetBIOS name of the Windows NT host to which to authenticate users.

ssoadm attribute: iplanet-am-auth-nt-host

Samba Configuration File Name

Specify the full path to the Samba configuration file.

ssoadm attribute: iplanet-am-auth-samba-config-file-name

Authentication Level

Sets the authentication level used to indicate the level of security associated with the module. The value can range from 0 to any positive integer.

ssoadm attribute: iplanet-am-auth-nt-auth-level

2.6. Configuring Authentication Chains

Once you have configured authentication modules and added the modules to the list of module instances, you can configure authentication chains. Authentication chains let you handle cases where alternate modules or credentials are needed. If you need modules in the chain to share user credentials, then set options for the module.

Tip

OpenAM provides a wizard for configuring authentication providers, including Facebook, Google, and Microsoft. The wizard creates a relevant authentication chain as part of the process. For more information, see "Configuring Social Authentication".

To Create an Authentication Chain

On the Realms page of the OpenAM console, click the realm for which to create the authentication chain.
On the Realm Overview page, click Authentication in the left-hand menu, and then click Chains.
On the Authentication Chains page, click Add Chain. Enter new chain name, and then click Create.
On the New Module dialog, select the authentication module in the chain, and then assign appropriate criteria (Optional, Required, Requisite, Sufficient) as described in "About Authentication in OpenAM". You can also configure where OpenAM redirects the user upon successful and failed authentication, and plug in your post-authentication processing classes as necessary.
(Optional) If you need modules in the chain to share user credentials, consider the following available options. Enter the key and its value, and then click Plus (+). When you finish entering the options, click OK.
iplanet-am-auth-store-shared-state-enabled
Set iplanet-am-auth-store-shared-state-enabled=true to store the credentials captured by this module in shared state. This enables subsequent modules in the chain to access the credentials captured by this module. The shared state is cleared when the user successfully authenticates, quits the chain, or logs out.
Default: true
iplanet-am-auth-shared-state-enabled
Set iplanet-am-auth-shared-state-enabled=true to allow this module to access the credentials, such as user name and password, that have been stored in shared state by previous modules in the authentication chain.
Default: false
iplanet-am-auth-shared-state-behavior-pattern
Set iplanet-am-auth-shared-state-behavior-pattern=tryFirstPass to try authenticating with the username and password stored in shared state. If authentication fails, OpenAM displays the login screen of this module for the user to re-enter their credentials.
Set iplanet-am-auth-shared-state-behavior-pattern=useFirstPass to prevent the user from entering the username and password twice during authentication. Typically, you set the property to useFirstPass for all modules in the chain except the first module. If authentication fails, then the module fails.
Default: tryFirstPass
For example, consider a chain with two modules sharing credentials according to the following settings: The first module in the chain has the option iplanet-am-auth-store-shared-state-enabled=true, and criteria REQUIRED.
Authentication Chain First Module

The second module in the chain has options iplanet-am-auth-shared-state-enabled=true, iplanet-am-auth-shared-state-behavior-pattern=useFirstPass with criteria REQUIRED.
Authentication Chain Second Module
Click Save Changes.
The following authentication sequence would occur: The user enters their credentials for the first module and successfully authenticates. The first module shares the credentials with the second module, successfully authenticating the user without prompting again for their credentials, unless the credentials for the first module do not successfully authenticate the user to the second module.

To Select the Default Chain

Before you select the default chain for users, and especially for administrators, test the authentication chain first. For example, http://openam.example.com:8080/openam/UI/Login?service=NewChain. If you cannot log in, then go back and fix the authentication chain's configuration before making it the default.

On the Realms page of the OpenAM console, click the realm for which to set the default authentication chain.
(Optional) If necessary, on the Authentication tab page for the realm, adjust the drop-down lists for Organization Authentication Configuration and Administrator Authentication Configuration to the appropriate authentication chains.
The Organization Authentication Configuration serves when users access /openam/UI/Login.
The Administrator Authentication Configuration serves when users access /openam/console.
You can set these independently to separate administrative login from user login. For example, you can change the default user chain, but leave the default administrator chain as is to avoid locking yourself out as administrator. By default, amadmin can log in at /openam/UI/Login. You can change that for your deployment.
Save your work.

2.7. Post-Authentication Plugins

A post-authentication plugin provides custom processing at the end of the authentication process and immediately before the subject is authenticated. Post authentication plugins are often used in conjunction with policy agents. The post-authentication plugin sets custom session properties, and then the policy agent injects the custom properties into the request header to the protected application. Other common uses of post authentication plugins include setting cookies and session variables. You can configure a post authentication plugin for individual realms or for an authentication chain.

Important

Implementing a post authentication processing plugin in the top level realm can have unexpected effects. OpenAM invokes a post authentication plugin when the plugin is configured in the top level realm, which will then run for all types of authentication during startup, including user logins and internal administrative logins. The best practice first and foremost is to configure end-users to only log into subrealms, while administrators only log into the top level realm. If you need to execute the post authentication plugin for administrative logins, make sure that the plugin can also handle internal authentications.

An alternate solution is to configure the post authentication plugin on a per authentication chain basis, which can be configured separately for user logins or administrative logins.

Configure a post authentication plugin for a realm or authentication chain as follows:

Realm. You can configure a post authentication plugin for all users in a specific realm using the OpenAM console by navigating to Realms > Realm Name > Authentication > Settings > Post Authentication Processing > Authentication Post Processing Classes. Add the required post authentication class.
You can also configure the post authentication plugin for a realm using an ssoadm command, as follows:
```
$ ./ssoadm set-svc-attrs -s iPlanetAMAuthService -e realm-name \
  -u adminID -f passwordfile \
  -a iplanet-am-auth-post-login-process-class=post-auth-class
```
Authentication Chain. You can configure a post authentication plugin for a specific authentication chain on the OpenAM console by navigating to Realms > realm-name > Authentication > Chains > chain-name > Settings > Post Authentication Processing Class. Add the post authentication class.
Using ssoadm, run the following:
```
$ ./ssoadm update-auth-cfg-props -e realm-name -m auth-chain -u adminID -f passwordfile \
  -a iplanet-am-auth-post-login-process-class=post-auth-class
```

Standard Post-Authentication Plugins

OpenAM provides some post-authentication plugins as part of the standard product delivery.

Class name: org.forgerock.openam.authentication.modules.adaptive.Adaptive

The adaptive authentication plugin serves to save cookies and profile attributes after successful authentication.

Add it to your authentication chains that use the adaptive authentication module configured to save cookies and profile attributes.

Class name: org.forgerock.openam.authentication.modules.common.JaspiAuthLoginModulePostAuthenticationPlugin

The Java Authentication Service Provider Interface (JASPI) post authentication plugin initializes the underlying JASPI ServerAuth module.

JASPI defines a standard service provider interface (SPI) where developers can write message level authentication agents for Java EE containers on either the client side or the server side.

Class name: org.forgerock.openam.authentication.modules.oauth2.OAuth2PostAuthnPlugin

The OAuth 2.0 post-authentication plugin builds a global logout URL used by /oauth2c/OAuthLogout.jsp after successful OAuth 2.0 client authentication. This logs the resource owner out with the OAuth 2.0 provider when logging out of OpenAM.

Before using this plugin, configure the OAuth 2.0 authentication module with the correct OAuth 2.0 Provider logout service URL, and set the Logout options to Log out or Prompt. This plugin cannot succeed unless those parameters are correctly set.

Sometimes OAuth 2.0 providers change their endpoints, including their logout URLs. When using a provider like Facebook, Google, or MSN, make sure you are aware when they change their endpoint locations so that you can change your client configuration accordingly.

Class name: org.forgerock.openam.authentication.plugins.AccountExpirePlugin

The account expiration post-authentication plugin sets an account expiration date after successful authentication. OpenAM uses this to prevent expired accounts from being used to authenticate.

The default of 30 days can be changed using the advanced OpenAM server property, org.forgerock.openam.authentication.accountExpire.days.

Class name: org.forgerock.openam.authentication.modules.saml2.SAML2PostAuthenticationPlugin

The SAML v2.0 post-authentication plugin that gets activated for single logout. Supports HTTP-Redirect for logout-sending messages only.

Set the post-authentication processing class for the authentication chain that contains the SAML v2.0 authentication module.

Class name: org.forgerock.openam.authentication.modules.persistentcookie.PersistentCookieAuthModule

The Persistent Cookie Authentication Module provides logic for persistent cookie authentication in OpenAM. It makes use of the JASPI JwtSession module to create and verify the persistent cookie.

If necessary, you can also write your own custom post-authentication plugin as described in "Creating a Post Authentication Plugin" in the Developer's Guide.

2.8. Authenticating To OpenAM

This section explains how to connect to OpenAM for user authentication by adding parameters to the login URL when testing your configuration.

2.8.1. Authenticating to OpenAM Using the XUI

When using the XUI, the base URL to authenticate to OpenAM points to /XUI/#login under the deployment URL, such as http://openam.example.com:8080/openam/XUI/#login.

The base URL to log out is similar, for example, http://openam.example.com:8080/openam/XUI/#logout/.

2.8.1.1. Specifying the Realm in the Login URL

You can specify the realm that you want to log in to as follows:

Options for Specifying the Realm in XUI Logon URLs

Description	Example URL
As part of the URL path	`http://openam.example.com:8080/openam/XUI/ #login/myrealm`
As a URL parameter	`http://openam.example.com:8080/openam/XUI/ #login&realm=/myrealm`
As a parameter of `XUI`	`http://openam.example.com:8080/openam/XUI/ ?realm=/myrealm#login`
As the fully-qualified host name in the URL, if the realm has a DNS alias	`http://myRealm.example.com:8080/openam/XUI/ #login`

2.8.1.2. Example XUI Login URLs

Use any of the options listed in "OpenAM Authentication Parameters" as URL parameters. The following are example URLs with parameters:

Example XUI Logon URLs

Description	Example URL
Log in to the top level realm, requesting that OpenAM display the user interface in German.	`http://openam.example.com:8080/openam/XUI/ #login&locale=de`
Log in to the `myRealm` realm, requesting that OpenAM display the user interface in German.	`http://openam.example.com:8080/openam/XUI/ #login/myRealm&locale=de`
Log in to the `myRealm` realm using the `HOTPChain` authentication chain, requesting that OpenAM display the user interface in German.	`http://openam.example.com:8080/openam/XUI/ #login/myRealm&locale=de&service=HOTPChain`

2.8.2. Authenticating to OpenAM Using the Classic UI

When using the classic UI, the base URL to authenticate to OpenAM points to /UI/Login under the deployment URL, such as http://openam.example.com:8080/openam/UI/Login.

The base URL to log out is similar, for example, http://openam.example.com:8080/openam/UI/Logout.

2.8.2.1. Specifying the Realm in the Login URL

You can specify the realm that you want to log in to as follows:

Options for Specifying the Realm in Classic UI Logon URLs

Description	Example URL
Use the `&realm` URL parameter to specify the realm that you want to log in to.	`http://openam.example.com:8080/openam/UI/ Login?realm=myRealm`
If the realm has a DNS alias, use it to reference the realm.	`http://myRealm.example.com:8080/openam/UI/ Login`

2.8.2.2. Example Login URLs

Use any of the options listed in "OpenAM Authentication Parameters" as URL parameters. The following are example URLs with parameters:

Example Classic UI Logon URLs

Description	Example URL
Log in to the top level realm, requesting that OpenAM display the user interface in German.	`http://openam.example.com:8080/openam/UI/ Login?locale=de`
Log in to the `myRealm` realm, requesting that OpenAM display the user interface in German.	`http://openam.example.com:8080/openam/UI/ Login?realm=myRealm&locale=de`
Log in to the `myRealm` realm using the `HOTPChain` authentication chain, requesting that OpenAM display the user interface in German.	`http://openam.example.com:8080/openam/UI/ Login?realm=myRealm&locale=de&service=HOTPChain`

2.8.3. OpenAM Authentication Parameters

OpenAM accepts the following parameters in the query string. With the exception of IDToken parameters, use no more than one occurrence of each.

arg=newsession

Request that OpenAM end the user's current session and start a new session.

authlevel

Request that OpenAM authenticate the user using a module with at least the specified authentication level that you have configured.

As this parameter determines authentication module selection, do not use it with module, service, or user.

ForceAuth

If ForceAuth=true, request that OpenAM force the user to authenticate even if they already has a valid session. On successful authentication, OpenAM updates the session token.

goto

On successful authentication, or successful logout, request that OpenAM redirect the user to the specified location. Values must be URL-encoded.

gotoOnFail

On authentication failure, request that OpenAM redirect the user to the specified location. Values must be URL-encoded.

IDToken1, IDToken2, ..., IDTokenN

Pass the specified credentials as IDToken parameters in the URL. The IDToken credentials map to the fields in the login page for the authentication module, such as IDToken1 as user ID and IDToken2 as password for basic user name, password authentication. The order depends on the callbacks in login page for the module; IDTokenN represents the N^th callback of the login page.

locale

Request that OpenAM display the user interface in the specified, supported locale. Locale can also be set in the user's profile, in the HTTP header from her browser, configured in OpenAM, and so on.

module

Request that OpenAM use the authentication module instance as configured for the realm where the user is authenticating.

As this parameter determines authentication module selection, do not use it with authlevel, service, or user.

realm

Request that OpenAM authenticate the user to the specified realm.

service

Request that OpenAM authenticate the user with the specified authentication chain.

As this parameter determines authentication module selection, do not use it with authlevel, module, or user.

user

Request that the user, specified by their OpenAM universal ID, authenticates according to the chain specified by the User Authentication Configuration property in their user profile. You can configure this property for a user under Realms > Realm Name > Subjects > User > User Name.

In order for the User Authentication Configuration property to appear in user profiles, the iplanet-am-user-service object class must contain the iplanet-am-user-auth-config attribute in the identity repository schema. The default identity repository schemas provided with OpenAM include this object class and attribute. See "Preparing an External Identity Repository" in the Installation Guide for information about identity repository schema.

As this parameter determines authentication module selection, do not use it with authlevel, module, or service.

2.9. Multi-Factor Authentication

This section explains multi-factor authentication in OpenAM. Multi-factor authentication requires that users provide more than one form of credential when logging in. A very common multi-factor authentication scenario is for users to be prompted to submit a user ID and password, and then to be prompted to submit a one-time password generated by an authenticator app on their mobile phone.

This section provides general information about multi-factor authentication, describes how end users authenticate using multi-factor authentication, and covers how administrators implement and support multi-factor authentication.

2.9.1. About Multi-Factor Authentication

Multi-factor authentication is an authentication technique that requires users to provide multiple forms of identification when logging in to OpenAM. Multi-factor authentication provides a more secure method for users to access their accounts with the help of a device.

Note that the word device is used in this section to mean a piece of equipment that can display a one-time password or that supports push notifications using protocols supported by OpenAM multi-factor authentication. Devices are most commonly mobile phones with authenticator apps that support the OATH protocol or push notifications, but could also include other equipment.

The following is an example scenario of multi-factor authentication in OpenAM:

An OpenAM administrator configures an authentication chain with the Data Store and ForgeRock Authenticator (OATH) authentication modules.
An end user authenticates to OpenAM using that authentication chain.
OpenAM prompts the user to enter the user ID and password as required by the Data Store authentication module—the first factor in multi-factor authentication.
If the user ID and password were correct, OpenAM prompts the user to obtain a one-time password.
The user runs an authenticator app on a mobile phone that generates and displays a one-time password.
The user provides the one-time password to OpenAM to successfully complete authentication—the second factor in multi-factor authentication.

Administrators set up multi-factor authentication by creating authentication chains with two or more authentication modules. The initial module in the chain defines the first authentication module for multi-factor authentication. In the preceding scenario, the first authentication module is the Data Store authentication module. Subsequent modules in the chain define the additional factors required to log in, for example the ForgeRock Authenticator (OATH) or ForgeRock Authenticator (Push) authentication modules.

OpenAM supports the Open AuTHentication (OATH) protocols, and also push notification for multi-factor authentication.

2.9.1.1. About Open AuTHentication (OATH)

The ForgeRock Authenticator (OATH) module supports HMAC one-time password (HOTP) and time-based one-time password (TOTP) authentication as defined in the OATH standard protocols for HOTP (RFC 4226) and TOTP (RFC 6238). Both HOTP and TOTP authentication require an OATH-compliant device that can provide the password.

HOTP authentication generates the one-time password every time the user requests a new password on their device. The device tracks the number of times the user requests a new one-time password with a counter. The one-time password displays for a period of time you designate in the setup, so the user may be further in the counter on their device than on their account.

OpenAM will resynchronize the counter when the user finally logs in. To accommodate this, you set the number of passwords a user can generate before their device cannot be resynchronized. For example, if you set the number of HOTP Window Size to 50 and someone presses the button 30 times on the user's device to generate a new password, the counter in OpenAM will review the passwords until it reaches the one-time password entered by the user. If someone presses the button 51 times, you will need to reset the counter to match the number on the device's counter before the user can login to OpenAM. HOTP authentication does not check earlier passwords, so if the user attempts to reset the counter on their device, they will not be able to login until you reset the counter in OpenAM to match their device. For more information, see "Deleting Registered Devices by using REST".

TOTP authentication constantly generates a new one-time password based on a time interval you specify. The device tracks the last several passwords generated and the current password. The TOTP Time Steps setting configures the number of passwords tracked. The Last Login Time setting monitors the time when a user logs in to make sure that user is not logged in several times within the present time period. The TOTP Time-Step Interval should not be so long as to lock users out, with a recommended time of 30 seconds.

2.9.1.1.1. Differences Among OpenAM Authentication Modules That Support HOTP

The ForgeRock Authenticator (OATH), OATH, and HOTP authentication modules all let you configure authentication that prompts users to enter HMAC one-time passwords. It is important that administrators understand the differences among these authentication modules:

The ForgeRock Authenticator (OATH) and OATH authentication modules accept one-time passwords generated by the end user's device, while the HOTP authentication module generates passwords and sends them to users by e-mail or SMS.
All three of the authentication modules support HOTP passwords. The ForgeRock Authenticator (OATH) and OATH authentication modules also support TOTP passwords.
The ForgeRock Authenticator (OATH) and OATH authentication modules require users to register their devices, and store the device registration details in the user profile. The HOTP authentication module requires the presence of mobile phone numbers and/or e-mail addresses in user profiles.
The ForgeRock Authenticator (OATH) authentication module can encrypt stored device registration details.

Before deciding on an implementation strategy, assess your requirements against the following capabilities in OpenAM:

Comparing the ForgeRock Authenticator (OATH) to the HOTP Authentication Module

Requirement	Available With the ForgeRock Authenticator (OATH) Authentication Module?	Available With the HOTP Authentication Module?
End users can authenticate using a HOTP password	Yes	Yes
OpenAM can generate a HOTP password and send it to end users in a text message or an e-mail	No	Yes
End users can register a mobile phone with OpenAM, and an authenticator app on the phone can generate a HOTP or TOTP password that OpenAM accepts as proof of authentication	Yes	No
End users can authenticate with a TOTP password	Yes	No
End users can opt out of providing a one-time password	Yes	No
End users can authenticate using XUI	Yes	Yes
End users can authenticate using the legacy UI	No	Yes

2.9.1.2. About Push Authentication

You can use push notifications as part of the authentication process in OpenAM.

To receive push notifications when authenticating, end users must register an Android or iOS device with OpenAM. The registered device can then be used as an additional factor when authenticating to OpenAM. OpenAM can send the device a push notification, which can be accepted by the ForgeRock Authenticator app. In the app, the user can allow or deny the request that generated the push notification and return the response to OpenAM.

Overview of Push Authentication in OpenAM

The following steps occur when OpenAM receives an authentication request and is configured for multi-factor authentication using push notifications:

The user must provide credentials to enable OpenAM to locate the user in the identity store and determine if they have a registered mobile device.
OpenAM prompts the user to register a mobile device if they have not done so already. Registering a device associates metadata about the device essential for enabling push notifications with the user's profile in the identity store.
For more information, see "Managing Devices for Multi-Factor Authentication".
Once the details of the registered device are obtained, OpenAM creates a push message specific to the registered device. The message has a unique ID, which OpenAM stores in anticipation of a response from the registered device.
A pending record using the same message ID is also written to the CTS store, providing redundancy should an individual server go offline during the authentication process.
OpenAM sends the push message to the registered device.
OpenAM uses cloud-based push notification services to deliver the messages to the devices. Depending on the registered device, OpenAM uses either Apple Push Notification Services (APNS) or Google Cloud Messaging (GCM) to deliver the push notification.
The ForgeRock Authenticator (Push) authentication module begins to poll OpenAM and the CTS for an accepted response from the registered device.
The user responds to the notification on the registered device, which will open the ForgeRock Authenticator app. In the ForgeRock Authenticator app, the user approves the authentication request with either a swipe, or by using a fingerprint on supported hardware.
For more information, see "To Perform Authentication using Push Notifications".
The app returns the response to the OpenAM cluster.
OpenAM verifies the message is from the correct registered phone and has not been tampered with, and marks the pending record as accepted if valid.
The ForgeRock Authenticator (Push) module detects the accepted record and redirects the user to their profile page, completing the authentication.

2.9.1.2.1. Limitations When Using Passwordless Push Authentication

The ForgeRock Authenticator (Push) authentication module operates in passwordless mode if not preceded by a Data Store module in an authentication chain. When authenticating using such a chain, the user will be asked to enter their user ID, but not their password. A push notification is then sent to their registered device to complete the authentication by using the ForgeRock Authenticator app.

You should be aware of the following potential limitations before deciding to implement passwordless push authentication:

Unsolicited push messages could be sent to a user's registered device by anyone who knew or was able to guess their user ID.
If a malicious user attempted to authenticate by using push at the same time as a legitimate user, the legitimate user might unintentionally approve the malicious attempt. This is because push notifications only contain the username and issuer in the text, and it is not easy to determine which notification relates to which authentication attempt.

Consider using push notifications as part of a multi-factor authentication chain For an example, see "Creating Authentication Chains for Push Authentication".

2.9.2. Implementing Multi-Factor Authentication

This section explains the server configuration required to implement multi-factor authentication in OpenAM:

"Configuring Multi-Factor Authentication Service Settings".
"Letting Users Opt Out of One-Time Password Authentication".
"Creating Multi-Factor Authentication Chains".

2.9.2.1. Configuring Multi-Factor Authentication Service Settings

OpenAM provides a number of services that must be configured to provide multi-factor authentication with the ForgeRock Authenticator app.

The service for customizing one-time password implementation is:

ForgeRock Authenticator (OATH) Service

Specifies the attribute in which to store information about a registered device, and whether to encrypt that information.

Also specifies the attribute used to indicate if a user has opted out of one-time passwords.

For detailed information about the available properties, see "ForgeRock Authenticator (OATH) Service" in the Reference.

The services required for implementing push notifications are:

ForgeRock Authenticator (Push) Service

Specifies the attribute in which to store information about a registered device, and whether to encrypt the data.

For detailed information about the available properties, see "ForgeRock Authenticator (Push) Service" in the Reference.

Push Notification Service

Configures how OpenAM sends push notifications to registered devices, including endpoints, and access credentials.

For information on provisioning the credentials required by the Push Notification Service, see How do I set up AM/OpenAM Push Notification Service credentials in the ForgeRock Knowledge Base.

For detailed information about the available properties, see "Push Notification Service" in the Reference.

To configure these services globally for an OpenAM deployment, navigate to Configure > Global Services, and then click the service to configure.

To configure these services for a realm, navigate to Realms > Realm Name, and then click Services. Add an instance of the service to the realm and configure settings in the service as required.

2.9.2.2. Letting Users Opt Out of One-Time Password Authentication

Letting users opt out of providing one-time passwords when they perform multi-factor authentication is an important implementation decision. The Two Factor Authentication Mandatory setting under Realms > Realm Name > Authentication > Settings > General configures whether users can opt out.

When the Two Factor Authentication Mandatory setting is enabled, users must provide a one-time password every time they authenticate to a chain that includes a ForgeRock Authenticator (OATH) authentication module. When the setting is disabled, the user can optionally skip one-time passwords.

By default, OpenAM lets users opt out of providing one-time passwords. Users authenticating with one-time passwords for the first time are prompted with a screen that lets them opt out of providing one-time passwords.

With the Two Factor Authentication Mandatory setting enabled, the user experience differs from the default behavior. OpenAM does not provide an option to skip multi-factor authentication during the initial attempt at multi-factor authentication:

When configuring an authentication chain that implements one-time passwords, you need to be aware that a user's decision to opt out affects the authentication process. When a user who has opted out of providing one-time passwords authenticates to a chain that includes a ForgeRock Authenticator (OATH) authentication module, that module always passes authentication.

Consider the example authentication chain in "Creating Authentication Chains for One-Time Password Authentication". The first authentication module is a Data Store module and the second authentication module is a ForgeRock Authenticator (OATH) module. Both authentication modules have the Requisite flag setting.

A user who has opted out of providing one-time passwords might experience the following sequence of events when authenticating to the chain:

The Data Store authentication module prompts the user to provide a user ID and password.
The user provides a valid user ID and password.
Data Store authentication passes, and authentication proceeds to the next module in the chain—the ForgeRock Authenticator (OATH) module.
The ForgeRock Authenticator (OATH) authentication module determines that the user has opted out of providing one-time passwords.
ForgeRock Authenticator (OATH) authentication passes. Because it is the last authentication module in the chain, OpenAM considers authentication to have completed successfully.

Contrast the preceding sequence of events to the experience of a user who has not opted out of providing one-time passwords, or who is required to provide one-time passwords, while authenticating to the same chain:

The Data Store authentication module prompts the user to provide a user ID and password.
The user provides a valid user ID and password.
Data Store authentication passes, and authentication proceeds to the next module in the chain—the ForgeRock Authenticator (OATH) module.
The ForgeRock Authenticator (OATH) authentication module determines that the user has not opted out of providing one-time passwords, and prompts the user for a one-time password.
The user obtains a one-time password from the authenticator app on their mobile phone.
If the one-time password is valid, ForgeRock Authenticator (OATH) authentication passes. Because it is the last authentication module in the chain, OpenAM considers authentication to have completed successfully. However, if the one-time password is not valid, ForgeRock Authenticator (OATH) authentication fails, and OpenAM considers authentication to have failed.

2.9.2.3. Creating Multi-Factor Authentication Chains

The following procedures provide steps for creating authentication chains that implement multi-factor authentication.

2.9.2.3.1. Creating Authentication Chains for Push Authentication

Push authentication uses two separate authentication modules:

A module to register a device to receive push notifications called ForgeRock Authenticator (Push) Registration.
A module to perform the actual authentication itself, called ForgeRock Authenticator (Push).

You can insert both modules into a single chain to register devices and then authenticate with push notifications. See "To Create an Authentication Chain for Push Registration and Authentication".

The ForgeRock Authenticator (Push) module can also be used for passwordless authentication using push notifications. If the module is placed at the start of a chain, it will ask the user to enter their user ID, but not their password. A push notification is then sent to their registered device to complete the authentication by using the ForgeRock Authenticator app.

For information on configuring an authentication chain for passwordless authentication, see "To Create an Authentication Chain for Push Registration and Passwordless Authentication".

For information on the potential limitations of passwordless authentication, see "Limitations When Using Passwordless Push Authentication".

To Create an Authentication Chain for Push Registration and Authentication

The procedure assumes the following:

Users will provide user IDs and passwords as the first step of multi-factor authentication.
If the user does not have a device registered to receive push notifications, they will be asked to register a device. After successfully registering a device for push, authentication will proceed to the next step.
A push notification will be sent to the device as a second factor to complete authentication.

To create a multi-factor authentication chain that uses the ForgeRock Authenticator (Push) Registration and ForgeRock Authenticator (Push) modules, follow these steps:

Log in to the console as an OpenAM administrator, for example amadmin.
Select the realm that will contain the authentication chain.
Create a ForgeRock Authenticator (Push) Registration authentication module as follows:
1. Select Authentication > Modules, and then click Add Module.
  The New Module page appears.
2. Fill in fields in the Create New Module dialog box as follows:
  - Name: Specify a module name of your choosing, for example push-reg.
  - Type: Select ForgeRock Authenticator (Push) Registration.
3. Click Create.
  A page that lets you configure the authentication module appears.
4. Configure the module to meet your organization's requirements.
  For more information about the authentication module's configuration settings, see "Hints for the ForgeRock Authenticator (Push) Registration Authentication Module".
Create a ForgeRock Authenticator (Push) authentication module as follows:
1. Select Authentication > Modules, and then click Add Module.
  The New Module page appears.
2. Fill in fields in the Create New Module dialog box as follows:
  - Name: Specify a module name of your choosing, for example push-authn.
  - Type: Select ForgeRock Authenticator (Push).
3. Click Create.
  A page that lets you configure the authentication module appears.
4. Configure the module to meet your organization's requirements.
  For more information about the authentication module's configuration settings, see "Hints for the ForgeRock Authenticator (Push) Authentication Module".
Create the authentication chain as follows:
1. Select Authentication > Chains, and then click Add Chain.
  The Add Chain page appears.
2. Specify a name of your choosing, for example myPushAuthChain, and then click Create.
  A page appears with the Edit Chain tab selected.
3. Add the Data Store authentication module to the authentication chain as follows:
  1. Click Add a Module.
    The New Module dialog box appears.
  2. Fill in the New Module dialog box, specifying the Data Store authentication module. For this example, specify the Required flag.
  3. Click OK.
    The graphic showing your authentication chain now includes a Data Store authentication module.
4. Add the ForgeRock Authenticator (Push) Registration authentication module to the authentication chain as follows:
  1. Click Add a Module.
    The New Module dialog box appears.
  2. Fill in the New Module dialog box, specifying the ForgeRock Authenticator (Push) Registration authentication module that you just created. For this example, specify the Required flag.
  3. Click OK.
    The graphic showing your authentication chain now includes a Data Store, and a ForgeRock Authenticator (Push) Registration authentication module.
5. Add the ForgeRock Authenticator (Push) authentication module to the authentication chain as follows:
  1. Click Add a Module.
    The New Module dialog box appears.
  2. Fill in the New Module dialog box, specifying the ForgeRock Authenticator (Push) authentication module that you created. For this example, specify the Required flag.
  3. Click OK.
    The graphic showing your authentication chain now includes a Data Store, a ForgeRock Authenticator (Push) Registration, and a ForgeRock Authenticator (Push) authentication module.
6. Click Save Changes to save the authentication chain.
Test your authentication chain as follows:
1. Navigate to a URL similar to the following: http://openam.example.com:8080/openam/XUI/#login/&service=myPushAuthChain
  A login screen prompting you to enter your user ID and password appears.
2. Follow the procedure described in "To Perform Authentication using Push Notifications" to verify that you can use the ForgeRock Authenticator app to perform multi-factor authentication. If the chain is correctly configured, authentication is successful and OpenAM displays the user profile page.

To Create an Authentication Chain for Push Registration and Passwordless Authentication

The procedure assumes the following:

Users will provide only their user IDs as the first step of multi-factor authentication.
The user already has a device registered for receiving push notifications. For details of an authentication chain which can register a device for push notifications, see "To Create an Authentication Chain for Push Registration and Authentication".
A push notification will be sent to the device as a second factor, to complete authentication without the need to enter a password.

To create a multi-factor authentication chain that uses the ForgeRock Authenticator (Push) module for passwordless authentication, follow these steps:

Log in to the console as an OpenAM administrator, for example amadmin.
Select the realm that will contain the authentication chain.
Create a ForgeRock Authenticator (Push) authentication module as follows:
1. Select Authentication > Modules, and then click Add Module.
  The New Module page appears.
2. Fill in fields in the Create New Module dialog box as follows:
  - Name: Specify a module name of your choosing, for example push-authn.
  - Type: Select ForgeRock Authenticator (Push).
3. Click Create.
  A page that lets you configure the authentication module appears.
4. Configure the module to meet your organization's requirements.
  For more information about the authentication module's configuration settings, see "Hints for the ForgeRock Authenticator (Push) Authentication Module".
Create the authentication chain as follows:
1. Select Authentication > Chains, and then click Add Chain.
  The Add Chain page appears.
2. Specify a name of your choosing, for example myPasswordlessAuthChain, and then click Create.
  A page appears with the Edit Chain tab selected.
3. Add the ForgeRock Authenticator (Push) authentication module to the authentication chain as follows:
  1. Click Add a Module.
    The New Module dialog box appears.
  2. Fill in the New Module dialog box, specifying the ForgeRock Authenticator (Push) authentication module that you created. For this example, specify the Requisite flag.
  3. Click OK.
    The graphic showing your authentication chain now includes a ForgeRock Authenticator (Push) authentication module.
4. Click Save Changes to save the authentication chain.
Test your authentication chain as follows:
1. Navigate to a URL similar to the following: http://openam.example.com:8080/openam/XUI/#login/&service=myPasswordlessAuthChain
  A login screen prompting you to enter your user ID appears.
2. Follow the procedure described in "To Perform Authentication using Push Notifications" to verify that you can use the ForgeRock Authenticator app to perform multi-factor authentication. If the chain is correctly configured, authentication is successful and OpenAM displays the user profile page, without having to enter a password.

2.9.2.3.2. Creating Authentication Chains for One-Time Password Authentication

This section covers one-time password authentication.

To Create an Authentication Chain for One-Time Password Authentication

The procedure assumes the following:

Users will provide user IDs and passwords as the first step of multi-factor authentication.
An existing Data Store authentication module will collect and verify user IDs and passwords.
All authentication modules in the chain will use the Requisite flag setting. See "About Authentication in OpenAM" for details about authentication module flag settings.
Users can opt out of one-time password authentication.

To create a multi-factor authentication chain that uses the ForgeRock Authenticator (OATH) module, follow these steps:

Log in to the console as an OpenAM administrator, for example amadmin.
Select the realm that will contain the authentication chain.
You can allow users to opt out of using OATH-based one-time passwords as follows:
1. Select Authentication > Settings > General.
2. Make sure that the Two Factor Authentication Mandatory is not enabled.
  See "Core Authentication Attributes - General" for details about this configuration setting.
For information about how letting users skip multi-factor authentication impacts the behavior of authentication chains, see "Letting Users Opt Out of One-Time Password Authentication".
Create a ForgeRock Authenticator (OATH) authentication module as follows:
1. Select Authentication > Modules, and then click Add Module.
  The New Module page appears.
2. Fill in fields in the Create New Module dialog box as follows:
  - Name: Specify a module name of your choosing.
  - Type: Select ForgeRock Authenticator (OATH).
3. Click Create.
  A page that lets you configure the authentication module appears.
4. Configure the ForgeRock Authenticator authentication module to meet your organization's requirements.
  For more information about the authentication module's configuration settings, see "Hints for the ForgeRock Authenticator (OATH) Authentication Module".
Create the authentication chain as follows:
1. Select Authentication > Chains, and then click Add Chain.
  The Add Chain page appears.
2. Specify a name of your choosing, for example myOathAuthChain, and then click Create.
  A page appears with the Edit Chain tab selected.
3. Click Add a Module. Fill in fields in the New Module dialog box as follows:
  - Select Module: Select the existing Data Store module to use in this chain.
  - Select Criteria: Select a flag setting for the module in the authentication chain. For this example, specify the Requisite flag.
    See "About Authentication in OpenAM" for information about authentication module flag settings.
4. Click OK.
  A graphic showing an authentication chain with a single Data Store module appears on the page.
5. Add the ForgeRock Authenticator (OATH) authentication module to the authentication chain as follows:
  1. Click Add a Module.
    The New Module dialog box appears.
  2. Fill in the New Module dialog box, specifying the ForgeRock Authenticator (OATH) authentication module that you just created. For this example, specify the Requisite flag.
  3. Click OK.
    The graphic showing your authentication chain now includes the Data Store and ForgeRock Authenticator (OATH) authentication module.
6. Click Save Changes to save the authentication chain.
Test your authentication chain as follows:
1. Navigate to a URL similar to the following: http://openam.example.com:8080/openam/XUI/#login/&service=myOathAuthChain
  A login screen prompting you to enter your user ID and password appears.
2. Follow the procedure described in "To Perform Authentication using a One-Time Password" to verify that you can use the ForgeRock Authenticator app to perform multi-factor authentication. If the chain is correctly configured, authentication is successful and OpenAM displays the user profile page.

2.9.3. Managing Devices for Multi-Factor Authentication

Multi-factor authentication requires you to register a device, which is used as an additional factor when you log in to OpenAM.

This section covers the following topics relating to devices used for multi-factor authentication:

2.9.3.1. Downloading the ForgeRock Authenticator App

If you have not already done so, download and install the ForgeRock Authenticator app on your phone, so that you can perform multi-factor authentication.

The ForgeRock Authenticator app supports push authentication notifications and one-time passwords.

The app is available for both Android and iOS devices, and is free to download. Source code is also available:

Android

Download: Google Play

Source code: https://stash.forgerock.org/projects/OPENAM/repos/forgerock-authenticator-android

iOS

Download: App Store

Source code: https://stash.forgerock.org/projects/OPENAM/repos/forgerock-authenticator-ios

2.9.3.2. Registering a Device for Multi-Factor Authentication

Registering a device with OpenAM by using the ForgeRock Authenticator app enables it to be used as an additional factor when logging in.

The ForgeRock Authenticator app supports registration of multiple accounts and multiple different authentication methods in each account, such as push notifications and one-time passwords.

Device registration only needs to be completed the first time an authentication method is used with an identity provider. Use of a different authentication method may require that device registration with the identity provider is repeated for that additional method.

The device needs access to the internet to register to receive push notifications. Registering for one-time password authentication does not require a connection to the internet.

To Register a Device for Multi-Factor Authentication

When visiting a protected resource without having any registered devices for multi-factor authentication, OpenAM requires that you register a device.
To register your mobile phone with OpenAM, click Register Device. A screen with a QR code appears:
Start the ForgeRock Authenticator app on the device to register, and then click the plus icon:
The screen on the device changes to an interface similar to your camera app.
Point the camera at the QR code on the OpenAM page and the ForgeRock Authenticator app will acquire the QR code and read the data encoded within.
If you are logging in to OpenAM on the registered device and cannot scan the screen, click the button labelled On a mobile device?. The ForgeRock Authenticator app will request permission to launch. If allowed, the information required to register the device will be transferred to the ForgeRock Authenticator app directly, without the need to scan the QR code.
After registering, the app displays the registered accounts and the authentication methods they support, for example one-time passwords (a timer icon) or push notifications (a bell icon):

Your device is now registered. You will able to use it to perform multi-factor authentication.

Important

After registering a new device and successfully performing multi-factor authentication, you should obtain the recovery codes for the registered device and store them somewhere safe. See "Accessing Your Recovery Codes".

2.9.3.3. Accessing Your Recovery Codes

After successful first-time authentication with multi-factor authentication, you should safeguard your ability to use multi-factor authentication in case you lose your phone. OpenAM provides each device you register with a set of one-time recovery codes that you can use in cases where you cannot complete multi-factor authentication using your registered device.

To Access Your Recovery Codes

After registering a new device with OpenAM, use the following steps to access your recovery codes:

Log in to OpenAM.
Select Dashboard from the top-level menu.
Locate the entry for the device type in the Authentication Devices section, click the context menu button, and then click Recovery Codes:
A list of recovery codes appears:
Keep a copy of the codes for each of your registered device types in a safe place. You will need to use one of your recovery codes to authenticate to OpenAM if you lose your phone.

See "Recovering After Replacing a Lost Device" for the procedure to authenticate to OpenAM using a recovery code instead of performing multi-factor authentication.

2.9.3.4. Opting Out of One-Time Password Authentication

Unless the OpenAM administrator has made one-time password authentication mandatory, users can choose to opt out of using one-time passwords by clicking the Skip This Step button on the ForgeRock Authenticator (OATH) screen. ^[2] This button appears:

When users are prompted to register their mobile devices during their initial login from a new device.
Every time users are prompted by the ForgeRock Authenticator (OATH) authentication module to enter one-time passwords.

Users who decide to opt out of using one-time passwords are not prompted to enter one-time passwords when authenticating to OpenAM.

The decision to opt out of using one-time passwords in OpenAM is revocable: users who have decided to opt out of using one-time passwords can reverse their decisions, so that one-time password authentication is once again required.

End users should follow these steps to opt out or opt in to using one-time passwords:

To Opt out or Opt in to Using One-Time Passwords

Log in to OpenAM.
Select Dashboard from the top navigation bar.
In the Authentication Devices section of the Dashboard page, click the context menu button, and then click Settings:
Enable or disable the 2-Step Authentication option:
Click Save.

2.9.3.5. Recovering After Replacing a Lost Device

If you register a device with OpenAM and then lose it, you must authenticate to OpenAM using a recovery code, delete the lost device, and then register the new device. Follow these steps:

To Register a New Device After Losing a Registered Device

Log in to OpenAM. If push authentication is enabled, enter your user ID, click Log In, and then click Use Emergency Code. If one-time passwords are enabled, when prompted to enter a verification code, instead enter one of your recovery codes.
Because recovery codes are valid for a single use only, make a note to yourself not to attempt to reuse this code.
If you did not save the recovery codes for the lost device, contact your administrator to remove the registered device from your OpenAM user profile.
Select Dashboard from the top-level menu.
Locate the entry for your phone in the Authentication Devices section, click the context menu button, and then click Delete:
If you have not already done so, install the ForgeRock Authenticator app on your new phone. See "Downloading the ForgeRock Authenticator App".
Register your new device. See "Registering a Device for Multi-Factor Authentication".

Users who do not save recovery codes or who run out of recovery codes and cannot authenticate to OpenAM without a verification code require administrative support to reset their device profiles. See "Deleting Registered Devices by using REST" for more information.

2.9.3.6. Recovering After a Device Becomes Out of Sync With OpenAM

If you repeatedly enter valid one-time passwords that appear to be valid passwords, but OpenAM rejects the passwords as unauthorized, it is likely that your device has become out of sync with OpenAM.

When a registered device becomes out of sync with OpenAM, you must authenticate to OpenAM using a recovery code, delete your device, and then re-register your device. You can do so by performing the steps in "To Register a New Device After Losing a Registered Device".

Users who do not save recovery codes or who run out of recovery codes and cannot authenticate to OpenAM without a verification code require administrative support to reset their device profiles. See "Deleting Registered Devices by using REST" for more information.

2.9.3.7. Deleting Registered Devices by using REST

As described in "Recovering After Replacing a Lost Device", a user who has lost a mobile phone registered with OpenAM can register a replacement device by authenticating using a recovery code, deleting their existing device, and then re-registering a new device.

Additional support is required for users who lose mobile phones but did not save their recovery codes when they initially registered the phone, and for users who have used up all their recovery codes.

OpenAM provides a REST API to reset a device profile by deleting information about a user's registered device. Either the user or an administrator can call the REST API to reset a device profile. Device profile reset can be implemented as follows:

Administrators provide authenticated users with a self-service page that calls the REST API to let the users reset their own device profiles.
Administrators can call the REST API themselves to reset users' device profiles.
Administrators can call the REST API themselves to reset a device when the HOTP counter exceeds the HOTP threshold window and requires a reset.
Note
The reset action deletes the OATH device profile, which by default has a limit of one profile per device, and sets the Select to Enable Skip option to its default value of Not Set.

For details about the REST API to reset users' device profiles, see "Resetting Device Profiles" in the Developer's Guide.

2.9.4. Authenticating Using Multi-Factor Authentication

This section provides an example of how end users might authenticate with OpenAM configured for multi-factor authentication. Use the following procedures to complete multi-factor authentication using the ForgeRock Authenticator:

"To Perform Authentication using a One-Time Password"
"To Perform Authentication using Push Notifications"

To Perform Authentication using a One-Time Password

This example uses the authentication chain as created in "Creating Authentication Chains for One-Time Password Authentication".

Because the first module in the authentication chain is a Data Store module, OpenAM presents you with a page for entering your user ID and password. After you provide those credentials, OpenAM verifies them. If your credentials are valid, OpenAM proceeds to the ForgeRock Authenticator (OATH) authentication module.

On the ForgeRock Authenticator (OATH) screen, follow these steps to complete one-time password authentication:

On your registered device, open the ForgeRock Authenticator app, and then tap the account matching the user ID you entered earlier. The registered authentication methods for that account are displayed:
In the One-time Password section, click the refresh icon. A one-time password is displayed:
On the ForgeRock Authenticator (OATH) page in OpenAM, enter the one-time password that the authenticator app generated on your phone, and then click Submit:
OpenAM will display the user's profile page.

To Perform Authentication using Push Notifications

This example uses one of the authentication chains as created in "Creating Authentication Chains for Push Authentication".

OpenAM presents you with a page for entering only your user ID, or user ID and password. After you provide those credentials, OpenAM verifies them. If your credentials are valid and the account has a device registered for push notifications, OpenAM proceeds to the ForgeRock Authenticator (Push) authentication module, and a push notification is sent to the registered device.

Note

The device needs access to the Internet to receive push notifications, and the OpenAM server must be able to receive responses from the device.

Follow these steps to complete authentication using push notifications:

On your registered device, you will receive a push notification from OpenAM. Depending on the state of the phone and the ForgeRock Authenticator app, respond to the notification as follows:
- If the phone is locked, the notification may appear similar to the following:
  Slide the notification across the screen, then unlock the phone. The ForgeRock Authenticator app will automatically open and display the push notification authentication screen.
- If the phone is not locked, and the ForgeRock Authenticator app is not open, the notification may appear similar to the following:
  Tap the notification. The ForgeRock Authenticator app will automatically open and display the push notification authentication screen.
- If the phone is not locked, and the ForgeRock Authenticator app is open, the app will open the push notification authentication screen automatically.
On the push notification authentication screen, you can approve the request or deny it:
- Slide the switch with a checkmark on horizontally to the right.
  OpenAM will display the user's profile page.
- If the registered device supports Touch ID, and fingerprints have been provided, you can approve the request by using a registered fingerprint.
  OpenAM will display the user's profile page.
- To deny the request, tap the cancel icon in the top-right of the screen, or if Touch ID is enabled, click the Cancel button.
  After a timeout has passed, OpenAM will report that authentication has failed and return to the first screen in the chain.
  Note
  If you do not approve or deny the request on the registered device, the OpenAM Push Authentication page will timeout and the authentication will fail. The timeout can be configured in the ForgeRock Authenticator (Push) authentication module settings. See "Hints for the ForgeRock Authenticator (Push) Authentication Module".

2.10. Authentication Levels and Session Upgrade

As shown in "Configuring Authentication Modules", authentication modules are configured with an authentication level. This configuration sets the level of security associated with the module, Stronger forms of authentication are assigned higher authentication levels. (Or lower authentication level numbers if the deployment defines stronger authentication with lower authentication level numbers.) Upon successful authentication, a user's session includes information about the authentication level achieved.

Authorization policies can require a particular authentication level for access to sensitive resources (or at most or at least a specified authentication level). When a user who is already authenticated in the realm tries to access a sensitive resource with a valid session that does not have the requisite authentication level, OpenAM denies access to the resource. However, OpenAM also returns advices with the authorization decision. The advices indicate the need for the required authentication level. The policy agent or policy enforcement point can then send the user back to OpenAM for session upgrade.

During session upgrade the user authenticates with a stronger authentication module. The stronger module is typically part of the same authentication chain that handled the original authentication, though not required for access to less sensitive resources. Upon successful stronger authentication, the user session is upgraded to the new authentication level and modified to include any settings related to the stronger authentication.

If unsuccessful, session upgrade leaves the user session as it was before the attempt at stronger authentication. If session upgrade failed because the login page times out, OpenAM redirects the user's browser to the success URL from the last successful authentication.

OpenAM policy agents generally handle session upgrade without additional configuration, as policy agents are built to handle OpenAM's advices. If you build your own policy enforcement point (PEP), however, take advices and session upgrade into consideration. For RESTful PEPs, see "Requesting Policy Decisions" in the Developer's Guide, and for indications on how to handle advices and session upgrade see "Authentication and Logout" in the Developer's Guide.

OpenAM's support for session upgrades requires stateful sessions. Be sure that OpenAM is configured for stateful sessions—the default configuration—before attempting to upgrade OpenAM sessions.

2.11. Configuring Account Lockout

OpenAM supports two different approaches to account lockout, where OpenAM locks an account after repeated authentication failures. Lockout works with modules for which users can enter a password incorrectly. For example:

Memory lockout locks the user account, keeping track of the locked state only in memory, and then unlocking the account after a specified delay. Memory lockout is also released when OpenAM restarts.
Persistent (physical) lockout sets the user account status to inactive in the user profile. For persistent lockout, OpenAM tracks failed authentication attempts by writing to the user repository.
Persistent account lockout works independently of account lockout mechanisms in the underlying directory server that serves as the user data store.

You configure account lockout by editing settings for the core authentication module. For details, see "Configuring Core Authentication Attributes". Access the settings in OpenAM console under Realms > Realm Name > Authentication > Settings > Account Lockout. The inline help explains the settings in detail. To do this:

Enable lockout by checking Login Failure Lockout Mode, setting the number of attempts, and setting the lockout interval and duration.
You can also opt to warn users after several consecutive failures, or to multiply the lockout duration on each successive lockout.
You can set up email notification upon lockout to an administrator if OpenAM is configured to send mail. (You can configure OpenAM to send mail in Configure > Server Defaults > General > Mail Server.)
For persistent lockout, OpenAM sets the value of the user's inetuserstatus profile attribute to inactive. You can also specify another attribute to update on lockout. You can further set a non-default attribute on which to store the number of failed authentication attempts. When you do store the number of failed attempts in the data store, other OpenAM servers accessing the user data store can also see the number.

If you need to unlock a user's account, find the user under Realms > Realm Name > Subjects > User, set the user's User Status to Active, and click Save.

2.12. Configuring Session Quotas

OpenAM lets you limit the number of active sessions for a user by setting session quotas. You also configure session quota exhaustion actions so that when a user goes beyond the session quota, OpenAM takes the appropriate action.

OpenAM's support for session quotas requires stateful sessions. Be sure that OpenAM is configured for stateful sessions—the default configuration—before attempting to configure session quotas.

Important

To enforce session quotas across multiple servers in a site, configure session failover as described in "Setting Up OpenAM Session Failover" in the Installation Guide.

To Configure Session Quotas and Exhaustion Actions

The session quota applies to all sessions opened for the same user (as represented by the user's universal identifier). To configure:

Log in to OpenAM console as administrator, navigate to Configure > Global Services, and then click Session.
Set Enable Quota Constraints to ON.
Set Resulting behavior if session quota exhausted.
The following settings are available by default:
DENY_ACCESS
Deny access, preventing the user from creating an additional session.
DESTROY_NEXT_EXPIRING
Remove the next session to expire, and create a new session for the user. The next session to expire is the session with the minimum time left until expiration.
This is the default setting.
DESTROY_OLDEST_SESSION
Remove the oldest session, and create a new session for the user.
DESTROY_OLD_SESSIONS
Remove all existing sessions, and create a new session for the user.
If none of these session quota exhaustion actions fit your deployment, you can implement a custom session quota exhaustion action. For an example, see "Customizing Session Quota Exhaustion Actions" in the Developer's Guide.
Set Active User Sessions to the session quota.
The default is 5 sessions.
Save your work.
(Optional) If you have multiple servers but session failover is not configured, configure multi-server mode as described below:
- If you have only a single OpenAM server, skip this step. OpenAM enforces the session quota you set for the server.
- If you have multiple servers with session failover configured, then also skip this step. In this case OpenAM uses the session store to enforce session quotas globally across your deployment. In other words when the Set Active User Sessions is 5, a user can have a maximum of five active sessions.
- If you have multiple OpenAM servers but session failover is not configured, configure multi-server mode for session quotas as follows:
  1. Navigate to Configure > Server Defaults > Advanced, or Deployment > Servers > Server Name > Advanced.
  2. Set the openam.session.useLocalSessionsInMultiServerMode property to true.
  When you set this property to true for your OpenAM servers, users can potentially reach the session quota for each individual server before all session quotas are exhausted. In other words, if you have four OpenAM servers and Set Active User Sessions is 5, then the user can have a maximum of 20 (5 * 4) sessions.

2.13. Configuring Valid goto URL Resources

By default, OpenAM redirects the user to the URL specified in the goto and gotoOnFail query string parameters supplied to the authentication interface in the login URL. You can increase security against possible phishing attacks through open redirect by specifying a list of valid URL resources using the Validation Service.

OpenAM only redirects a user if the goto and gotoOnFail URL matches any of the resources specified in this setting. If no setting is present, it is assumed that the goto or gotoOnFail URL is valid.

The URL whitelisting and pattern matching follow the wildcard rules as specified in "Specifying Resource Patterns with Wildcards".

Here are some general examples of URL pattern matching:

If no port is specified, http://www.example.com canonicalizes to http://www.example.com:80 and https://www.example.com canonicalizes to http://www.example.com:443.
A wildcard before "://" only matches up to "://"
For example, http*://*.com/* matches http://www.example.com/hello/world and https://www.example.com/hello.
A wildcard between "://" and ":" matches up to ":"
For example, http://*:85 matches http://www.example.com:85.
A wildcard between ":" and "/" only matches up to the first "/"
For example, http://www.*:*/ matches http://www.example.com:80. In another example, http://www.example.com:* matches http://ww.example.com:[any port] and http://www.example.com:[any port]/, but nothing more.
A wildcard after "/" matches anything, depending on whether it is single-level or a wildcard appropriately.
For example, https://www.example.com/* matches https://www.example.com:443/foo/bar/baz/me
If you do not use any wildcards, OpenAM exactly matches the string, so http://www.example.com only matches http://www.example.com, but NOT http://www.example.com/ (trailing slash).
If you put the wildcard after the path, OpenAM expects a path (even if it is blank), so http://www.example.com/* matches http://www.example.com/ and http://www.example.com/foo/bar/baz.html, but NOT http://www.example.com.
http://www.example.com:*/ matches http://www.example.com/, which also canonicalizes to http://www.example.com:80/.
https://www.example.com:*/ matches https://www.example.com/, which also canonicalizes to https://www.example.com:443/.

2.14. Redirection URL Precedence

OpenAM determines the redirection URL based on authentication success or failure.

2.14.1. Successful Authentication URL Precedence

Upon a successful authentication, OpenAM determines the redirection URL in the following order:

The URL set in the authentication chain.
In the OpenAM console, you can set the Successful Login URL parameter by navigating to realm > Authentication > Chains > chain > Settings.

The URL set in the goto login URL parameter. For example,

http://openam.example.com:8080/openam/XUI/?realm=/#login/&goto=http%3A%2F%2Fwww.example.com

The URL set in the Success URL attribute in the user's profile.
In the OpenAM console, you can set the Success URL parameter by navigating to realm > Subjects > subject. Scroll down to Success URL, enter a URL in the New Value field, and then click Add.
You can also specify the client type by entering ClientType|URL as the property value. If the client type is specified, it will have precedence over a regular URL in the user's profile.
The URL set in the Default Success Login URL attribute in the Top Level realm.
You can set this property on the OpenAM console by navigating to Configure > Authentication > Core Attributes > Post Authentication Processing.
You can also specify the client type by entering ClientType|URL as the property value. If the client type is specified, it will have precedence over a Default Success Login URL in the Top Level realm.

2.14.2. Failed Authentication URL Precedence

Upon a failed authentication, OpenAM determines the redirection URL in the following order:

The URL set in the authentication chain.
In the OpenAM console, you can set the Failed Login URL parameter by navigating to realm > Authentication > Chains > chain > Settings.

The URL set in the gotoOnFail URL parameter. For example,

http://openam.example.com:8080/openam/XUI/?realm=/#login/&gotoOnFail=http%3A%2F%2Fwww.example.com

The URL set in the Failure URL attribute in the user's profile.
In the OpenAM console, you can set the Failure URL parameter by navigating to realm > Subjects > subject. Scroll down to Failure URL, and enter a URL in the New Value field, and then click Add.
You can also specify the client type by entering ClientType|URL as the property value. If the client type is specified, it will have precedence over a regular URL in the user's profile.
The URL set in the Default Failure Login URL attribute in the Top Level realm.
You can set this property on the OpenAM console by navigating to Configure > Authentication > Core Attributes > Post Authentication Processing.
You can also specify the client type by entering ClientType|URL as the property value. If the client type is specified, it will have precedence over a Default Failure Login URL in the Top Level realm.

^[2]For information about making the usage of one-time passwords mandatory in OpenAM, see "Letting Users Opt Out of One-Time Password Authentication".

Chapter 3. Defining Authorization Policies

Authorization is determining whether to grant or to deny a user access to a resource. Policies define how to determine whether to grant or deny access. This chapter describes how to configure authorization policies in OpenAM.

3.1. About Authorization in OpenAM

Applications rely on OpenAM for access management, which breaks down into authentication, or determining who is trying to access a resource, and authorization, or determining whether to grant or deny access. This is because whether access is granted generally depends on what the policies about access are, who is trying to gain access, and perhaps some other conditions, such as whether the access itself needs to happen over a secure channel or what time of day it is.

To return to the international airport example from the discussion on authentication the policy might be that passengers with valid passports and visas presenting valid plane tickets are allowed through to the gate where the plane is waiting to take off, but only under the condition that the plane is going to leave soon. (You cannot expect to get to the gate today with a scheduled departure for three months from now.)

3.1.1. OpenAM Resource Types, Policy Sets, and Policies

Define authorization policies to allow OpenAM to determine whether to grant a subject access to a resource.

A policy defines the following:

resources: The resource definitions constrain which resources, such as web pages or access to the boarding area, the policy applies to.
actions: The actions are verbs that describe what the policy allows users to do to the resources, such as read a web page, submit a web form, or access the boarding area.
subject conditions: The subject conditions constrain who the policy applies to, such as all authenticated users, only administrators, or only passengers with valid tickets for planes leaving soon.
environment conditions: The environment conditions set the circumstances under which the policy applies, such as only during work hours, only when accessing from a specific IP address, or only when the flight is scheduled to leave within the next four hours.
response attributes: The response attributes define information that OpenAM attaches to a response following a policy decision, such as a name, email address, or frequent flyer status.

When queried about whether to let a user through to a protected resource, OpenAM decides whether to authorize access or not based on applicable policies as described below in "OpenAM Policy Decisions". OpenAM communicates its decision to the application that is using OpenAM for access management. In the common case, this is a policy agent installed on the server where the application runs. The agent then enforces the authorization decision from OpenAM.

Relationship between Realms, Policies, and Policy Sets

To help with the creation of policies, OpenAM uses resource types and policy sets.

Resource types

Resource types define a template for the resources that policies apply to, and the actions that could be performed on those resources.

For example, the URL resource type that is included by default in OpenAM acts as a template for protecting web pages or applications. It contains resource patterns, such as *://*:*/*?*, which can be made more specific when used in the policy. The actions that the resource supports are also defined, as follows:

GET
POST
PUT
HEAD
PATCH
DELETE
OPTIONS

OpenAM also includes a resource type to protect REST endpoints, with patterns including https://*:*/*?* and the CRUDPAQ actions:

CREATE
READ
UPDATE
DELETE
PATCH
ACTION
QUERY

Policy Sets

Policy Sets are associated with a set of resource types, and contain one or more policies based upon the template it provides.

For example, an application for Example.com's HR service might contain resource types that constrain all policies to apply to URL resource types under http*://example.com/hr* and http*://example.com/hr*?*, and only the HTTP GET and POST actions.

Configure policy sets, policies, and resource types in the OpenAM console under Realms > Realm Name > Authorization.

Policy Sets in the OpenAM Console

For more information on viewing, creating, and editing policies and resource types, see "Configuring Resource Types, Policy Sets, and Policies".

3.1.2. OpenAM Policy Decisions

OpenAM relies on policies to reach authorization decisions, such as whether to grant or to deny access to a resource. OpenAM acts as the policy decision point (PDP), whereas OpenAM policy agents act as policy enforcement points (PEP). In other words, a policy agent or other PEP takes responsibility only for enforcing a policy decision rendered by OpenAM. When you configured applications and their policies in OpenAM, you used OpenAM as a policy administration point (PAP).

Concretely speaking, when a PEP requests a policy decision from OpenAM it specifies the target resource(s), the policy set (default: iPlanetAMWebAgentService), and information about the subject and the environment. OpenAM as the PDP retrieves policies within the specified policy set that apply to the target resource(s). OpenAM then evaluates those policies to make a decision based on the conditions matching those of the subject and environment. When multiple policies apply for a particular resource, the default logic for combining decisions is that the first evaluation resulting in a decision to deny access takes precedence over all other evaluations. OpenAM only allows access if all applicable policies evaluate to a decision to allow access.

OpenAM communicates the policy decision to the PEP. The concrete decision, applying policy for a subject under the specified conditions, is called an entitlement.

The entitlement indicates the resource(s) it applies to, the actions permitted and denied for each resource, and optionally response attributes and advice.

When OpenAM denies a request due to a failed condition, OpenAM can send advice to the PEP, and the PEP can then take remedial action. For instance, suppose a user comes to a web site having authenticated with an email address and password, which is configured as authentication level 0. Had the user authenticated using a one-time password, the user would have had authentication level 1 in their session. Yet, because they have authentication level 0, they currently cannot access the desired page, as the policy governing access requires authentication level 1. OpenAM sends advice, prompting the PEP to have the user re-authenticate using a one-time password module, gaining authentication level 1, and thus having OpenAM grant access to the protected page.

3.1.3. Example Authorization

Consider the case where OpenAM protects a user profile web page. An OpenAM policy agent installed in the web server intercepts client requests to enforce policy. The policy says that only authenticated users can access the page to view and to update their profiles.

When a user browses to the profile page, the OpenAM policy agent intercepts the request. The policy agent notices that the request is to access a protected resource, but the request is coming from a user who has not yet logged in and consequently has no authorization to visit the page. The policy agent therefore redirects the user's browser to OpenAM to authenticate.

OpenAM receives the redirected user, serving a login page that collects the user's email and password. With the email and password credentials, OpenAM authenticates the user, and creates a session for the user. OpenAM then redirects the user to the policy agent, which gets the policy decision from OpenAM for the page to access, and grants access to the page.

While the user has a valid session with OpenAM, the user can go away to another page in the browser, come back to the profile page, and gain access without having to enter their email and password again.

Notice how OpenAM and the policy agent handle the access in the example. The web site developer can offer a profile page, but the web site developer never has to manage login, or handle who can access a page. As OpenAM administrator, you can change authentication and authorization independently of updates to the web site. You might need to agree with web site developers on how OpenAM identifies users so web developers can identify users by their own names when they log in. By using OpenAM and policy agents for authentication and authorization, your organization no longer needs to update web applications when you want to add external access to your Intranet for roaming users, open some of your sites to partners, only let managers access certain pages of your HR web site, or allow users already logged in to their desktops to visit protected sites without having to type their credentials again.

3.2. How OpenAM Reaches Policy Decisions

OpenAM has to match policies to resources to take policy decisions. For a policy to match, the resource has to match one of the resource patterns defined in the policy. The user making the request has to match a subject. Furthermore, at least one condition for each condition type has to be satisfied.

If more than one policy matches, OpenAM has to reconcile differences. When multiple policies match, the order in which OpenAM uses them to make a policy decision is not deterministic. However, a deny decision overrides an allow decision, and so by default once OpenAM reaches a deny decision it stops checking further policies. If you want OpenAM to continue checking despite the deny, navigate to Configure > Global Services, click Policy Configuration, and then enable Continue Evaluation on Deny Decision.

3.3. Configuring Resource Types, Policy Sets, and Policies

You can configure resource types, policy sets, and policies by using the OpenAM console, or by using the REST interface.

This section explains how to use the OpenAM console to configure resource types, policy sets, and policies to protect resources.

For information on managing resource types, policy sets, and policies by using the REST API, see "Managing Resource Types" in the Developer's Guide, "Managing Policy Sets" in the Developer's Guide, and "Managing Policies" in the Developer's Guide.

Tip

You can also configure policy sets and policies by using the ssoadm command. For more information see ssoadm(1) in the Reference.

3.3.1. Configuring Resource Types by Using the OpenAM Console

This section describes the process of using the OpenAM console for creating resource types, which define a template for the resources that policies apply to, and the actions that could be performed on those resources.

To Configure a Resource Type by Using the OpenAM Console

In the OpenAM console, select Realms > Realm Name > Authorization > Resource Types.
1. To create a new resource type, click New Resource Type.
2. To modify an existing resource type, click the resource type name.
3. To delete an existing resource type, in the row containing the resource type click the Delete button.
  You can only delete resource types that are not being used by policy sets or policies. Trying to delete a resource type that is in use returns an HTTP 409 Conflict status code.
  Remove the resource type from any associated policy sets or policies to be able to delete it.
Provide a name for the resource type, and optionally a description.
Do not use special characters within resource type, policy, or policy set names (for example, "my+resource+type") when using the console or REST endpoints. Using the special characters listed below causes OpenAM to return a 400 Bad Request error. The special characters are: double quotes ("), plus sign (+), comma (,), less than (<), equals (=), greater than (>), backslash (\), forward slash (/), semicolon (;), and null (\u0000).
To define resource patterns that policies using this resource type can expand upon, follow the steps below:
1. In the Add a new pattern box, enter a pattern with optional wildcards that the policies will use as a template.
  For information on specifying patterns for matching resources, see "Specifying Resource Patterns with Wildcards".
2. Click the Add Pattern button to confirm the pattern.
Tip
To remove a pattern, click the Delete icon.
To define the actions that policies using this resource type can allow or deny, follow the steps below:
1. In the Add a new action box, enter an action related to the types of resources being described, and then click Add Action.
2. Select either allow or deny as the default state for the action.
To remove an action, click the Delete icon.
Continue adding the patterns and actions that your resource type requires.
Configuring Resource Types in the OpenAM Console
Click Create Resource Type to save a new resource type or Save Changes to save modifications to an existing resource type.

3.3.2. Configuring Policy Sets Using the OpenAM Console

This section describes how to use the OpenAM console to create policy sets, which are used as templates for policies protecting Web sites, Web applications, or other resources.

To Configure a Policy Set Using the OpenAM Console

In the OpenAM console, select Realms > Realm Name > Authorization > Policy Sets.
1. To create a new policy set, click New Policy Set.
2. To modify an existing policy set, in the row containing the name of the policy set click the Edit icon, and then click the Settings tab.
Enter an ID for the policy set. This is a required parameter
Enter a name for the policy set. The name is optional and is for display purposes only.
Do not use special characters within resource type, policy, or policy set names (for example, "my+resource+type") when using the console or REST endpoints. Using the special characters listed below causes OpenAM to return a 400 Bad Request error. The special characters are: double quotes ("), plus sign (+), comma (,), less than (<), equals (=), greater than (>), backslash (\), forward slash (/), semicolon (;), and null (\u0000).
In the Resource Types drop-down menu, select one or more resource types that policies in this policy set will use.
Tip
To remove a resource type from the policy set, select the label, and then press Delete or Backspace.
Click Create to save a new policy set or Save Changes to save modifications to an existing policy set.
Configuring Policy Sets in the OpenAM Console

To make use of a policy set and any policies it contains, you must configure a policy agent to use the policy set for policy decisions. For details see "To Specify the Realm and Application for Policy Decisions".

Note

Once a policy set is created, users can only change the displayName of an existing policy set, not the ID, without deleting the associated policies.

3.3.3. Configuring Policies Using the OpenAM Console

This section describes the process of using the OpenAM console to configure policies, which are used to protect a web site, web application, or other resource.

To Configure a Policy Using the OpenAM Console

In the OpenAM console, select Realms > Realm Name > Authorization > Policy Sets, and then click the name of the policy set in which to configure a policy:
To create a new policy, click Add a Policy.
In the Name field, enter a descriptive name for the policy.
Note
Do not use special characters within resource type, policy, or policy set names (for example, "my+resource+type") when using the console or REST endpoints. Using the special characters listed below causes OpenAM to return a 400 Bad Request error. The special characters are: double quotes ("), plus sign (+), comma (,), less than (<), equals (=), greater than (>), backslash (\), forward slash (/), semicolon (;), and null (\u0000).
To define resources that the policy applies to, follow the steps below:
1. Select a resource type from the Resource Type drop-down list. The set of resource patterns within the selected resource type will populate the Resources drop-down list. For information on configuring resource types, see "Configuring Resource Types by Using the OpenAM Console".
2. Select a resource pattern from the Resources drop-down list.
3. (Optional) Optionally, replace the asterisks with values to define the resources that the policy applies to.
  Editing Resource Patterns Policies
  
  For information on specifying patterns for matching resources, see "Specifying Resource Patterns with Wildcards".
4. Click Add to save the resource.
  The OpenAM console displays a page for your new policy. The Tab pages let you modify the policy's properties.
Tip
To remove a resource, click the Delete icon.
Repeat these steps to add all the resources to which your policy applies, and then click Create.
To configure the policy's actions, select the Actions tab and perform the following:
1. Select an action that the policy applies to by selecting them from the Add an Action drop-down list.
2. Select whether to allow or deny the action on the resources specified earlier.
  Allowing or Denying the Action for the Resource
3. Repeat these steps to add all the appropriate actions, and then click Save Changes.
Define conditions in the OpenAM console by combining logical operators with blocks of configured parameters to create a rule set that the policy uses to filter requests for resources. Use drag and drop to nest logical operators at multiple levels to create complex rule sets.
Valid drop-points in which to drop a block are displayed with a grey horizontal bar.
Valid Drop Point
1. To define the subjects that the policy applies to, complete the following steps on the Subjects tab:
  1. Click Add a Subject Condition, choose the type from the drop-down menu, specify any required subject values, click the checkmark to the right when done, and then drag the block into a valid drop point in the rule set above.
    Nesting subject conditions
    
    The available subject condition types are:
    Authenticated Users
    Any user that has successfully authenticated with OpenAM.
    Users & Groups
    A user or group as defined in the Subjects pages of the realm the policy is created in.
    Select one or more users or groups from the User Subjects or Group Subjects drop-down lists, which display the subjects and groups available within the realm.
    To remove an entry, click the value, and then press Delete (Windows/GNU/Linux) or Backspace (Mac OS X).
    OpenID Connect/Jwt Claim
    Validate a claim within a JSON Web Token (JWT).
    Type the name of the claim to validate in the Claim Name field, for example sub, and the required value in the Claim Value field, and then click the checkmark.
    Repeat the step to enter additional claims.
    The claim(s) will be part of the JWT payload together with the JWT header and signature. The JWT is sent in the authorization header of the bearer token.
    This condition type only supports string equality comparisons, and is case-sensitive.
    Never Match
    Never match any subject. Has the effect of disabling the policy, as it will never match a subject.
    If you do not set a subject condition, "Never Match" is the default. In other words, you must set a subject condition for the policy to apply.
    To match regardless of the subject, configure a subject condition that is "Never Match" inside a logical Not block.
  2. To add a logical operator, click the Add a Logical Operator button, choose between All Of, Not, and Any Of from the drop-down menu, and then drag the block into a valid drop point in the rule set above.
  3. Continue combining logical operators and subject conditions. To edit an item, click the Edit button. To remove an item, click the Delete button. When complete, click Save Changes.
2. To configure environment conditions in the policy, complete the following steps on the Environments tab:
  1. To add an environment condition, click the Environment Condition button, choose the type from the drop-down menu, specify any required parameters, and then drag the block into a drop-point in a logical block above.
    The available environment condition types are:
    Active Session Time
    Make the policy test how long the user's stateful or stateless session has been active, as specified in Max Session Time. To terminate the session if it has been active for longer than the specified time, set Terminate Sessions to True. The user will need to re-authenticate.
    Authentication by Module Chain
    Make the policy test the service that was used to authenticate the user.
    Authentication by Module Instance
    Make the policy test the authentication module used to authenticate, specified in Authentication Scheme. Specify a timeout for application authentication in Application Idle Timeout Scheme and the name of the application in Application Name.
    Authentication Level (greater than or equal to)
    Make the policy test the minimum acceptable authentication level specified in Authentication Level.
    Authentication to a Realm
    Make the policy test the realm to which the user authenticated.
    Current Session Properties
    Make the policy test property values set in the user's stateful or stateless session.
    Set Ignore Value Case to True to make the test case-insensitive.
    Specify one or more pairs of session properties and values using the format property:value. For example, specify clientType:genericHTML to test whether the value of the clientType property is equal togenericHTML.
    Identity Membership
    Make the policy apply if the UUID of the invocator is a member of at least one of the AMIdentity objects specified in AM Identity Name.
    Often used to filter requests on the identity of a Web Service Client (WSC).
    IPv4 Address/DNS Name
    Make the policy test the IP version 4 address that the request originated from.
    The IP address is taken from the requestIp value of policy decision requests. If this is not provided, the IP address stored in the SSO token is used instead.
    Specify a range of addresses to test against by entering four sets of up to three digits, separated by full stops (.) in both Start IP and End IP.
    If only one of these values is provided, it is used as a single IP address to match.
    Optionally, specify a DNS name in DNS Name to filter requests to that domain.
    IPv6 Address/DNS Name
    Make the policy test the IP version 6 address that the request originated from.
    The IP address is taken from the requestIp value of policy decision requests. If this is not provided, the IP address stored in the SSO token is used instead.
    Specify a range of addresses to test against by entering eight sets of four hexadecimal characters, separated by a colon (:) in both Start IP and End IP.
    If only one of these values is provided, it is used as a single IP address to match.
    Optionally, specify a DNS name in DNS Name to filter requests to those coming from the specified domain.
    Use an asterisk (*) in the DNS name to match multiple subdomains. For example *.example.com applies to requests coming from www.example.com, secure.example.com, or any other subdomain of example.com.
    LDAP Filter Condition
    Make the policy test whether the user's entry can be found using the LDAP search filter you specify in the directory configured for the policy service, which by default is the identity repository. Navigate to Configure > Global Services, and then click Policy Configuration to see the global LDAP configuration.
    Alternatively, to configure these settings for a realm, navigate to Realms > Realm Name > Services, and then click Policy Configuration.
    OAuth2 Scope
    Make the policy test whether an authorization request includes all of the specified OAuth 2.0 scopes.
    Scope names must follow OAuth 2.0 scope syntax described in RFC 6749, Access Token Scope . As described in that section, separate multiple scope strings with spaces, such as openid profile.
    The scope strings match regardless of order in which they occur, so openid profile is equivalent to profile openid.
    The condition is also met when additional scope strings are provided beyond those required to match the specified list. For example, if the condition specifies openid profile, then openid profile email also matches.
    Resource/Environment/IP Address
    Make the policy apply to a complex condition such as whether the user is making a request from the localhost and has also authenticated with the LDAP authentication module.
    Entries must take the form of an IF...ELSE statement. The IF statement can specify either IP to match the user's IP address, or dnsName to match their DNS name.
    If the IF statement is true, the THEN statement must also be true for the condition to be fulfilled. If not, relevant advice is returned in the policy evaluation request.
    The available parameters for the THEN statement are as follows:
    module
    The module that was used to authenticate the user, for example DataStore.
    service
    The service that was used to authenticate the user.
    authlevel
    The minimum required authentication level.
    role
    The role of the authenticated user.
    user
    The name of the authenticated user.
    redirectURL
    The URL the user was redirected from.
    realm
    The realm that was used to authenticate the user.
    The IP address can be IPv4, IPv6, or a hybrid of the two.
    Example: IF IP=[127.0.0.1] THEN role=admins.
    Time (day, date, time, and timezone)
    Make the policy test when the policy is evaluated.
    The values for day, date and time must be set in pairs that comprise a start and an end.
    Create conditions that apply between a start and end date and time.
  2. To add a logical operator, click the Logical button, choose between All Of, Not, and Any Of from the drop-down menu, and then drag the block into a valid drop point in the rule set above.
  3. Continue combining logical operators and environment conditions, and when finished, click Save Changes.
(Optional) Add response attributes, retrieved from the user entry in the identity repository, into the headers of the request at policy decision time. The policy agent for the protected resources/applications or the protected resources/applications themselves retrieve the policy response attributes to customize or personalize the application. Policy response attributes come in two formats: subject attributes and static attributes.
To configure response attributes in the policy, complete the following steps on the Response attributes tab:
1. To add subject attributes, select them from the Subject attributes drop-down list
  To remove an entry, click the value, and then press Delete (Windows/GNU/Linux) or Backspace (Mac OS X)
2. To add a static attribute, specify the key-value pair for each static attribute. Enter the Property Name and its corresponding Property Value in the fields, and then click the Add (+) icon.
  Note
  To edit an entry, click the Edit icon in the row containing the attribute, or click the row itself. To remove an entry, click the Delete icon in the row containing the attribute.
3. Continue adding subject and static attributes, and when finished, click Save Changes.

3.3.4. Specifying Resource Patterns with Wildcards

Resource patterns can specify an individual URL or resource name to protect. Alternatively, a resource pattern can match URLs or resource names by using wildcards.

The wildcards you can use are * and -*-.
These wildcards can be used throughout resource patterns to match URLs or resource names. For a resource pattern used to match URLs, wildcards can be employed to match the scheme, host, port, path, and query string of a resource.
- When used within the path segment of a resource, the wildcard * matches multiple path segments.
  For example, http://www.example.com/* matches http://www.example.com/, http://www.example.com/index.html, and also http://www.example.com/company/images/logo.png.
- When used within the path segment of a resource, the wildcard -*- will only match a single path segment.
  For example, http://www.example.com/-*- matches http://www.example.com/index.html but does not match http://www.example.com/company/resource.html or http://www.example.com/company/images/logo.png.
Wildcards do not match ?. You must explicitly add patterns to match URLs with query strings.
- When matching URLs sent from a web policy or J2EE agent, an asterisk (*) used at the end of a pattern after a ? character matches one or more characters, not zero or more characters.
  For example, http://www.example.com/*?* matches http://www.example.com/users?_action=create, but not http://www.example.com/users?.
  To match everything under http://www.example.com/ specify three patterns, one for http://www.example.com/*, one for http://www.example.com/*?, and one for http://www.example.com/*?*.
- When matching resources by using the policies?_action=evaluate REST endpoint, an asterisk (*) used at the end of a pattern after a ? character matches zero or more characters.
  For example, http://www.example.com/*?* matches http://www.example.com/users?_action=create, as well as http://www.example.com/users?.
  To match everything under http://www.example.com/ specify two patterns, one for http://www.example.com/*, one for http://www.example.com/*?*.
When defining patterns to match URLs with query strings, OpenAM sorts the query string field-value pairs alphabetically by field name when normalizing URLs before checking whether a policy matches. Therefore the query string ?subject=SPBnfm+t5PlP+ISyQhVlplE22A8=&action=get is equivalent to the query string ?action=get&subject=SPBnfm+t5PlP+ISyQhVlplE22A8=.
Duplicate slashes (/) are not considered part of the resource name to match. A trailing slash is considered by OpenAM as part of the resource name.
For example, http://www.example.com//path/, and http://www.example.com/path// are treated in the same way.
http://www.example.com/path, and http://www.example.com/path/ are considered two distinct resources.
Wildcards can be used to match protocols, host names, and port numbers.
For example, *://*:*/* matches http://www.example.com:80/index.html, https://www.example.com:443/index.html, and http://www.example.net:8080/index.html.
When a port number is not explicitly specified, then the default port number is implied. Therefore http://www.example.com/* is the same as http://www.example.com:80/*, and https://www.example.com/* is the same as https://www.example.com:443/*.
Wildcards cannot be escaped.
Do not mix * and -*- in the same pattern.
By default, comparisons are not case sensitive. The delimiter, wildcards and case sensitivity are configurable. To see examples of other configurations, in the OpenAM Console, navigate to Configure > Global Services, click Policy Configuration, and scroll to Resource Comparator.

3.4. Importing and Exporting Policies

You can import and export policies to and from files.

You can use these files to backup policies, transfer policies between OpenAM instances, or store policy configuration in a version control system such as Git or Subversion.

OpenAM supports exporting policies in JSON and eXtensible Access Control Markup Language (XACML) Version 3.0 format. The features supported by each format are summarized in the table below:

Comparison of Policy Import/Export Formats

Feature	Supported?
Feature	JSON	XACML
Can be imported/exported from within the OpenAM console?	No	Yes
Can be imported/exported on the command line, using the ssoadm command?	Yes	Yes
Exports policies?	Yes	Yes
Exports policy sets?	Yes	Partial ^[a]
Exports resource types?	Yes	Partial ^[a]
Creates an exact copy of the original policy sets, resource types, and policies upon import?	Yes	Partial ^[b]
^[a]Only the details of policy sets and resource types that are actually used within a policy is exported to the XACML format. The full definition is not exported. ^[b]Policy sets and resource types will be generated from the details in the XML, but may not match the definitions of the originals, for example the names are auto-generated.

Note

OpenAM can only import XACML 3.0 files that were either created by an OpenAM instance, or that have had minor manual modifications, due to the reuse of some XACML 3.0 parameters for non-standard information.

You can import and export policies by using the policy editor in the OpenAM console, using the REST API, or with the ssoadm command.

"To Export Policies in XACML Format (OpenAM Console)"
"To Import Policies in XACML Format (OpenAM Console)"
"To Export Policies in JSON Format (Command Line)"
"To Import Policies in JSON Format (Command Line)"
"To Export Policies in XACML Format (Command Line)"
"To Import Policies in XACML Format (Command Line)"

For information on importing and exporting policies in XACML format by using the REST API, see "Importing and Exporting XACML 3.0" in the Developer's Guide.

To Export Policies in XACML Format (OpenAM Console)

In the OpenAM console, select Realms > Realm Name > Authorization > Policy Sets, and then click Export Policy Sets.
All policy sets, and the policies within will be exported in XACML format.

To Import Policies in XACML Format (OpenAM Console)

In the OpenAM console, select Realms > Realm Name > Authorization > Policy Sets, and then click Import Policy Sets.
Browse to the XACML format file, select it, and then click Open.
Any policy sets, and the policies within will be imported from the selected XACML format file.
Note
Policy sets and resource types will be generated from the details in the XACML format file, but may not match the definitions of the originals, for example the names are auto-generated.

To Export Policies in JSON Format (Command Line)

Use the ssoadm policy-export command:

$ ssoadm \
  policy-export \
  --realm "/" \
  --servername "http://openam.example.com:8080/openam" \
  --jsonfile "myPolicies.json" \
  --adminid amadmin \
  --password-file /tmp/pwd.txt

{
  "RESOURCE_TYPE" : 1,
  "POLICY" : 1,
  "APPLICATION" : 1
}

If exporting from a subrealm, include the top level realm ("/") in the --realm value. For example --realm "/myRealm".

For more information on the syntax of this command, see "ssoadm policy-export" in the Reference.

To Import Policies in JSON Format (Command Line)

Use the ssoadm policy-import command:

$ ssoadm \
  policy-import \
  --realm "/myRealm" \
  --servername "http://openam.example.com:8080/openam" \
  --jsonfile "myPolicies.json" \
  --adminid amadmin \
  --password-file /tmp/pwd.txt

{
  "POLICY" : {
    "CREATE_SUCCESS" : {
      "count" : 1
    }
  },
  "RESOURCE_TYPE" : {
    "CREATE_SUCCESS" : {
      "count" : 1
    }
  },
  "APPLICATION" : {
    "CREATE_SUCCESS" : {
      "count" : 1
    }
  }
}

If importing to a subrealm, include the top level realm ("/") in the --realm value. For example --realm "/myRealm".

For more information on the syntax of this command, see "ssoadm policy-import" in the Reference.

To Export Policies in XACML Format (Command Line)

Use the ssoadm list-xacml command:

$ ssoadm \
  list-xacml \
  --realm "/" \
  --adminid amadmin \
  --password-file /tmp/pwd.txt

 <?xml version="1.0" encoding="UTF-8"?>
 <PolicySet
 xmlns="urn:oasis:names:tc:xacml:3.0:core:schema:wd-17"
 PolicyCombiningAlgId="urn...rule-combining-algorithm:deny-overrides"
 Version="2014.11.25.17.41.15.597"
 PolicySetId="/:2014.11.25.17.41.15.597">
  <Target />
  <Policy
  RuleCombiningAlgId="urn...rule-combining-algorithm:deny-overrides"
  Version="2014.11.25.17.40.08.067"
  PolicyId="myPolicy">
  <Description />
  <Target>
   <AnyOf>
    <AllOf>
     <Match
      MatchId="urn...entitlement:json-subject-match">
      <AttributeValue
       DataType="urn...entitlement.conditions.subject.AuthenticatedUsers">
       {}
      </AttributeValue>
      <AttributeDesignator
       MustBePresent="true"
       DataType="urn...entitlement.conditions.subject.AuthenticatedUsers"
       AttributeId="urn...entitlement:json-subject"
       Category="urn:oasis:names:tc:xacml:1.0:subject-category:access-subject" />
     </Match>
    </AllOf>
   </AnyOf>
   <AnyOf>
    <AllOf>
     <Match
      MatchId="urn...entitlement:resource-match:application:iPlanetAMWebAgentService">
      <AttributeValue
       DataType="htp://www.w3.org/2001/XMLSchema#string">
       http://www.example.com:8000/*?*
      </AttributeValue>
      <AttributeDesignator
       MustBePresent="true"
       DataType="htp://www.w3.org/2001/XMLSchema#string"
       AttributeId="urn:oasis:names:tc:xacml:1.0:resource:resource-id"
       Category="urn...attribute-category:resource" />
     </Match>
    </AllOf>
   </AnyOf>
   <AnyOf>
    <AllOf>
     <Match
      MatchId="urn...application-match">
      <AttributeValue
       DataType="htp://www.w3.org/2001/XMLSchema#string">
       iPlanetAMWebAgentService
      </AttributeValue>
      <AttributeDesignator
       MustBePresent="false"
       DataType="htp://www.w3.org/2001/XMLSchema#string"
       AttributeId="urn...application-id"
       Category="urn...application-category" />
     </Match>
    </AllOf>
   </AnyOf>
   <AnyOf>
    <AllOf>
     <Match
      MatchId="urn...entitlement:action-match:application:iPlanetAMWebAgentService">
      <AttributeValue
       DataType="htp://www.w3.org/2001/XMLSchema#string">
       POST
      </AttributeValue>
      <AttributeDesignator
       MustBePresent="true"
       DataType="htp://www.w3.org/2001/XMLSchema#string"
       AttributeId="urn:oasis:names:tc:xacml:1.0:action:action-id"
       Category="urn...attribute-category:action" />
     </Match>
    </AllOf>
    <AllOf>
     <Match
      MatchId="urn...entitlement:action-match:application:iPlanetAMWebAgentService">
      <AttributeValue
       DataType="htp://www.w3.org/2001/XMLSchema#string">
       GET
      </AttributeValue>
      <AttributeDesignator
       MustBePresent="true"
       DataType="htp://www.w3.org/2001/XMLSchema#string"
       AttributeId="urn:oasis:names:tc:xacml:1.0:action:action-id"
       Category="urn...attribute-category:action" />
     </Match>
    </AllOf>
   </AnyOf>
  </Target>
  <VariableDefinition
   VariableId="....entitlement.applicationName">
   <AttributeValue
    DataType="htp://www.w3.org/2001/XMLSchema#string">
    iPlanetAMWebAgentService
   </AttributeValue>
  </VariableDefinition>
  <VariableDefinition
   VariableId="...privilege.createdBy">
   <AttributeValue
    DataType="htp://www.w3.org/2001/XMLSchema#string">
    id=amadmin,ou=user,dc=openam,dc=forgerock,dc=org
   </AttributeValue>
  </VariableDefinition>
  <VariableDefinition
   VariableId="...privilege.lastModifiedBy">
   <AttributeValue
    DataType="htp://www.w3.org/2001/XMLSchema#string">
    id=amadmin,ou=user,dc=openam,dc=forgerock,dc=org
   </AttributeValue>
  </VariableDefinition>
  <VariableDefinition
   VariableId="...privilege.creationDate">
   <AttributeValue
    DataType="htp://www.w3.org/2001/XMLSchema#dateTime">
    2014-11-25T17:40:08.067
   </AttributeValue>
  </VariableDefinition>
  <VariableDefinition
   VariableId="...privilege.lastModifiedDate">
   <AttributeValue
    DataType="htp://www.w3.org/2001/XMLSchema#dateTime">
    2014-11-25T17:40:08.067
   </AttributeValue>
  </VariableDefinition>
  <Rule
   Effect="Permit"
   RuleId="null:permit-rule">
   <Description>Permit Rule</Description>
   <Target>
    <AnyOf>
     <AllOf>
      <Match
       MatchId="urn...entitlement:action-match:application:iPlanetAMWebAgentService">
       <AttributeValue
        DataType="htp://www.w3.org/2001/XMLSchema#string">
        POST
       </AttributeValue>
       <AttributeDesignator
        MustBePresent="true"
        DataType="htp://www.w3.org/2001/XMLSchema#string"
        AttributeId="urn:oasis:names:tc:xacml:1.0:action:action-id"
        Category="urn...attribute-category:action" />
      </Match>
     </AllOf>
     <AllOf>
      <Match
       MatchId="urn...entitlement:action-match:application:iPlanetAMWebAgentService">
       <AttributeValue
        DataType="htp://www.w3.org/2001/XMLSchema#string">
        GET
       </AttributeValue>
       <AttributeDesignator
        MustBePresent="true"
        DataType="htp://www.w3.org/2001/XMLSchema#string"
        AttributeId="urn:oasis:names:tc:xacml:1.0:action:action-id"
        Category="urn...attribute-category:action" />
      </Match>
     </AllOf>
    </AnyOf>
   </Target>
   <Condition>
    <Apply
     FunctionId="urn...entitlement:json-subject-and-condition-satisfied">
     <AttributeValue
      DataType="urn...entitlement.conditions.subject.AuthenticatedUsers"
      privilegeComponent="entitlementSubject">
      {}
     </AttributeValue>
    </Apply>
   </Condition>
  </Rule>
 </Policy>
</PolicySet>

 Policy definitions were returned under realm, /.

For more information on the syntax of this command, see "ssoadm list-xacml" in the Reference.

To Import Policies in XACML Format (Command Line)

Use the ssoadm create-xacml command:

$ ssoadm \
  create-xacml \
  --realm "/" \
  --adminid amadmin \
  --password-file /tmp/pwd.txt \
  --xmlfile policy.xml

 Policies were created under realm, /.

For more information on the syntax of this command, see "ssoadm create-xacml" in the Reference.

3.5. Delegating Policy Management

To delegate policy management and other administrative tasks, use privileges. You set privileges in OpenAM console on the Privileges page for a realm.

For more information, see "Delegating Realm Administration Privileges".

Chapter 4. Configuring Realms

This chapter shows how to configure OpenAM realms, which are used to group configuration and identities together. For example, you might have one realm for OpenAM administrators and agents, and another realm for users. In this two-realm setup, the OpenAM administrator can log in to the administrative realm to manage the services, but cannot authenticate as OpenAM administrator to the realm that protects web sites with HR and financial information.

OpenAM associates a realm with at least one identity repository and authentication chain. OpenAM also associates the realm with authorization applications and their policies, and with privileges for administrators. Each realm can have its own configuration for the services it provides.

When you first configure OpenAM, OpenAM sets up the default Top Level Realm, sometimes referred to as the / realm or root realm. The Top Level Realm contains OpenAM configuration data and allows authentication using the identity repository that you choose during initial configuration. The Top Level Realm might hold the overall configuration for Example.com, for instance.

You create new realms to subdivide authentication and authorization, and to delegate management of subrealms. For example, your organization might require separate realms for payroll, human resources, and IT management domains and their applications.

By default a new realm inherits configuration from its parent's configuration. The default identity repository is the one you choose when you deploy and configure OpenAM. The default authentication mechanism corresponds to that identity repository as well. You can, however, constrain authentication to rely on different data stores, and set policy for agents to define authorization in the realm:

Note

OpenAM requires cookies for all configured realms when using DNS aliases. For example, if you install OpenAM in the domain, openam.example.net and have realms, identity.example.org and security.example.com then you must configure cookie domains for .example.net, .example.org, and .example.com. You can set up the cookie domains for each realm using the OpenAM console under Configuration > System > Platform > Cookie Domains, and then add the domains as needed.

4.1. Managing Realms

You create and configure realms through the console, starting from the Realms page. You delegate administration for a realm by setting privileges in the realm.

"To Create a New Realm"
"Delegating Realm Administration Privileges"

To Create a New Realm

You can create a new realm through the OpenAM console as described below, or by using the ssoadm create-realm command:

Log in to the OpenAM console as OpenAM Administrator, amadmin.
On the Realms page, click New Realm. The New Realm dialog box appears. Use this dialog box to configure the realm.
Note
Do not use the names of OpenAM REST endpoints as the name of a realm. The OpenAM REST endpoint names that should not be used include: "users", "groups", "realms", "policies" and "applications".
If you configure the realm to be inactive, then users cannot use it to authenticate or be granted access to protected resources.
Realm/DNS aliases must follow standard FQDN conventions, such as hr.example.com or pay.example.com.^[3]
Save your work after defining the configuration for the new realm.

4.1.1. Delegating Realm Administration Privileges

You assign administration privileges to groups of users.

You can grant privileges through the OpenAM console, see "To Delegate Privileges using the OpenAM Console", or by using the ssoadm add-privileges command, see "ssoadm add-privileges" in the Reference.

To Delegate Privileges using the OpenAM Console

On the Realms page, click the realm for which you want to delegate administration to view the realm configuration.
Delegating administration privileges in the top-level realm allows members of the group full administration access to the OpenAm instance. Administration privileges in any other realm allows the group to administrate only in that realm, and any child realms.
On the Privileges tab, click the name of the group to which you intend to grant access.
Select the administrative privileges to delegate for the realm:
- (Optional) To grant users in the group access to the administration console for the realm, select Read and write access to all realm and policy properties.
  In OpenAM 13.5.2-15, administrators can use the OpenAM administration console as follows:
  - Delegated administrators with the RealmAdmin privilege can access full administration console functionality within the realms they can administer.
  - Administrators with lesser privileges, such as the PolicyAdmin privilege, can not access the OpenAM administration console.
  - Both the top-level administrator (such as amadmin) and delegated administrators in the Top Level Realm with the RealmAdmin privilege have access to full console functionality in all realms and can access OpenAM's global configuration.
- (Optional) To grant users in the group access to REST endpoints, select them from the list.
For information about the available OpenAM privileges, see "OpenAM Privileges".
Save your work.

The following table describes privileges that you can assign in the OpenAM console or by using the ssoadm add-privileges command:

OpenAM Privileges

Privilege as it Appears in the Console	Privilege Name to Use With the ssoadm add-privileges Command	Notes
Read and write access to all realm and policy properties	`RealmAdmin`	Assign this privilege to administrators in order to let them modify or read any part of an OpenAM realm. Use this privilege when you do not require granularity in your delegation model. All other OpenAM privileges are included with this privilege. Administrators using the OpenAM administration console must have this privilege.
Read and write access to all log files	`LogAdmin`	Subset of the `RealmAdmin` privilege.
Read access to all log files	`LogRead`	Subset of the `RealmAdmin` privilege.
Write access to all log files	`LogWrite`	Subset of the `RealmAdmin` privilege.
Read and write access to all configured agents	`AgentAdmin`	Provides access to centralized agent configuration; subset of the `RealmAdmin` privilege.
Read and write access to all federation metadata configurations	`FederationAdmin`	Subset of the `RealmAdmin` privilege.
REST calls for reading realms	`RealmReadAccess`	Subset of the `RealmAdmin` privilege.
Read and write access only for policy properties, including REST calls	`PolicyAdmin`	Assign this privilege to policy administrators in order to let them modify or read any part of the OpenAM policy configuration. This privilege lets an administrator modify or read all policy components: policies, applications, subject types, condition types, subject attributes, and decision combiners. All other OpenAM privileges that affect policy components are included with this privilege. Subset of the `RealmAdmin` privilege.
REST calls for policy evaluation	`EntitlementRestAccess`	Subset of the `RealmAdmin` and `PolicyAdmin` privileges.
REST calls for reading policies	`PrivilegeRestReadAccess`	Subset of the `RealmAdmin` and `PolicyAdmin` privileges.
REST calls for managing policies	`PrivilegeRestAccess`	Subset of the `RealmAdmin` and `PolicyAdmin` privileges.
REST calls for reading policy applications	`ApplicationReadAccess`	Subset of the `RealmAdmin` and `PolicyAdmin` privileges.
REST calls for modifying policy applications	`ApplicationModifyAccess`	Subset of the `RealmAdmin` and `PolicyAdmin` privileges.
REST calls for modifying policy resource types	`ResourceTypeModifyAccess`	Subset of the `RealmAdmin` and `PolicyAdmin` privileges.
REST calls for reading policy resource types	`ResourceTypeReadAccess`	Subset of the `RealmAdmin` and `PolicyAdmin` privileges.
REST calls for reading policy application types	`ApplicationTypesReadAccess`	Subset of the `RealmAdmin` and `PolicyAdmin` privileges.
REST calls for reading environment conditions	`ConditionTypesReadAccess`	Subset of the `RealmAdmin` and `PolicyAdmin` privileges.
REST calls for reading subject conditions	`SubjectTypesReadAccess`	Subset of the `RealmAdmin` and `PolicyAdmin` privileges.
REST calls for reading decision combiners	`DecisionCombinersReadAccess`	Subset of the `RealmAdmin` and `PolicyAdmin` privileges.
REST calls for reading subject attributes	`SubjectAttributesReadAccess`	Subset of the `RealmAdmin` and `PolicyAdmin` privileges.
REST calls for modifying session properties	`SessionPropertyModifyAccess`	Subset of the `RealmAdmin` and `PolicyAdmin` privileges.

4.2. Working With Realms and Policy Agents

You can configure a policy agent to be directed to a realm and application when requesting policy decisions, or to log users into a different realm than the policy agent's realm:

"To Specify the Realm and Application for Policy Decisions"
"To Configure a Web or J2EE Agent for Log In to a Realm"

To Specify the Realm and Application for Policy Decisions

By default, policy agents request policy decisions in the Top Level Realm (/) from the default policy set, iPlanetAMWebAgentService. When the realm and policy set differ for your policy agent, you can specify the realm and policy set in the policy agent profile. OpenAM then directs requests from the policy agent to the specified realm and policy set, so this is backwards compatible with existing policy agents.

In the OpenAM console, browse to Realms > Realm Name > Agents > Web or Java EE Agent Type > Agent Name > OpenAM Services > Policy Client Service.
Set the Realm and Policy Set.
Note that Policy Sets are labelled as "Application" in some parts of the user interface.
For example, if the realm is /hr and the policy set is myHRApp:
- Realm: /hr
- Application: myHRApp
Save your work.

To Configure a Web or J2EE Agent for Log In to a Realm

You might choose to configure your agent in one realm, yet have your real users authenticate through another realm. In this case, you want your policy agents to redirect users to authenticate to their realm, rather than the agent realm:

In the OpenAM console, browse to Realms > Realm Name > Agents > Web or Java EE Agent Type > Agent Name > OpenAM Services.
Add login and logout URLs, including the realm in the query string.
For example, if your Realm Name is hr, and you access OpenAM at http://openam.example.com:8080/openam:
- Login URL: http://openam.example.com:8080/openam/UI/Login?realm=hr
- Logout URL: http://openam.example.com:8080/openam/UI/Logout?realm=hr
Save your work.

4.3. Configuring Data Stores

When you first set up a realm, the new realm inherits the data store from the parent realm. Yet, if your administrators are in one realm and your users in another, your new child realm might retrieve users from a different data store.

To Configure a Data Store

An external identity repository is a user store other than the OpenAM embedded repository. Before configuring an OpenAM data store as an external identity repository, make sure that you have prepared the external identity repository for OpenAM. For more information, see "Preparing an External Identity Repository" in the Installation Guide.
In the OpenAM console, browse to Realms > Realm Name > Data Stores.
Click New in the Data Stores table to create a data store profile, and to provide the information needed to connect to the data store.
In the first screen, name the data store and select the type of data store.
Most data stores are directory services, though the Database Repository lets you connect to an SQL database through JDBC.
In the second screen, provide information on how to connect to your data store, and then click Finish to save your work.
See the following sections for hints depending on the type of data store.
You must index several directory attributes as a post-configuration step if you configured the data store as follows:
- You configured the data store to access an external identity repository.
- You used the "Load schema when finished" option.
For more information about indexing external identity repository attributes, see "To Index External Identity Repository Attributes" in the Installation Guide.
Click the Subjects tab, and make sure the connection to your new data store is working, by searching for a known identity.
By default the Subjects list only retrieves 100 entries from the data store. Narrow your search if you do not see the identity you are looking for.
If you no longer need the connection to the inherited data store in this realm, then you can delete its entry in the Data Stores table.
Also, once you change the data store for a realm, you might opt to change the authentication module configuration to use your realm data store, rather than the inherited settings. See "Configuring Authentication Modules".

4.3.1. Hints for Configuring Active Directory Data Stores

Use these hints when configuring Active Directory Data Stores:

ssoadm service name: sunIdentityRepositoryService

Name

Name for the data store configuration

Load schema when finished

Add appropriate LDAP schema to the directory server when saving the configuration. The LDAP Bind DN user must have access to perform this operation.

This attribute is not available for use with the ssoadm command.

Default: false

LDAP Server

host:port to contact the directory server, with optional |server_ID|site_ID for deployments with multiple servers and sites.

OpenAM uses the optional settings to determine which directory server to contact first. OpenAM tries to contact directory servers in the following priority order, with highest priority first:

The first directory server in the list whose server_ID matches the current OpenAM server.
The first directory server in the list whose site_ID matches the current OpenAM server.
The first directory server in the remaining list.

If the directory server is not available, OpenAM proceeds to the next directory server in the list.

ssoadm attribute: sun-idrepo-ldapv3-config-ldap-server

Default: host:port of the initial directory server configured for this OpenAM server.

LDAP Bind DN

Bind DN for connecting to the directory server. Some OpenAM capabilities require write access to directory entries.

ssoadm attribute: sun-idrepo-ldapv3-config-authid

Default: CN=Administrator,CN=Users,base-dn

LDAP Bind Password

Bind password for connecting to the directory server

ssoadm attribute: sun-idrepo-ldapv3-config-authpw

LDAP Organization DN

The base DN under which to find user and group profiles.

ssoadm attribute: sun-idrepo-ldapv3-config-organization_name

Default: base-dn

LDAP SSL/TLS Enabled

Whether to use LDAPS or StartTLS to connect to the directory server. If you enable SSL or StartTLS, OpenAM must be able to trust server certificates, either because the server certificates were signed by a CA whose certificate is already included in the trust store used by the container where OpenAM runs, or because you imported the certificates into the trust store.

ssoadm attribute: sun-idrepo-ldapv3-config-connection-mode

Possible values: LDAP, LDAPS, and StartTLS

LDAP Connection Pool Maximum Size

Maximum number of connections to the directory server. Make sure the directory service can cope with the maximum number of client connections across all servers.

ssoadm attribute: sun-idrepo-ldapv3-config-connection_pool_max_size

Default: 10

LDAP Connection Heartbeat Interval

How often to send a heartbeat request to the directory server to ensure that the connection does not remain idle. Some network administrators configure firewalls and load balancers to drop connections that are idle for too long. You can turn this off by setting the value to 0 or to a negative number. To set the units for the interval use LDAP Connection Heartbeat Time Unit.

ssoadm attribute: openam-idrepo-ldapv3-heartbeat-interval

Default: 10

LDAP Connection Heartbeat Time Unit

Time unit for the LDAP Connection Heartbeat Interval setting.

ssoadm attribute: openam-idrepo-ldapv3-heartbeat-timeunit

Default: SECONDS

Maximum Results Returned from Search

A cap for the number of search results to request. For example, when using the Subjects tab to view profiles, even if you set Configuration > Console > Administration > Maximum Results Returned from Search to a larger number, OpenAM does not exceed this setting. Rather than raise this number, consider narrowing your search to match fewer directory entries.

ssoadm attribute: sun-idrepo-ldapv3-config-max-result

Default: 1000

Search Timeout

Maximum time to wait for search results in seconds. Does not apply to persistent searches.

ssoadm attribute: sun-idrepo-ldapv3-config-time-limit

Default: 10

LDAPv3 Plugin Search Scope

LDAP searches can apply to a single entry (SCOPE_BASE), entries directly below the search DN (SCOPE_ONE), or all entries below the search DN (SEARCH_SUB)

ssoadm attribute: sun-idrepo-ldapv3-config-search-scope

Default: SCOPE_SUB

LDAPv3 Repository Plugin Class Name

OpenAM identity repository implementation.

ssoadm attribute: sunIdRepoClass

Default: org.forgerock.openam.idrepo.ldap.DJLDAPv3Repo

Attribute Name Mapping

Map of OpenAM profile attribute names to directory server attribute names.

ssoadm attribute: sunIdRepoAttributeMapping

Default: userPassword=unicodePwd

LDAPv3 Plugin Supported Types and Operations

Map of OpenAM operations that can be performed in the specified OpenAM contexts.

ssoadm attribute: sunIdRepoSupportedOperations

Default: group=read,create,edit,delete, realm=read,create,edit,delete,service, user=read,create,edit,delete

LDAP Users Search Attribute

When searching for a user by name, match values against this attribute.

ssoadm attribute: sun-idrepo-ldapv3-config-users-search-attribute

Default: cn

Warning

Do not modify the value of the search attribute in user profiles. Modifying this attribute value can result in incorrectly cached identity data. For example, if you configure the search attribute to mail, it could prevent users from being able to update their email addresses in their user profiles.

LDAP Users Search Filter

When searching for users, apply this LDAP search filter as well.

ssoadm attribute: sun-idrepo-ldapv3-config-users-search-filter

Default: (objectclass=person)

LDAP People Container Naming Attribute

RDN attribute of the LDAP base DN which contains user profiles.

ssoadm attribute: sun-idrepo-ldapv3-config-people-container-name

Default: cn

LDAP People Container Value

RDN attribute value of the LDAP base DN which contains user profiles.

ssoadm attribute: sun-idrepo-ldapv3-config-people-container-value

Default: users

LDAP User Object Class

User profiles have these LDAP object classes.

OpenAM handles only those attributes listed in this setting. OpenAM discards any such unlisted attributes from requests and the request proceeds without the attribute.

For example, with default settings, if you request that OpenAM execute a search that asks for the mailAlternateAddress attribute, OpenAM does the search, but does not request mailAlternateAddress. In the same way, OpenAM does perform an update operation with a request to set the value of an unlisted attribute like mailAlternateAddress, but it drops the unlisted attribute from the update request.

ssoadm attribute: sun-idrepo-ldapv3-config-user-objectclass

Default: organizationalPerson, person, top, User,

LDAP User Attributes

User profiles have these LDAP attributes.

ssoadm attribute: sun-idrepo-ldapv3-config-user-attributes

Default: assignedDashboard, cn, devicePrintProfiles, displayName, distinguishedName, dn, employeeNumber, givenName, iplanet-am-auth-configuration, iplanet-am-session-add-session-listener-on-all-sessions, iplanet-am-session-destroy-sessions, iplanet-am-session-get-valid-sessions, iplanet-am-session-max-caching-time, iplanet-am-session-max-idle-time, iplanet-am-session-max-session-time, iplanet-am-session-quota-limit, iplanet-am-session-service-status, iplanet-am-user-account-life, iplanet-am-user-admin-start-dn, iplanet-am-user-alias-list, iplanet-am-user-auth-config, iplanet-am-user-auth-modules, iplanet-am-user-failure-url, iplanet-am-user-federation-info-key, iplanet-am-user-federation-info, iplanet-am-user-login-status, iplanet-am-user-password-reset-force-reset, iplanet-am-user-password-reset-options, iplanet-am-user-password-reset-question-answer, iplanet-am-user-success-url, mail, name, objectclass, objectGUID, postalAddress, preferredlanguage, preferredLocale, preferredtimezone, sAMAccountName, sn, sun-fm-saml2-nameid-info, sun-fm-saml2-nameid-infokey, sunAMAuthInvalidAttemptsData, sunIdentityMSISDNNumber, sunIdentityServerDiscoEntries, sunIdentityServerPPAddressCard, sunIdentityServerPPCommonNameAltCN, sunIdentityServerPPCommonNameCN, sunIdentityServerPPCommonNameFN, sunIdentityServerPPCommonNameMN, sunIdentityServerPPCommonNamePT, sunIdentityServerPPCommonNameSN, sunIdentityServerPPDemographicsAge, sunIdentityServerPPDemographicsBirthDay, sunIdentityServerPPDemographicsDisplayLanguage, sunIdentityServerPPDemographicsLanguage, sunIdentityServerPPDemographicsTimeZone, sunIdentityServerPPEmergencyContact, sunIdentityServerPPEmploymentIdentityAltO, sunIdentityServerPPEmploymentIdentityJobTitle, sunIdentityServerPPEmploymentIdentityOrg, sunIdentityServerPPEncryPTKey, sunIdentityServerPPFacadegreetmesound, sunIdentityServerPPFacadeGreetSound, sunIdentityServerPPFacadeMugShot, sunIdentityServerPPFacadeNamePronounced, sunIdentityServerPPFacadeWebSite, sunIdentityServerPPInformalName, sunIdentityServerPPLegalIdentityAltIdType, sunIdentityServerPPLegalIdentityAltIdValue, sunIdentityServerPPLegalIdentityDOB, sunIdentityServerPPLegalIdentityGender, sunIdentityServerPPLegalIdentityLegalName, sunIdentityServerPPLegalIdentityMaritalStatus, sunIdentityServerPPLegalIdentityVATIdType, sunIdentityServerPPLegalIdentityVATIdValue, sunIdentityServerPPMsgContact, sunIdentityServerPPSignKey, telephoneNumber, unicodePwd, userAccountControl, userpassword, userPrincipalname

Create User Attribute Mapping

When creating a user profile, apply this map of OpenAM profile attribute names to directory server attribute names.

The LDAP user profile entries require the Common Name (cn) and Surname (sn) attributes, so that LDAP constraint violations do not occur when performing an add operation.

The cn attribute gets its value from the uid attribute, which comes from the User Name field on the console's login page. The sn attribute gets the value of the givenName attribute. Attributes not mapped to another attribute and attributes mapped to themselves (for example, cn=cn) take the value of the username unless the attribute values are provided when creating the profile.

ssoadm attribute: sun-idrepo-ldapv3-config-createuser-attr-mapping

Default: cn, sn

Attribute Name of User Status

Attribute to check/set user status.

ssoadm attribute: sun-idrepo-ldapv3-config-isactive

Default: userAccountControl

User Status Active Value

Active users have the user status attribute set to this value.

ssoadm attribute: sun-idrepo-ldapv3-config-active

Default: 544

User Status Inactive Value

Inactive users have the user status attribute set to this value.

ssoadm attribute: sun-idrepo-ldapv3-config-inactive

Default: 546

Authentication Naming Attribute

RDN attribute for building the bind DN when given a username and password to authenticate a user against the directory server.

ssoadm attribute: sun-idrepo-ldapv3-config-auth-naming-attr

Default: cn

LDAP Groups Search Attribute

When searching for a group by name, match values against this attribute.

ssoadm attribute: sun-idrepo-ldapv3-config-groups-search-attribute

Default: cn

LDAP Groups Search Filter

When searching for groups, apply this LDAP search filter as well.

ssoadm attribute: sun-idrepo-ldapv3-config-groups-search-filter

Default: (objectclass=group)

LDAP Groups Container Naming Attribute

RDN attribute of the LDAP base DN which contains group profiles.

ssoadm attribute: sun-idrepo-ldapv3-config-group-container-name

Default: cn

LDAP Groups Container Value

RDN attribute value of the LDAP base DN which contains group profiles.

ssoadm attribute: sun-idrepo-ldapv3-config-group-container-value

Default: users

LDAP Groups Object Class

Group profiles have these LDAP object classes.

ssoadm attribute: sun-idrepo-ldapv3-config-group-objectclass

Default: Group, top

LDAP Groups Attributes

Group profiles have these LDAP attributes.

ssoadm attribute: sun-idrepo-ldapv3-config-group-attributes

Default: cn, distinguishedName, dn, member, name, objectCategory, objectclass, sAMAccountName, sAMAccountType

Attribute Name for Group Membership

LDAP attribute in the member's LDAP entry whose values are the groups to which a member belongs.

ssoadm attribute: sun-idrepo-ldapv3-config-memberof

Attribute Name of Unique Member

Attribute in the group's LDAP entry whose values are the members of the group.

ssoadm attribute: sun-idrepo-ldapv3-config-uniquemember

Default: member

Persistent Search Base DN

Base DN for LDAP-persistent searches used to receive notification of changes in directory server data.

ssoadm attribute: sun-idrepo-ldapv3-config-psearchbase

Default: base-dn

Persistent Search Scope

LDAP searches can apply to a single entry (SCOPE_BASE), entries directly below the search DN (SCOPE_ONE), or all entries below the search DN (SEARCH_SUB).

Specify either SCOPE_BASE or SCOPE_ONE. Do not specify SCOPE_SUB, as it can have a severe impact on Active Directory performance.

ssoadm attribute: sun-idrepo-ldapv3-config-psearch-scope

Default: SCOPE_SUB

The Delay Time Between Retries

How long to wait after receiving an error result that indicates OpenAM should try the LDAP operation again.

ssoadm attribute: com.iplanet.am.ldap.connection.delay.between.retries

Default: 1000 milliseconds

DN Cache Enabled

Whether to enable the DN cache, which is used to cache DN lookups that can happen in bursts during authentication. As the cache can become stale when a user is moved or renamed, enable DN caching when the directory service allows move/rename operations (Mod DN), and when OpenAM uses persistent searches to obtain notification of such updates.

ssoadm attribute: sun-idrepo-ldapv3-dncache-enabled

Default: false

DN Cache Size

Maximum number of DNs cached when caching is enabled.

ssoadm attribute: sun-idrepo-ldapv3-dncache-size

Default: 1500 items

4.3.2. Hints for Configuring Active Directory Application Mode Data Stores

Use these hints when configuring Active Directory Application Mode (ADAM) Data Stores.

ssoadm service name: sunIdentityRepositoryService

Name

Name for the data store configuration.

Load schema when finished

Add appropriate LDAP schema to the directory server when saving the configuration. The LDAP Bind DN user must have access to perform this operation.

This attribute is not available for use with the ssoadm command.

Default: false

LDAP Server

host:port to contact the directory server, with optional |server_ID|site_ID for deployments with multiple servers and sites.

OpenAM uses the optional settings to determine which directory server to contact first. OpenAM tries to contact directory servers in the following priority order, with highest priority first:

The first directory server in the list whose server_ID matches the current OpenAM server.
The first directory server in the list whose site_ID matches the current OpenAM server.
The first directory server in the remaining list.

If the directory server is not available, OpenAM proceeds to the next directory server in the list.

ssoadm attribute: sun-idrepo-ldapv3-config-ldap-server

Default: host:port of the initial directory server configured for this OpenAM server.

LDAP Bind DN

Bind DN for connecting to the directory server. Some OpenAM capabilities require write access to directory entries.

ssoadm attribute: sun-idrepo-ldapv3-config-authid

Default: CN=Administrator,CN=Users,base-dn

LDAP Bind Password

Bind password for connecting to the directory server.

ssoadm attribute: sun-idrepo-ldapv3-config-authpw

LDAP Organization DN

The base DN under which to find user and group profiles.

ssoadm attribute: sun-idrepo-ldapv3-config-organization_name

Default: base-dn

LDAP SSL/TLS Enabled

Whether to use LDAPS or StartTLS to connect to the directory server. If you enable SSL or StartTLS, OpenAM must be able to trust server certificates, either because the server certificates were signed by a CA whose certificate is already included in the trust store used by the container where OpenAM runs, or because you imported the certificates into the trust store.

ssoadm attribute: sun-idrepo-ldapv3-config-connection-mode

Possible values: LDAP, LDAPS, and StartTLS

LDAP Connection Pool Maximum Size

Maximum number of connections to the directory server. Make sure the directory service can cope with the maximum number of client connections across all servers.

ssoadm attribute: sun-idrepo-ldapv3-config-connection_pool_max_size

Default: 10

LDAP Connection Heartbeat Interval

How often to send a heartbeat request to the directory server to ensure that the connection does not remain idle. Some network administrators configure firewalls and load balancers to drop connections that are idle for too long. You can turn this off by setting the value to 0 or to a negative number. To set the units for the interval, use LDAP Connection Heartbeat Time Unit.

ssoadm attribute: openam-idrepo-ldapv3-heartbeat-interval

Default: 10

LDAP Connection Heartbeat Time Unit

Time unit for the LDAP Connection Heartbeat Interval setting

ssoadm attribute: openam-idrepo-ldapv3-heartbeat-timeunit

Default: second

Maximum Results Returned from Search

A cap for the number of search results to request. For example, when using the Subjects tab to view profiles, even if you set Configuration > Console > Administration > Maximum Results Returned from Search to a larger number, OpenAM does not exceed this setting. Rather than raise this number, consider narrowing your search to match fewer directory entries.

ssoadm attribute: sun-idrepo-ldapv3-config-max-result

Default: 1000

Search Timeout

Maximum time to wait for search results in seconds. Does not apply to persistent searches.

ssoadm attribute: sun-idrepo-ldapv3-config-time-limit

Default: 10

LDAPv3 Plugin Search Scope

LDAP searches can apply to a single entry (SCOPE_BASE), entries directly below the search DN (SCOPE_ONE), or all entries below the search DN (SEARCH_SUB).

ssoadm attribute: sun-idrepo-ldapv3-config-search-scope

Default: SCOPE_SUB

LDAPv3 Repository Plugin Class Name

OpenAM identity repository implementation.

ssoadm attribute: sunIdRepoClass

Default: org.forgerock.openam.idrepo.ldap.DJLDAPv3Repo

Attribute Name Mapping

Map of OpenAM profile attribute names to directory server attribute names.

ssoadm attribute: sunIdRepoAttributeMapping

Default: userPassword=unicodePwd

LDAPv3 Plugin Supported Types and Operations

Map of OpenAM operations that can be performed in the specified OpenAM contexts.

ssoadm attribute: sunIdRepoSupportedOperations

Default: group=read,create,edit,delete, realm=read,create,edit,delete,service, user=read,create,edit,delete

LDAP Users Search Attribute

When searching for a user by name, match values against this attribute.

ssoadm attribute: sun-idrepo-ldapv3-config-users-search-attribute

Default: cn

Warning

Do not modify the value of the search attribute in user profiles. Modifying this attribute value can result in incorrectly cached identity data. For example, if you configure the search attribute to mail, it could prevent users from being able to update their email addresses in their user profiles.

LDAP Users Search Filter

When searching for users, apply this LDAP search filter as well.

ssoadm attribute: sun-idrepo-ldapv3-config-users-search-filter

Default: (objectclass=person)

LDAP People Container Naming Attribute

RDN attribute of the LDAP base DN which contains user profiles.

ssoadm attribute: sun-idrepo-ldapv3-config-people-container-name

LDAP People Container Value

RDN attribute value of the LDAP base DN which contains user profiles.

ssoadm attribute: sun-idrepo-ldapv3-config-people-container-value

LDAP User Object Class

User profiles have these LDAP object classes.

OpenAM handles only those attributes listed in this setting. OpenAM discards any unlisted attributes from requests and the request proceeds without the attribute.

For example, with default settings, if you request that OpenAM execute a search that asks for the mailAlternateAddress attribute, OpenAM does the search, but does not request mailAlternateAddress. In the same way, OpenAM does perform an update operation with a request to set the value of an unlisted attribute like mailAlternateAddress, but it drops the unlisted attribute from the update request.

ssoadm attribute: sun-idrepo-ldapv3-config-user-objectclass

Default: devicePrintProfilesContainer, forgerock-am-dashboard-service, iplanet-am-auth-configuration-service, iplanet-am-managed-person, iplanet-am-user-service, iPlanetPreferences, organizationalPerson, person, sunAMAuthAccountLockout, sunFederationManagerDataStore, sunFMSAML2NameIdentifier, sunIdentityServerLibertyPPService, top, User

LDAP User Attributes

User profiles have these LDAP attributes.

OpenAM handles only those attributes listed in this setting. OpenAM discards any unlisted attributes from requests and the request proceeds without the attribute.

ssoadm attribute: sun-idrepo-ldapv3-config-user-attributes

Default: assignedDashboard, cn, devicePrintProfiles, displayName, distinguishedName, dn, employeeNumber, givenName, iplanet-am-auth-configuration, iplanet-am-session-add-session-listener-on-all-sessions, iplanet-am-session-destroy-sessions, iplanet-am-session-get-valid-sessions, iplanet-am-session-max-caching-time, iplanet-am-session-max-idle-time, iplanet-am-session-max-session-time, iplanet-am-session-quota-limit, iplanet-am-session-service-status, iplanet-am-user-account-life, iplanet-am-user-admin-start-dn, iplanet-am-user-alias-list, iplanet-am-user-auth-config, iplanet-am-user-auth-modules, iplanet-am-user-failure-url, iplanet-am-user-federation-info-key, iplanet-am-user-federation-info, iplanet-am-user-login-status, iplanet-am-user-password-reset-force-reset, iplanet-am-user-password-reset-options, iplanet-am-user-password-reset-question-answer, iplanet-am-user-success-url, mail, name, objectclass, objectGUID, postalAddress, preferredlanguage, preferredLocale, preferredtimezone, sAMAccountName, sn, sun-fm-saml2-nameid-info, sun-fm-saml2-nameid-infokey, sunAMAuthInvalidAttemptsData, sunIdentityMSISDNNumber, sunIdentityServerDiscoEntries, sunIdentityServerPPAddressCard, sunIdentityServerPPCommonNameAltCN, sunIdentityServerPPCommonNameCN, sunIdentityServerPPCommonNameFN, sunIdentityServerPPCommonNameMN, sunIdentityServerPPCommonNamePT, sunIdentityServerPPCommonNameSN, sunIdentityServerPPDemographicsAge, sunIdentityServerPPDemographicsBirthDay, sunIdentityServerPPDemographicsDisplayLanguage, sunIdentityServerPPDemographicsLanguage, sunIdentityServerPPDemographicsTimeZone, sunIdentityServerPPEmergencyContact, sunIdentityServerPPEmploymentIdentityAltO, sunIdentityServerPPEmploymentIdentityJobTitle, sunIdentityServerPPEmploymentIdentityOrg, sunIdentityServerPPEncryPTKey, sunIdentityServerPPFacadegreetmesound, sunIdentityServerPPFacadeGreetSound, sunIdentityServerPPFacadeMugShot, sunIdentityServerPPFacadeNamePronounced, sunIdentityServerPPFacadeWebSite, sunIdentityServerPPInformalName, sunIdentityServerPPLegalIdentityAltIdType, sunIdentityServerPPLegalIdentityAltIdValue, sunIdentityServerPPLegalIdentityDOB, sunIdentityServerPPLegalIdentityGender, sunIdentityServerPPLegalIdentityLegalName, sunIdentityServerPPLegalIdentityMaritalStatus, sunIdentityServerPPLegalIdentityVATIdType, sunIdentityServerPPLegalIdentityVATIdValue, sunIdentityServerPPMsgContact, sunIdentityServerPPSignKey, telephoneNumber, unicodePwd, userAccountControl, userpassword, userPrincipalname

Create User Attribute Mapping

When creating a user profile, apply this map of OpenAM profile attribute names to directory server attribute names.

Attributes not mapped to another attribute (for example, cn) and attributes mapped to themselves, (for example, cn=cn) take the value of the username unless the attribute values are provided when creating the profile. The object classes for user profile LDAP entries generally require Common Name (cn) and Surname (sn) attributes, so this prevents an LDAP constraint violation when performing the add operation.

ssoadm attribute: sun-idrepo-ldapv3-config-createuser-attr-mapping

Default: cn, sn

Attribute Name of User Status

Attribute to check/set user status.

ssoadm attribute: sun-idrepo-ldapv3-config-isactive

Default: msDS-UserAccountDisabled

User Status Active Value

Active users have the user status attribute set to this value.

ssoadm attribute: sun-idrepo-ldapv3-config-active

Default: FALSE

User Status Inactive Value

Inactive users have the user status attribute set to this value.

ssoadm attribute: sun-idrepo-ldapv3-config-inactive

Default: TRUE

Authentication Naming Attribute

RDN attribute for building the bind DN when given a username and password to authenticate a user against the directory server.

ssoadm attribute: sun-idrepo-ldapv3-config-auth-naming-attr

Default: cn

LDAP Groups Search Attribute

When searching for a group by name, match values against this attribute.

ssoadm attribute: sun-idrepo-ldapv3-config-groups-search-attribute

Default: cn

LDAP Groups Search Filter

When searching for groups, apply this LDAP search filter as well.

ssoadm attribute: sun-idrepo-ldapv3-config-groups-search-filter

Default: (objectclass=group)

LDAP Groups Container Naming Attribute

RDN attribute of the LDAP base DN which contains group profiles.

ssoadm attribute: sun-idrepo-ldapv3-config-group-container-name

Default: cn

LDAP Groups Container Value

RDN attribute value of the LDAP base DN which contains group profiles.

ssoadm attribute: sun-idrepo-ldapv3-config-group-container-value

LDAP Groups Object Class

Group profiles have these LDAP object classes.

ssoadm attribute: sun-idrepo-ldapv3-config-group-objectclass

Default: Group, top

LDAP Groups Attributes

Group profiles have these LDAP attributes.

ssoadm attribute: sun-idrepo-ldapv3-config-group-attributes

Default: cn, distinguishedName, dn, member, name, objectCategory, objectclass, sAMAccountName, sAMAccountType

Attribute Name for Group Membership

LDAP attribute in the member's LDAP entry whose values are the groups to which a member belongs.

ssoadm attribute: sun-idrepo-ldapv3-config-memberof

Attribute Name of Unique Member

Attribute in the group's LDAP entry whose values are the members of the group.

ssoadm attribute: sun-idrepo-ldapv3-config-uniquemember

Default: member

Persistent Search Base DN

Base DN for LDAP-persistent searches used to receive notification of changes in directory server data.

ssoadm attribute: sun-idrepo-ldapv3-config-psearchbase

Default: base-dn

Persistent Search Scope

LDAP searches can apply to a single entry (SCOPE_BASE), entries directly below the search DN (SCOPE_ONE), or all entries below the search DN (SEARCH_SUB).

Specify either SCOPE_BASE or SCOPE_ONE. Do not specify SCOPE_SUB, as it can have a severe impact on Active Directory performance.

ssoadm attribute: sun-idrepo-ldapv3-config-psearch-scope

Default: SCOPE_SUB

The Delay Time Between Retries

How long to wait after receiving an error result that indicates OpenAM should try the LDAP operation again.

ssoadm attribute: com.iplanet.am.ldap.connection.delay.between.retries

Default: 1000 milliseconds

DN Cache Enabled

Whether to enable the DN cache, which is used to cache DN lookups that can happen in bursts during authentication. As the cache can become stale when a user is moved or renamed, enable DN caching when the directory service allows move/rename operations (Mod DN), and when OpenAM uses persistent searches to obtain notification of such updates.

ssoadm attribute: sun-idrepo-ldapv3-dncache-enabled

Default: false

DN Cache Size

Maximum number of DNs cached when caching is enabled.

ssoadm attribute: sun-idrepo-ldapv3-dncache-size

Default: 1500 items

4.3.3. Hints for Configuring Generic LDAPv3 Data Stores

Use these hints when configuring Generic LDAPv3 compliant data stores.

ssoadm service name: sunIdentityRepositoryService

Name

Name for the data store configuration.

Load schema when finished

Add appropriate LDAP schema to the directory server when saving the configuration. The LDAP Bind DN user must have access to perform this operation.

This attribute is not available for use with the ssoadm command.

Default: false

LDAP Server

host:port to contact the directory server, with optional |server_ID|site_ID for deployments with multiple servers and sites.

OpenAM uses the optional settings to determine which directory server to contact first. OpenAM tries to contact directory servers in the following priority order, with highest priority first:

The first directory server in the list whose server_ID matches the current OpenAM server.
The first directory server in the list whose site_ID matches the current OpenAM server.
The first directory server in the remaining list.

If the directory server is not available, OpenAM proceeds to the next directory server in the list.

ssoadm attribute: sun-idrepo-ldapv3-config-ldap-server

Default: host:port of the initial directory server configured for this OpenAM server

LDAP Bind DN

Bind DN for connecting to the directory server. Some OpenAM capabilities require write access to directory entries.

ssoadm attribute: sun-idrepo-ldapv3-config-authid

LDAP Bind Password

Bind password for connecting to the directory server.

ssoadm attribute: sun-idrepo-ldapv3-config-authpw

LDAP Organization DN

The base DN under which to find user and group profiles.

ssoadm attribute: sun-idrepo-ldapv3-config-organization_name

Default: base-dn

LDAP SSL/TLS Enabled

Whether to use LDAPS or StartTLS to connect to the directory server. If you enable SSL or StartTLS, OpenAM must be able to trust server certificates, either because the server certificates were signed by a CA whose certificate is already included in the trust store used by the container where OpenAM runs, or because you imported the certificates into the trust store.

ssoadm attribute: sun-idrepo-ldapv3-config-connection-mode

Possible values: LDAP, LDAPS, and StartTLS

LDAP Connection Pool Maximum Size

Maximum number of connections to the directory server. Make sure the directory service can cope with the maximum number of client connections across all servers.

ssoadm attribute: sun-idrepo-ldapv3-config-connection_pool_max_size

Default: 10

LDAP Connection Heartbeat Interval

How often to send a heartbeat request to the directory server to ensure that the connection does not remain idle. Some network administrators configure firewalls and load balancers to drop connections that are idle for too long. You can turn this off by setting the value to 0 or to a negative number. To set the units for the interval, use LDAP Connection Heartbeat Time Unit.

ssoadm attribute: openam-idrepo-ldapv3-heartbeat-interval

Default: 10

LDAP Connection Heartbeat Time Unit

Time unit for the LDAP Connection Heartbeat Interval setting.

ssoadm attribute: openam-idrepo-ldapv3-heartbeat-timeunit

Default: second

Maximum Results Returned from Search

A cap for the number of search results to request. For example, when using the Subjects tab to view profiles, even if you set Configuration > Console > Administration > Maximum Results Returned from Search to a larger number, OpenAM does not exceed this setting. Rather than raise this number, consider narrowing your search to match fewer directory entries.

ssoadm attribute: sun-idrepo-ldapv3-config-max-result

Default: 1000

Search Timeout

Maximum time to wait for search results in seconds. Does not apply to persistent searches.

ssoadm attribute: sun-idrepo-ldapv3-config-time-limit

Default: 10

LDAPv3 Plugin Search Scope

LDAP searches can apply to a single entry (SCOPE_BASE), entries directly below the search DN (SCOPE_ONE), or all entries below the search DN (SEARCH_SUB).

ssoadm attribute: sun-idrepo-ldapv3-config-search-scope

Default: SCOPE_SUB

LDAPv3 Repository Plugin Class Name

OpenAM identity repository implementation.

ssoadm attribute: sunIdRepoClass

Default: org.forgerock.openam.idrepo.ldap.DJLDAPv3Repo

Attribute Name Mapping

Map of OpenAM profile attribute names to directory server attribute names.

ssoadm attribute: sunIdRepoAttributeMapping

LDAPv3 Plugin Supported Types and Operations

Map of OpenAM operations that can be performed in the specified OpenAM contexts.

ssoadm attribute: sunIdRepoSupportedOperations

Default: realm=read,create,edit,delete,service, user=read,create,edit,delete, group=read,create,edit,delete

LDAP Users Search Attribute

When searching for a user by name, match values against this attribute.

ssoadm attribute: sun-idrepo-ldapv3-config-users-search-attribute

Default: uid

Warning

Do not modify the value of the search attribute in user profiles. Modifying this attribute value can result in incorrectly cached identity data. For example, if you configure the search attribute to mail, it could prevent users from being able to update their email addresses in their user profiles.

LDAP Users Search Filter

When searching for users, apply this LDAP search filter as well.

ssoadm attribute: sun-idrepo-ldapv3-config-users-search-filter

Default: (objectclass=inetorgperson)

LDAP People Container Naming Attribute

RDN attribute of the LDAP base DN which contains user profiles.

ssoadm attribute: sun-idrepo-ldapv3-config-people-container-name

LDAP People Container Value

RDN attribute value of the LDAP base DN which contains user profiles.

ssoadm attribute: sun-idrepo-ldapv3-config-people-container-value

LDAP User Object Class

User profiles have these LDAP object classes.

OpenAM handles only those attributes listed in this setting. OpenAM discards any unlisted attributes from requests and the request proceeds without the attribute.

For example, with default settings, if you request that OpenAM execute a search that asks for the mailAlternateAddress attribute, OpenAM does the search, but does not request mailAlternateAddress. In the same way, OpenAM does perform an update operation with a request to set the value of an unlisted attribute like mailAlternateAddress, but it drops the unlisted attribute from the update request.

ssoadm attribute: sun-idrepo-ldapv3-config-user-objectclass

Default: inetorgperson, inetUser, organizationalPerson, person, top,

LDAP User Attributes

User profiles have these LDAP attributes.

OpenAM handles only those attributes listed in this setting. OpenAM discards any unlisted attributes from requests and the request proceeds without the attribute.

ssoadm attribute: sun-idrepo-ldapv3-config-user-attributes

Default: uid, caCertificate, authorityRevocationList, inetUserStatus, mail, sn, manager, userPassword, adminRole, objectClass, givenName, memberOf, cn, telephoneNumber, preferredlanguage, userCertificate, postalAddress, dn, employeeNumber, distinguishedName

Create User Attribute Mapping

When creating a user profile, apply this map of OpenAM profile attribute names to directory server attribute names.

Attributes not mapped to another attribute (for example, cn) and attributes mapped to themselves (for example, cn=cn) take the value of the username unless the attribute values are provided when creating the profile. The object classes for user profile LDAP entries generally require Common Name (cn) and Surname (sn) attributes, so this prevents an LDAP constraint violation when performing the add operation.

ssoadm attribute: sun-idrepo-ldapv3-config-createuser-attr-mapping

Default: cn, sn

Attribute Name of User Status

Attribute to check/set user status.

ssoadm attribute: sun-idrepo-ldapv3-config-isactive

Default: inetuserstatus

User Status Active Value

Active users have the user status attribute set to this value.

ssoadm attribute: sun-idrepo-ldapv3-config-active

Default: Active

User Status Inactive Value

Inactive users have the user status attribute set to this value.

ssoadm attribute: sun-idrepo-ldapv3-config-inactive

Default: Inactive

Authentication Naming Attribute

RDN attribute for building the bind DN when given a username and password to authenticate a user against the directory server.

ssoadm attribute: sun-idrepo-ldapv3-config-auth-naming-attr

Default: uid

LDAP Groups Search Attribute

When searching for a group by name, match values against this attribute.

ssoadm attribute: sun-idrepo-ldapv3-config-groups-search-attribute

Default: cn

LDAP Groups Search Filter

When searching for groups, apply this LDAP search filter as well.

ssoadm attribute: sun-idrepo-ldapv3-config-groups-search-filter

Default: (objectclass=groupOfUniqueNames)

LDAP Groups Container Naming Attribute

RDN attribute of the LDAP base DN which contains group profiles.

ssoadm attribute: sun-idrepo-ldapv3-config-group-container-name

Default: ou

LDAP Groups Container Value

RDN attribute value of the LDAP base DN which contains group profiles.

ssoadm attribute: sun-idrepo-ldapv3-config-group-container-value

Default: groups

LDAP Groups Object Class

Group profiles have these LDAP object classes.

ssoadm attribute: sun-idrepo-ldapv3-config-group-objectclass

Default: groupofuniquenames, top

LDAP Groups Attributes

Group profiles have these LDAP attributes.

ssoadm attribute: sun-idrepo-ldapv3-config-group-attributes

Default: ou, cn, description, dn, objectclass, uniqueMember

Attribute Name for Group Membership

LDAP attribute in the member's LDAP entry whose values are the groups to which a member belongs.

ssoadm attribute: sun-idrepo-ldapv3-config-memberof

Attribute Name of Unique Member

Attribute in the group's LDAP entry whose values are the members of the group.

ssoadm attribute: sun-idrepo-ldapv3-config-uniquemember

Default: uniqueMember

Attribute Name of Group Member URL

Attribute in the dynamic group's LDAP entry whose value is a URL specifying the members of the group.

ssoadm attribute: sun-idrepo-ldapv3-config-memberurl

Default: memberUrl

Default Group Member's User DN

DN of member added to all newly created groups.

ssoadm attribute: sun-idrepo-ldapv3-config-dftgroupmember

Persistent Search Base DN

Base DN for LDAP-persistent searches used to receive notification of changes in directory server data.

ssoadm attribute: sun-idrepo-ldapv3-config-psearchbase

Default: base-dn

Persistent Search Filter

LDAP filter to apply when performing persistent searches.

ssoadm attribute: sun-idrepo-ldapv3-config-psearch-filter

Default: (objectclass=*)

Persistent Search Scope

LDAP searches can apply to a single entry (SCOPE_BASE), entries directly below the search DN (SCOPE_ONE), or all entries below the search DN (SEARCH_SUB).

ssoadm attribute: sun-idrepo-ldapv3-config-psearch-scope

Default: SCOPE_SUB

The Delay Time Between Retries

How long to wait after receiving an error result that indicates OpenAM should try the LDAP operation again.

ssoadm attribute: com.iplanet.am.ldap.connection.delay.between.retries

Default: 1000 milliseconds

DN Cache Enabled

Whether to enable the DN cache, which is used to cache DN lookups that can happen in bursts during authentication. As the cache can become stale when a user is moved or renamed, enable DN caching when the directory service allows move/rename operations (Mod DN), and when OpenAM uses persistent searches to obtain notification of such updates.

ssoadm attribute: sun-idrepo-ldapv3-dncache-enabled

Default: false

DN Cache Size

Maximum number of DNs cached when caching is enabled.

ssoadm attribute: sun-idrepo-ldapv3-dncache-size

Default: 1500 items

4.3.4. Hints for Configuring OpenDJ Data Stores

Use these hints when configuring OpenDJ data stores.

ssoadm service name: sunIdentityRepositoryService

Name

Name for the data store configuration.

Load schema when finished

Add appropriate LDAP schema to the directory server when saving the configuration. The LDAP Bind DN user must have access to perform this operation.

This attribute is not available for use with the ssoadm command.

Default: false

LDAP Server

host:port to contact the directory server, with optional |server_ID|site_ID for deployments with multiple servers and sites.

OpenAM uses the optional settings to determine which directory server to contact first. OpenAM tries to contact directory servers in the following priority order, with highest priority first:

The first directory server in the list whose server_ID matches the current OpenAM server.
The first directory server in the list whose site_ID matches the current OpenAM server.
The first directory server in the remaining list.

If the directory server is not available, OpenAM proceeds to the next directory server in the list.

ssoadm attribute: sun-idrepo-ldapv3-config-ldap-server

Default: host:port of the initial directory server configured for this OpenAM server

LDAP Bind DN

Bind DN for connecting to the directory server. Some OpenAM capabilities require write access to directory entries.

ssoadm attribute: sun-idrepo-ldapv3-config-authid

LDAP Bind Password

Bind password for connecting to the directory server.

ssoadm attribute: sun-idrepo-ldapv3-config-authpw

LDAP Organization DN

The base DN under which to find user and group profiles.

ssoadm attribute: sun-idrepo-ldapv3-config-organization_name

Default: base-dn

LDAP SSL/TLS Enabled

Whether to use LDAPS or StartTLS to connect to the directory server. If you enable SSL or StartTLS, OpenAM must be able to trust server certificates, either because the server certificates were signed by a CA whose certificate is already included in the trust store used by the container where OpenAM runs, or because you imported the certificates into the trust store.

ssoadm attribute: sun-idrepo-ldapv3-config-connection-mode

Possible values: LDAP, LDAPS, and StartTLS

LDAP Connection Pool Maximum Size

Maximum number of connections to the directory server. Make sure the directory service can cope with the maximum number of client connections across all servers.

ssoadm attribute: sun-idrepo-ldapv3-config-connection_pool_max_size

Default: 10

LDAP Connection Heartbeat Interval

How often to send a heartbeat request to the directory server to ensure that the connection does not remain idle. Some network administrators configure firewalls and load balancers to drop connections that are idle for too long. You can turn this off by setting the value to 0 or to a negative number. To set the units for the interval, use LDAP Connection Heartbeat Time Unit.

ssoadm attribute: openam-idrepo-ldapv3-heartbeat-interval

Default: 10

LDAP Connection Heartbeat Time Unit

Time unit for the LDAP Connection Heartbeat Interval setting.

ssoadm attribute: openam-idrepo-ldapv3-heartbeat-timeunit

Default: second

Maximum Results Returned from Search

A cap for the number of search results to request. For example, when using the Subjects tab to view profiles, even if you set Configuration > Console > Administration > Maximum Results Returned from Search to a larger number, OpenAM does not exceed this setting. Rather than raise this number, consider narrowing your search to match fewer directory entries.

ssoadm attribute: sun-idrepo-ldapv3-config-max-result

Default: 1000

Search Timeout

Maximum time to wait for search results in seconds. Does not apply to persistent searches.

ssoadm attribute: sun-idrepo-ldapv3-config-time-limit

Default: 10

LDAPv3 Plugin Search Scope

LDAP searches can apply to a single entry (SCOPE_BASE), entries directly below the search DN (SCOPE_ONE), or all entries below the search DN (SEARCH_SUB).

ssoadm attribute: sun-idrepo-ldapv3-config-search-scope

Default: SCOPE_SUB

LDAPv3 Repository Plugin Class Name

OpenAM identity repository implementation.

ssoadm attribute: sunIdRepoClass

Default: org.forgerock.openam.idrepo.ldap.DJLDAPv3Repo

Attribute Name Mapping

Map of OpenAM profile attribute names to directory server attribute names.

ssoadm attribute: sunIdRepoAttributeMapping

LDAPv3 Plugin Supported Types and Operations

Map of OpenAM operations that can be performed in the specified OpenAM contexts.

ssoadm attribute: sunIdRepoSupportedOperations

Default: realm=read,create,edit,delete,service, user=read,create,edit,delete, group=read,create,edit,delete

LDAP Users Search Attribute

When searching for a user by name, match values against this attribute.

ssoadm attribute: sun-idrepo-ldapv3-config-users-search-attribute

Default: uid

Warning

Do not modify the value of the search attribute in user profiles. Modifying this attribute value can result in incorrectly cached identity data. For example, if you configure the search attribute to mail, it could prevent users from being able to update their email addresses in their user profiles.

LDAP Users Search Filter

When searching for users, apply this LDAP search filter as well.

ssoadm attribute: sun-idrepo-ldapv3-config-users-search-filter

Default: (objectclass=inetorgperson)

LDAP People Container Naming Attribute

RDN attribute of the LDAP base DN which contains user profiles.

ssoadm attribute: sun-idrepo-ldapv3-config-people-container-name

Default: ou

LDAP People Container Value

RDN attribute value of the LDAP base DN which contains user profiles.

ssoadm attribute: sun-idrepo-ldapv3-config-people-container-value

Default: people

LDAP User Object Class

User profiles have these LDAP object classes.

OpenAM handles only those attributes listed in this setting. OpenAM discards any unlisted attributes from requests and the request proceeds without the attribute.

For example, with default settings, if you request that OpenAM execute a search that asks for the mailAlternateAddress attribute, OpenAM does the search, but does not request mailAlternateAddress. In the same way, OpenAM does perform an update operation with a request to set the value of an unlisted attribute like mailAlternateAddress, but it drops the unlisted attribute from the update request.

ssoadm attribute: sun-idrepo-ldapv3-config-user-objectclass

Default: devicePrintProfilesContainer, forgerock-am-dashboard-service, inetorgperson, inetuser, iplanet-am-auth-configuration-service, iplanet-am-managed-person, iplanet-am-user-service, iPlanetPreferences, organizationalperson, person, sunAMAuthAccountLockout, sunFederationManagerDataStore, sunFMSAML2NameIdentifier, sunIdentityServerLibertyPPService, top

LDAP User Attributes

User profiles have these LDAP attributes.

OpenAM handles only those attributes listed in this setting. OpenAM discards any unlisted attributes from requests and the request proceeds without the attribute.

ssoadm attribute: sun-idrepo-ldapv3-config-user-attributes

Default: sunIdentityServerPPDemographicsBirthDay, uid, sunIdentityServerPPLegalIdentityLegalName, manager, assignedDashboard, sunIdentityServerPPCommonNameSN, userPassword, iplanet-am-session-get-valid-sessions, sunIdentityServerPPEmploymentIdentityJobTitle, iplanet-am-user-password-reset-question-answer, sunIdentityServerPPLegalIdentityDOB, sunIdentityServerPPEmergencyContact, sunIdentityServerPPCommonNameCN, iplanet-am-user-success-url, iplanet-am-user-admin-start-dn, iplanet-am-user-federation-info, userCertificate, sunIdentityServerPPFacadeGreetSound, sunAMAuthInvalidAttemptsData, sunIdentityServerPPFacadeNamePronounced, distinguishedName, sunIdentityServerPPDemographicsTimeZone, sunIdentityMSISDNNumber, iplanet-am-session-max-caching-time, sn, iplanet-am-session-quota-limit, iplanet-am-session-max-session-time, adminRole, sunIdentityServerPPEmploymentIdentityAltO, objectClass, sun-fm-saml2-nameid-info, sunIdentityServerPPLegalIdentityMaritalStatus, iplanet-am-user-login-status, sunIdentityServerPPLegalIdentityAltIdType, devicePrintProfiles, iplanet-am-session-max-idle-time, sunIdentityServerPPFacadegreetmesound, cn, iplanet-am-user-password-reset-options, telephoneNumber, preferredlanguage, iplanet-am-user-federation-info-key, sunIdentityServerPPMsgContact, sunIdentityServerPPLegalIdentityGender, iplanet-am-user-alias-list, sunIdentityServerPPCommonNameFN, caCertificate, inetUserStatus, sunIdentityServerPPCommonNameMN, sunIdentityServerPPEncryPTKey, givenName, memberOf, sunIdentityServerPPLegalIdentityVATIdValue, preferredLocale, iplanet-am-session-service-status, sun-fm-saml2-nameid-infokey, sunIdentityServerPPDemographicsAge, sunIdentityServerDiscoEntries, sunIdentityServerPPLegalIdentityVATIdType, iplanet-am-user-auth-config, iplanet-am-user-failure-url, sunIdentityServerPPAddressCard, sunIdentityServerPPCommonNamePT, dn, iplanet-am-session-add-session-listener-on-all-sessions, mail, authorityRevocationList, iplanet-am-user-password-reset-force-reset, inetUserHttpURL, sunIdentityServerPPLegalIdentityAltIdValue, sunIdentityServerPPCommonNameAltCN, preferredtimezone, sunIdentityServerPPInformalName, sunIdentityServerPPSignKey, sunIdentityServerPPEmploymentIdentityOrg, iplanet-am-session-destroy-sessions, sunIdentityServerPPFacadeMugShot, sunIdentityServerPPFacadeWebSite, sunIdentityServerPPDemographicsDisplayLanguage, postalAddress, iplanet-am-auth-configuration, employeeNumber, iplanet-am-user-account-life, iplanet-am-user-auth-modules, sunIdentityServerPPDemographicsLanguage

Create User Attribute Mapping

When creating a user profile, apply this map of OpenAM profile attribute names to directory server attribute names.

Attributes not mapped to another attribute (for example, cn) and attributes mapped to themselves (for example, cn=cn) take the value of the username unless the attribute values are provided when creating the profile. The object classes for user profile LDAP entries generally require Common Name (cn) and Surname (sn) attributes, so this prevents an LDAP constraint violation when performing the add operation.

ssoadm attribute: sun-idrepo-ldapv3-config-createuser-attr-mapping

Default: cn, sn

Attribute Name of User Status

Attribute to check/set user status.

ssoadm attribute: sun-idrepo-ldapv3-config-isactive

Default: inetuserstatus

User Status Active Value

Active users have the user status attribute set to this value.

ssoadm attribute: sun-idrepo-ldapv3-config-active

Default: Active

User Status Inactive Value

Inactive users have the user status attribute set to this value.

ssoadm attribute: sun-idrepo-ldapv3-config-inactive

Default: Inactive

Authentication Naming Attribute

RDN attribute for building the bind DN when given a username and password to authenticate a user against the directory server.

ssoadm attribute: sun-idrepo-ldapv3-config-auth-naming-attr

Default: uid

LDAP Groups Search Attribute

When searching for a group by name, match values against this attribute.

ssoadm attribute: sun-idrepo-ldapv3-config-groups-search-attribute

Default: cn

LDAP Groups Search Filter

When searching for groups, apply this LDAP search filter as well.

ssoadm attribute: sun-idrepo-ldapv3-config-groups-search-filter

Default: (objectclass=groupOfUniqueNames)

LDAP Groups Container Naming Attribute

RDN attribute of the LDAP base DN which contains group profiles.

ssoadm attribute: sun-idrepo-ldapv3-config-group-container-name

Default: ou

LDAP Groups Container Value

RDN attribute value of the LDAP base DN which contains group profiles.

ssoadm attribute: sun-idrepo-ldapv3-config-group-container-value

Default: groups

LDAP Groups Object Class

Group profiles have these LDAP object classes.

ssoadm attribute: sun-idrepo-ldapv3-config-group-objectclass

Default: groupofuniquenames, top

LDAP Groups Attributes

Group profiles have these LDAP attributes.

ssoadm attribute: sun-idrepo-ldapv3-config-group-attributes

Default: cn, dn, objectclass, uniqueMember

Attribute Name for Group Membership

LDAP attribute in the member's LDAP entry whose values are the groups to which a member belongs.

ssoadm attribute: sun-idrepo-ldapv3-config-memberof

Attribute Name of Unique Member

Attribute in the group's LDAP entry whose values are the members of the group.

ssoadm attribute: sun-idrepo-ldapv3-config-uniquemember

Default: uniqueMember

Persistent Search Base DN

Base DN for LDAP-persistent searches used to receive notification of changes in directory server data.

ssoadm attribute: sun-idrepo-ldapv3-config-psearchbase

Default: base-dn

Persistent Search Filter

LDAP filter to apply when performing persistent searches.

ssoadm attribute: sun-idrepo-ldapv3-config-psearch-filter

Default: (objectclass=*)

Persistent Search Scope

LDAP searches can apply to a single entry (SCOPE_BASE), entries directly below the search DN (SCOPE_ONE), or all entries below the search DN (SEARCH_SUB).

ssoadm attribute: sun-idrepo-ldapv3-config-psearch-scope

Default: SCOPE_SUB

The Delay Time Between Retries

How long to wait after receiving an error result that indicates OpenAM should try the LDAP operation again.

The OpenDJ data store uses this setting only for persistent searches.

ssoadm attribute: com.iplanet.am.ldap.connection.delay.between.retries

Default: 1000 milliseconds

DN Cache Enabled

Whether to enable the DN cache, which is used to cache DN lookups that can happen in bursts during authentication. As the cache can become stale when a user is moved or renamed, enable DN caching when the directory service allows move/rename operations (Mod DN), and when OpenAM uses persistent searches to obtain notification of such updates.

ssoadm attribute: sun-idrepo-ldapv3-dncache-enabled

Default: true

DN Cache Size

Maximum number of DNs cached when caching is enabled.

ssoadm attribute: sun-idrepo-ldapv3-dncache-size

Default: 1500 items

4.3.5. Hints for Configuring Sun/Oracle DSEE Data Stores

Use these hints when configuring Data Stores for Oracle DSEE or Sun DSEE using OpenAM schema.

ssoadm service name: sunIdentityRepositoryService

Name

Name for the data store configuration.

Load schema when finished

Add appropriate LDAP schema to the directory server when saving the configuration. The LDAP Bind DN user must have access to perform this operation.

This attribute is not available for use with the ssoadm command.

Default: false

LDAP Server

host:port to contact the directory server, with optional |server_ID|site_ID for deployments with multiple servers and sites.

OpenAM uses the optional settings to determine which directory server to contact first. OpenAM tries to contact directory servers in the following priority order, with highest priority first:

The first directory server in the list whose server_ID matches the current OpenAM server.
The first directory server in the list whose site_ID matches the current OpenAM server.
The first directory server in the remaining list.

If the directory server is not available, OpenAM proceeds to the next directory server in the list.

ssoadm attribute: sun-idrepo-ldapv3-config-ldap-server

Default: host:port of the initial directory server configured for this OpenAM server.

LDAP Bind DN

Bind DN for connecting to the directory server. Some OpenAM capabilities require write access to directory entries.

ssoadm attribute: sun-idrepo-ldapv3-config-authid

Default: cn=dsameuser,ou=DSAME Users,base-dn

LDAP Bind Password

Bind password for connecting to the directory server.

ssoadm attribute: sun-idrepo-ldapv3-config-authpw

LDAP Organization DN

The base DN under which to find user and group profiles.

ssoadm attribute: sun-idrepo-ldapv3-config-organization_name

Default: base-dn

LDAP SSL/TLS Enabled

Whether to use LDAPS or StartTLS to connect to the directory server. If you enable SSL or StartTLS, OpenAM must be able to trust server certificates, either because the server certificates were signed by a CA whose certificate is already included in the trust store used by the container where OpenAM runs, or because you imported the certificates into the trust store.

ssoadm attribute: sun-idrepo-ldapv3-config-connection-mode

Possible values: LDAP, LDAPS, and StartTLS

LDAP Connection Pool Maximum Size

Maximum number of connections to the directory server. Make sure the directory service can cope with the maximum number of client connections across all servers.

ssoadm attribute: sun-idrepo-ldapv3-config-connection_pool_max_size

Default: 10

LDAP Connection Heartbeat Interval

How often to send a heartbeat request to the directory server to ensure that the connection does not remain idle. Some network administrators configure firewalls and load balancers to drop connections that are idle for too long. You can turn this off by setting the value to 0 or to a negative number. To set the units for the interval, use LDAP Connection Heartbeat Time Unit.

ssoadm attribute: openam-idrepo-ldapv3-heartbeat-interval

Default: 10

LDAP Connection Heartbeat Time Unit

Time unit for the LDAP Connection Heartbeat Interval setting.

ssoadm attribute: openam-idrepo-ldapv3-heartbeat-timeunit

Default: second

Maximum Results Returned from Search

A cap for the number of search results to request. For example, when using the Subjects tab to view profiles, even if you set Configuration > Console > Administration > Maximum Results Returned from Search to a larger number, OpenAM does not exceed this setting. Rather than raise this number, consider narrowing your search to match fewer directory entries.

ssoadm attribute: sun-idrepo-ldapv3-config-max-result

Default: 1000

Search Timeout

Maximum time to wait for search results in seconds. Does not apply to persistent searches.

ssoadm attribute: sun-idrepo-ldapv3-config-time-limit

Default: 10

LDAPv3 Plugin Search Scope

LDAP searches can apply to a single entry (SCOPE_BASE), entries directly below the search DN (SCOPE_ONE), or all entries below the search DN (SEARCH_SUB).

ssoadm attribute: sun-idrepo-ldapv3-config-search-scope

Default: SCOPE_SUB

LDAPv3 Repository Plugin Class Name

OpenAM identity repository implementation.

ssoadm attribute: sunIdRepoClass

Default: org.forgerock.openam.idrepo.ldap.DJLDAPv3Repo

Attribute Name Mapping

Map of OpenAM profile attribute names to directory server attribute names.

ssoadm attribute: sunIdRepoAttributeMapping

LDAPv3 Plugin Supported Types and Operations

Map of OpenAM operations that can be performed in the specified OpenAM contexts.

ssoadm attribute: sunIdRepoSupportedOperations

Default: filteredrole=read,create,edit,delete, group=read,create,edit,delete, realm=read,create,edit,delete,service, role=read,create,edit,delete, user=read,create,edit,delete,service

LDAP Users Search Attribute

When searching for a user by name, match values against this attribute.

ssoadm attribute: sun-idrepo-ldapv3-config-users-search-attribute

Default: uid

Warning

Do not modify the value of the search attribute in user profiles. Modifying this attribute value can result in incorrectly cached identity data. For example, if you configure the search attribute to mail, it could prevent users from being able to update their email addresses in their user profiles.

LDAP Users Search Filter

When searching for users, apply this LDAP search filter as well.

ssoadm attribute: sun-idrepo-ldapv3-config-users-search-filter

Default: (objectclass=inetorgperson)

LDAP People Container Naming Attribute

RDN attribute of the LDAP base DN which contains user profiles.

ssoadm attribute: sun-idrepo-ldapv3-config-people-container-name

Default: ou

LDAP People Container Value

RDN attribute value of the LDAP base DN which contains user profiles.

ssoadm attribute: sun-idrepo-ldapv3-config-people-container-value

Default: people

LDAP User Object Class

User profiles have these LDAP object classes.

OpenAM handles only those attributes listed in this setting. OpenAM discards any unlisted attributes from requests and the request proceeds without the attribute.

For example, with default settings, if you request that OpenAM execute a search that asks for the mailAlternateAddress attribute, OpenAM does the search, but does not request mailAlternateAddress. In the same way, OpenAM does perform an update operation with a request to set the value of an unlisted attribute like mailAlternateAddress, but it drops the unlisted attribute from the update request.

ssoadm attribute: sun-idrepo-ldapv3-config-user-objectclass

Default: devicePrintProfilesContainer, forgerock-am-dashboard-service, inetadmin, inetorgperson, inetuser, iplanet-am-auth-configuration-service, iplanet-am-managed-person, iplanet-am-user-service, iPlanetPreferences, organizationalperson, person, sunAMAuthAccountLockout, sunFederationManagerDataStore, sunFMSAML2NameIdentifier, sunIdentityServerLibertyPPService, top

LDAP User Attributes

User profiles have these LDAP attributes.

OpenAM handles only those attributes listed in this setting. OpenAM discards any unlisted attributes from requests and the request proceeds without the attribute.

ssoadm attribute: sun-idrepo-ldapv3-config-user-attributes

Default: sunIdentityServerPPDemographicsBirthDay, uid, sunIdentityServerPPLegalIdentityLegalName, manager, assignedDashboard, sunIdentityServerPPCommonNameSN, userPassword, iplanet-am-session-get-valid-sessions, sunIdentityServerPPEmploymentIdentityJobTitle, iplanet-am-user-password-reset-question-answer, sunIdentityServerPPLegalIdentityDOB, sunIdentityServerPPEmergencyContact, sunIdentityServerPPCommonNameCN, iplanet-am-user-success-url, iplanet-am-user-admin-start-dn, iplanet-am-user-federation-info, userCertificate, sunIdentityServerPPFacadeGreetSound, sunAMAuthInvalidAttemptsData, sunIdentityServerPPFacadeNamePronounced, distinguishedName, sunIdentityServerPPDemographicsTimeZone, sunIdentityMSISDNNumber, iplanet-am-session-max-caching-time, sn, iplanet-am-session-quota-limit, iplanet-am-session-max-session-time, adminRole, sunIdentityServerPPEmploymentIdentityAltO, objectClass, sun-fm-saml2-nameid-info, sunIdentityServerPPLegalIdentityMaritalStatus, iplanet-am-user-login-status, sunIdentityServerPPLegalIdentityAltIdType, devicePrintProfiles, iplanet-am-session-max-idle-time, sunIdentityServerPPFacadegreetmesound, cn, iplanet-am-user-password-reset-options, telephoneNumber, preferredlanguage, iplanet-am-user-federation-info-key, sunIdentityServerPPMsgContact, sunIdentityServerPPLegalIdentityGender, iplanet-am-user-alias-list, sunIdentityServerPPCommonNameFN, caCertificate, inetUserStatus, sunIdentityServerPPCommonNameMN, sunIdentityServerPPEncryPTKey, givenName, memberOf, iplanet-am-static-group-dn, sunIdentityServerPPLegalIdentityVATIdValue, preferredLocale, iplanet-am-session-service-status, sun-fm-saml2-nameid-infokey, sunIdentityServerPPDemographicsAge, sunIdentityServerDiscoEntries, sunIdentityServerPPLegalIdentityVATIdType, iplanet-am-user-auth-config, iplanet-am-user-failure-url, sunIdentityServerPPAddressCard, sunIdentityServerPPCommonNamePT, dn, iplanet-am-session-add-session-listener-on-all-sessions, mail, authorityRevocationList, iplanet-am-user-password-reset-force-reset, inetUserHttpURL, sunIdentityServerPPLegalIdentityAltIdValue, sunIdentityServerPPCommonNameAltCN, preferredtimezone, sunIdentityServerPPInformalName, sunIdentityServerPPSignKey, sunIdentityServerPPEmploymentIdentityOrg, iplanet-am-session-destroy-sessions, sunIdentityServerPPFacadeMugShot, sunIdentityServerPPFacadeWebSite, sunIdentityServerPPDemographicsDisplayLanguage, postalAddress, iplanet-am-auth-configuration, employeeNumber, iplanet-am-user-auth-modules, iplanet-am-user-account-life, sunIdentityServerPPDemographicsLanguage

Create User Attribute Mapping

When creating a user profile, apply this map of OpenAM profile attribute names to directory server attribute names.

Attributes not mapped to another attribute (for example, cn) and attributes mapped to themselves (for example, cn=cn) take the value of the username unless the attribute values are provided when creating the profile. The object classes for user profile LDAP entries generally require Common Name (cn) and Surname (sn) attributes, so this prevents an LDAP constraint violation when performing the add operation.

ssoadm attribute: sun-idrepo-ldapv3-config-createuser-attr-mapping

Default: cn, sn

Attribute Name of User Status

Attribute to check/set user status.

ssoadm attribute: sun-idrepo-ldapv3-config-isactive

Default: inetuserstatus

User Status Active Value

Active users have the user status attribute set to this value.

ssoadm attribute: sun-idrepo-ldapv3-config-active

Default: Active

User Status Inactive Value

Inactive users have the user status attribute set to this value.

ssoadm attribute: sun-idrepo-ldapv3-config-inactive

Default: Inactive

Authentication Naming Attribute

RDN attribute for building the bind DN when given a username and password to authenticate a user against the directory server.

ssoadm attribute: sun-idrepo-ldapv3-config-auth-naming-attr

Default: uid

LDAP Groups Search Attribute

When searching for a group by name, match values against this attribute.

ssoadm attribute: sun-idrepo-ldapv3-config-groups-search-attribute

Default: cn

LDAP Groups Search Filter

When searching for groups, apply this LDAP search filter as well.

ssoadm attribute: sun-idrepo-ldapv3-config-groups-search-filter

Default: (objectclass=groupOfUniqueNames)

LDAP Groups Container Naming Attribute

RDN attribute of the LDAP base DN which contains group profiles.

ssoadm attribute: sun-idrepo-ldapv3-config-group-container-name

Default: ou

LDAP Groups Container Value

RDN attribute value of the LDAP base DN which contains group profiles.

ssoadm attribute: sun-idrepo-ldapv3-config-group-container-value

Default: groups

LDAP Groups Object Class

Group profiles have these LDAP object classes.

ssoadm attribute: sun-idrepo-ldapv3-config-group-objectclass

Default: groupofuniquenames, iplanet-am-managed-group, iplanet-am-managed-static-group, groupofurls, top

LDAP Groups Attributes

Group profiles have these LDAP attributes.

ssoadm attribute: sun-idrepo-ldapv3-config-group-attributes

Default: cn, iplanet-am-group-subscribable, dn, objectclass, uniqueMember

Attribute Name for Group Membership

LDAP attribute in the member's LDAP entry whose values are the groups to which a member belongs.

ssoadm attribute: sun-idrepo-ldapv3-config-memberof

Attribute Name of Unique Member

Attribute in the group's LDAP entry whose values are the members of the group.

ssoadm attribute: sun-idrepo-ldapv3-config-uniquemember

Default: uniqueMember

Attribute Name of Group Member URL

Attribute in the dynamic group's LDAP entry whose values are LDAP URLs specifying members of the group.

ssoadm attribute: sun-idrepo-ldapv3-config-memberurl

Default: memberUrl

LDAP Roles Search Attribute

When searching for a role by name, match values against this attribute.

ssoadm attribute: sun-idrepo-ldapv3-config-roles-search-attribute

Default: cn

LDAP Roles Search Filter

When searching for roles, apply this LDAP search filter as well.

ssoadm attribute: sun-idrepo-ldapv3-config-roles-search-filter

Default: (&(objectclass=ldapsubentry)(objectclass=nsmanagedroledefinition))

LDAP Roles Object Class

Role profiles have these LDAP object classes.

ssoadm attribute: sun-idrepo-ldapv3-config-role-objectclass

Default: ldapsubentry, nsmanagedroledefinition, nsroledefinition, nssimpleroledefinition, top

LDAP Filter Roles Search Attribute

When searching for a filtered role by name, match values against this attribute.

ssoadm attribute: sun-idrepo-ldapv3-config-filterroles-search-attribute

Default: cn

LDAP Filter Roles Search Filter

When searching for filtered roles, apply this LDAP search filter as well.

ssoadm attribute: sun-idrepo-ldapv3-config-filterroles-search-filter

Default: (&(objectclass=ldapsubentry)(objectclass=nsfilteredroledefinition))

LDAP Filter Roles Object Class

Filtered role profiles have these LDAP object classes.

ssoadm attribute: sun-idrepo-ldapv3-config-filterrole-objectclass

Default: ldapsubentry, nscomplexroledefinition, nsfilteredroledefinition, nsroledefinition

LDAP Filter Roles Attributes

Filtered role profiles have these LDAP attributes.

ssoadm attribute: sun-idrepo-ldapv3-config-filterrole-attributes

Default: nsRoleFilter

Attribute Name for Filtered Role Membership

LDAP attribute in the member's LDAP entry whose values are the filtered roles to which a member belongs.

ssoadm attribute: sun-idrepo-ldapv3-config-nsrole

Default: nsrole

Attribute Name of Role Membership

LDAP attribute in the member's LDAP entry whose values are the roles to which a member belongs.

ssoadm attribute: sun-idrepo-ldapv3-config-nsroledn

Default: nsRoleDN

Attribute Name of Filtered Role Filter

LDAP attribute whose values are the filters for filtered roles.

ssoadm attribute: sun-idrepo-ldapv3-config-nsrolefilter

Default: nsRoleFilter

Persistent Search Base DN

Base DN for LDAP-persistent searches used to receive notification of changes in directory server data.

ssoadm attribute: sun-idrepo-ldapv3-config-psearchbase

Default: base-dn

Persistent Search Filter

LDAP filter to apply when performing persistent searches.

ssoadm attribute: sun-idrepo-ldapv3-config-psearch-filter

Default: (objectclass=*)

Persistent Search Scope

LDAP searches can apply to a single entry (SCOPE_BASE), entries directly below the search DN (SCOPE_ONE), or all entries below the search DN (SEARCH_SUB).

ssoadm attribute: sun-idrepo-ldapv3-config-psearch-scope

Default: SCOPE_SUB

The Delay Time Between Retries

How long to wait after receiving an error result that indicates OpenAM should try the LDAP operation again.

ssoadm attribute: com.iplanet.am.ldap.connection.delay.between.retries

Default: 1000 milliseconds

DN Cache Enabled

Whether to enable the DN cache, which is used to cache DN lookups that can happen in bursts during authentication. As the cache can become stale when a user is moved or renamed, enable DN caching when the directory service allows move/rename operations (Mod DN), and when OpenAM uses persistent searches to obtain notification of such updates.

ssoadm attribute: sun-idrepo-ldapv3-dncache-enabled

Default: true

DN Cache Size

Maximum number of DNs cached when caching is enabled.

ssoadm attribute: sun-idrepo-ldapv3-dncache-size

Default: 1500 items

4.3.6. Hints for Configuring Tivoli Directory Server Data Stores

Use these hints when configuring Tivoli Directory Server data stores.

ssoadm service name: sunIdentityRepositoryService

Name

Name for the data store configuration.

Load schema when finished

Add appropriate LDAP schema to the directory server when saving the configuration. The LDAP Bind DN user must have access to perform this operation.

This attribute is not available for use with the ssoadm command.

Default: false

LDAP Server

host:port to contact the directory server, with optional |server_ID|site_ID for deployments with multiple servers and sites.

OpenAM uses the optional settings to determine which directory server to contact first. OpenAM tries to contact directory servers in the following priority order, with highest priority first.

The first directory server in the list whose server_ID matches the current OpenAM server.
The first directory server in the list whose site_ID matches the current OpenAM server.
The first directory server in the remaining list.

If the directory server is not available, OpenAM proceeds to the next directory server in the list.

ssoadm attribute: sun-idrepo-ldapv3-config-ldap-server

Default: host:port of the initial directory server configured for this OpenAM server

LDAP Bind DN

Bind DN for connecting to the directory server. Some OpenAM capabilities require write access to directory entries.

ssoadm attribute: sun-idrepo-ldapv3-config-authid

LDAP Bind Password

Bind password for connecting to the directory server.

ssoadm attribute: sun-idrepo-ldapv3-config-authpw

LDAP Organization DN

The base DN under which to find user and group profiles.

ssoadm attribute: sun-idrepo-ldapv3-config-organization_name

Default: base-dn

LDAP SSL/TLS Enabled

Whether to use LDAPS or StartTLS to connect to the directory server. If you enable SSL or StartTLS, OpenAM must be able to trust server certificates, either because the server certificates were signed by a CA whose certificate is already included in the trust store used by the container where OpenAM runs, or because you imported the certificates into the trust store.

ssoadm attribute: sun-idrepo-ldapv3-config-connection-mode

Possible values: LDAP, LDAPS, and StartTLS

LDAP Connection Pool Maximum Size

Maximum number of connections to the directory server. Make sure the directory service can cope with the maximum number of client connections across all servers.

ssoadm attribute: sun-idrepo-ldapv3-config-connection_pool_max_size

Default: 10

LDAP Connection Heartbeat Interval

How often to send a heartbeat request to the directory server to ensure that the connection does not remain idle. Some network administrators configure firewalls and load balancers to drop connections that are idle for too long. You can turn this off by setting the value to 0 or to a negative number. To set the units for the interval, use LDAP Connection Heartbeat Time Unit.

ssoadm attribute: openam-idrepo-ldapv3-heartbeat-interval

Default: 10

LDAP Connection Heartbeat Time Unit

Time unit for the LDAP Connection Heartbeat Interval setting.

ssoadm attribute: openam-idrepo-ldapv3-heartbeat-timeunit

Default: second

Maximum Results Returned from Search

A cap for the number of search results to request. For example, when using the Subjects tab to view profiles, even if you set Configuration > Console > Administration > Maximum Results Returned from Search to a larger number, OpenAM does not exceed this setting. Rather than raise this number, consider narrowing your search to match fewer directory entries.

ssoadm attribute: sun-idrepo-ldapv3-config-max-result

Default: 1000

Search Timeout

Maximum time to wait for search results in seconds. Does not apply to persistent searches.

ssoadm attribute: sun-idrepo-ldapv3-config-time-limit

Default: 10

LDAPv3 Plugin Search Scope

LDAP searches can apply to a single entry (SCOPE_BASE), entries directly below the search DN (SCOPE_ONE), or all entries below the search DN (SEARCH_SUB).

ssoadm attribute: sun-idrepo-ldapv3-config-search-scope

Default: SCOPE_SUB

LDAPv3 Repository Plugin Class Name

OpenAM identity repository implementation.

ssoadm attribute: sunIdRepoClass

Default: org.forgerock.openam.idrepo.ldap.DJLDAPv3Repo

Attribute Name Mapping

Map of OpenAM profile attribute names to directory server attribute names.

ssoadm attribute: sunIdRepoAttributeMapping

LDAPv3 Plugin Supported Types and Operations

Map of OpenAM operations that can be performed in the specified OpenAM contexts.

ssoadm attribute: sunIdRepoSupportedOperations

Default: group=read,create,edit,delete, realm=read,create,edit,delete,service, user=read,create,edit,delete,service

LDAP Users Search Attribute

When searching for a user by name, match values against this attribute.

ssoadm attribute: sun-idrepo-ldapv3-config-users-search-attribute

Default: cn

Warning

Do not modify the value of the search attribute in user profiles. Modifying this attribute value can result in incorrectly cached identity data. For example, if you configure the search attribute to mail, it could prevent users from being able to update their email addresses in their user profiles.

LDAP Users Search Filter

When searching for users, apply this LDAP search filter as well.

ssoadm attribute: sun-idrepo-ldapv3-config-users-search-filter

Default: (objectclass=inetorgperson)

LDAP People Container Naming Attribute

RDN attribute of the LDAP base DN which contains user profiles.

ssoadm attribute: sun-idrepo-ldapv3-config-people-container-name

Default: ou

LDAP People Container Value

RDN attribute value of the LDAP base DN which contains user profiles.

ssoadm attribute: sun-idrepo-ldapv3-config-people-container-value

LDAP User Object Class

User profiles have these LDAP object classes.

OpenAM handles only those attributes listed in this setting. OpenAM discards any unlisted attributes from requests and the request proceeds without the attribute.

For example, with default settings if you request that OpenAM execute a search that asks for the mailAlternateAddress attribute, OpenAM does the search, but does not request mailAlternateAddress. In the same way, OpenAM does perform an update operation with a request to set the value of an unlisted attribute like mailAlternateAddress, but it drops the unlisted attribute from the update request.

ssoadm attribute: sun-idrepo-ldapv3-config-user-objectclass

Default: devicePrintProfilesContainer, forgerock-am-dashboard-service, inetorgperson, inetuser, iplanet-am-auth-configuration-service, iplanet-am-managed-person, iplanet-am-user-service, iPlanetPreferences, organizationalperson, person, sunAMAuthAccountLockout, sunFederationManagerDataStore, sunFMSAML2NameIdentifier, sunIdentityServerLibertyPPService, top

LDAP User Attributes

User profiles have these LDAP attributes.

OpenAM handles only those attributes listed in this setting. OpenAM discards any unlisted attributes from requests and the request proceeds without the attribute.

ssoadm attribute: sun-idrepo-ldapv3-config-user-attributes

Default: adminRole, assignedDashboard, authorityRevocationList, caCertificate, cn, devicePrintProfiles, distinguishedName, dn, employeeNumber, givenName, inetUserHttpURL, inetUserStatus, iplanet-am-auth-configuration, iplanet-am-session-add-session-listener-on-all-sessions, iplanet-am-session-destroy-sessions, iplanet-am-session-get-valid-sessions, iplanet-am-session-max-caching-time, iplanet-am-session-max-idle-time, iplanet-am-session-max-session-time, iplanet-am-session-quota-limit, iplanet-am-session-service-status, iplanet-am-user-account-life, iplanet-am-user-admin-start-dn, iplanet-am-user-alias-list, iplanet-am-user-auth-config, iplanet-am-user-auth-modules, iplanet-am-user-failure-url, iplanet-am-user-federation-info-key, iplanet-am-user-federation-info, iplanet-am-user-login-status, iplanet-am-user-password-reset-force-reset, iplanet-am-user-password-reset-options, iplanet-am-user-password-reset-question-answer, iplanet-am-user-success-url, mail, manager, memberOf, objectClass, postalAddress, preferredlanguage, preferredLocale, preferredtimezone, sn, sun-fm-saml2-nameid-info, sun-fm-saml2-nameid-infokey, sunAMAuthInvalidAttemptsData, sunIdentityMSISDNNumber, sunIdentityServerDiscoEntries, sunIdentityServerPPAddressCard, sunIdentityServerPPCommonNameAltCN, sunIdentityServerPPCommonNameCN, sunIdentityServerPPCommonNameFN, sunIdentityServerPPCommonNameMN, sunIdentityServerPPCommonNamePT, sunIdentityServerPPCommonNameSN, sunIdentityServerPPDemographicsAge, sunIdentityServerPPDemographicsBirthDay, sunIdentityServerPPDemographicsDisplayLanguage, sunIdentityServerPPDemographicsLanguage, sunIdentityServerPPDemographicsTimeZone, sunIdentityServerPPEmergencyContact, sunIdentityServerPPEmploymentIdentityAltO, sunIdentityServerPPEmploymentIdentityJobTitle, sunIdentityServerPPEmploymentIdentityOrg, sunIdentityServerPPEncryPTKey, sunIdentityServerPPFacadegreetmesound, sunIdentityServerPPFacadeGreetSound, sunIdentityServerPPFacadeMugShot, sunIdentityServerPPFacadeNamePronounced, sunIdentityServerPPFacadeWebSite, sunIdentityServerPPInformalName, sunIdentityServerPPLegalIdentityAltIdType, sunIdentityServerPPLegalIdentityAltIdValue, sunIdentityServerPPLegalIdentityDOB, sunIdentityServerPPLegalIdentityGender, sunIdentityServerPPLegalIdentityLegalName, sunIdentityServerPPLegalIdentityMaritalStatus, sunIdentityServerPPLegalIdentityVATIdType, sunIdentityServerPPLegalIdentityVATIdValue, sunIdentityServerPPMsgContact, sunIdentityServerPPSignKey, telephoneNumber, uid, userCertificate, userPassword

Create User Attribute Mapping

When creating a user profile, apply this map of OpenAM profile attribute names to directory server attribute names.

Attributes not mapped to another attribute (for example, cn) and attributes mapped to themselves (for example, cn=cn) take the value of the username unless the attribute values are provided when creating the profile. The object classes for user profile LDAP entries generally require Common Name (cn) and Surname (sn) attributes, so this prevents an LDAP constraint violation when performing the add operation.

ssoadm attribute: sun-idrepo-ldapv3-config-createuser-attr-mapping

Default: cn, sn

Attribute Name of User Status

Attribute to check/set user status.

ssoadm attribute: sun-idrepo-ldapv3-config-isactive

Default: inetuserstatus

User Status Active Value

Active users have the user status attribute set to this value.

ssoadm attribute: sun-idrepo-ldapv3-config-active

Default: Active

User Status Inactive Value

Inactive users have the user status attribute set to this value.

ssoadm attribute: sun-idrepo-ldapv3-config-inactive

Default: Inactive

Authentication Naming Attribute

RDN attribute for building the bind DN when given a username and password to authenticate a user against the directory server.

ssoadm attribute: sun-idrepo-ldapv3-config-auth-naming-attr

Default: cn

LDAP Groups Search Attribute

When searching for a group by name, match values against this attribute.

ssoadm attribute: sun-idrepo-ldapv3-config-groups-search-attribute

Default: cn

LDAP Groups Search Filter

When searching for groups, apply this LDAP search filter as well.

ssoadm attribute: sun-idrepo-ldapv3-config-groups-search-filter

Default: (objectclass=groupOfNames)

LDAP Groups Container Naming Attribute

RDN attribute of the LDAP base DN which contains group profiles.

ssoadm attribute: sun-idrepo-ldapv3-config-group-container-name

Default: ou

LDAP Groups Container Value

RDN attribute value of the LDAP base DN which contains group profiles.

ssoadm attribute: sun-idrepo-ldapv3-config-group-container-value

LDAP Groups Object Class

Group profiles have these LDAP object classes.

ssoadm attribute: sun-idrepo-ldapv3-config-group-objectclass

Default: groupofnames, top

LDAP Groups Attributes

Group profiles have these LDAP attributes.

ssoadm attribute: sun-idrepo-ldapv3-config-group-attributes

Default: cn, description, dn, member, objectclass, ou

Attribute Name for Group Membership

LDAP attribute in the member's LDAP entry whose values are the groups to which a member belongs.

ssoadm attribute: sun-idrepo-ldapv3-config-memberof

Attribute Name of Unique Member

Attribute in the group's LDAP entry whose values are the members of the group.

ssoadm attribute: sun-idrepo-ldapv3-config-uniquemember

Default: member

Default Group Member's User DN

DN of member added to all newly created groups.

ssoadm attribute: sun-idrepo-ldapv3-config-dftgroupmember

Persistent Search Base DN

Base DN for LDAP-persistent searches used to receive notification of changes in directory server data.

ssoadm attribute: sun-idrepo-ldapv3-config-psearchbase

Default: base-dn

Persistent Search Filter

LDAP filter to apply when performing persistent searches.

ssoadm attribute: sun-idrepo-ldapv3-config-psearch-filter

Default: (objectclass=*)

Persistent Search Scope

LDAP searches can apply to a single entry (SCOPE_BASE), entries directly below the search DN (SCOPE_ONE), or all entries below the search DN (SEARCH_SUB).

ssoadm attribute: sun-idrepo-ldapv3-config-psearch-scope

Default: SCOPE_SUB

The Delay Time Between Retries

How long to wait after receiving an error result that indicates OpenAM should try the LDAP operation again.

ssoadm attribute: com.iplanet.am.ldap.connection.delay.between.retries

Default: 1000 milliseconds

DN Cache Enabled

Whether to enable the DN cache, which is used to cache DN lookups that can happen in bursts during authentication. As the cache can become stale when a user is moved or renamed, enable DN caching when the directory service allows move/rename operations (Mod DN), and when OpenAM uses persistent searches to obtain notification of such updates.

ssoadm attribute: sun-idrepo-ldapv3-dncache-enabled

Default: true

DN Cache Size

Maximum number of DNs cached when caching is enabled.

ssoadm attribute: sun-idrepo-ldapv3-dncache-size

Default: 1500 items

^[3] The Realm/DNS Alias option refers to an FQDN that can be used to represent the realm. It is not related to the CNAME record used in DNS database zones. In other words, the Realm/DNS Alias option shown in the console does not conform to the definition of DNS Aliases described in RFC 2219.

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

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

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

5.3. Creating Agent Profiles

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

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.

5.4. Delegating Agent Profile Creation

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

You can use the OpenAM administrator account when creating policy agent profiles. If 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.

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

5.6. 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. ^[4]

Tip

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

After changing properties specified as Hot swap: no, you must restart the application server or web server, or the agent's container.

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

5.6.2. 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 Processing Properties

Login Form URI

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

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

Login Error URI

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

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

Use Internal Login

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

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

Login Content File Name

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

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

Logout Processing Properties

Application Logout Handler

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

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

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

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

Application Logout URI

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

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

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

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

Logout Request Parameter

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

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

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

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

Logout Introspect Enabled

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

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

Logout Entry URI

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

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

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

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

Access Denied URI Processing Properties

Resource Access Denied URI

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

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

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

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

Not Enforced URI Processing Properties

Not Enforced URIs

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

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

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

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

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

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

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

Invert Not Enforced URIs

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

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

Not Enforced URIs Cache Enabled

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

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

Not Enforced URIs Cache Size

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

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

Default: 1000

Refresh Session Idle Time

When enabled, the agent 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

Note

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

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

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

Login URL Properties

OpenAM Login URL

OpenAM login page URL, such as http://openam.example.com:8080/openam/UI/Login, to which the agent redirects incoming users without sufficient credentials so 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.

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

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

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

Note

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

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

Warning

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

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

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.

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

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

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

^[4]The configuration file syntax is that of a standard Java properties file. See java.util.Properties.load() for a description of the format. The value of a property specified multiple times is not defined.

Chapter 6. Configuring Audit Logging

OpenAM supports a comprehensive Audit Logging Service that captures key auditing events, critical for system security, troubleshooting, and regulatory compliance.

Audit logs gather operational information about events occurring within an OpenAM deployment to track processes and security data, such as authentication mechanisms, system access, user and administrator activity, error messages, and configuration changes.

This chapter describes the new, common REST-based Audit Logging Service available in OpenAM 13.5.2-15. OpenAM 13.5.2-15 also supports a legacy Logging Service, based on a Java SDK and available in OpenAM versions prior to OpenAM 13.5.2-15. The legacy Logging Service will be deprecated in a future release of OpenAM.

The Audit Logging Service uses a structured message format that adheres to a consistent and documented log structure common across the ForgeRock stack, including OpenAM, OpenIDM, OpenDJ, and OpenIG.

Important

By default, OpenDJ 3.0 does not have audit logging enabled; thus, administrators must manually enable audit logging in the directory server. For more information, see To Enable LDAP CSV Access Logs in the OpenDJ Administration Guide.

6.1. About the Audit Logging Service

OpenAM writes log messages generated from audit events triggered by its instances, policy agents, the ssoadm tool, and connected ForgeRock stack implementations.

OpenAM's Audit Logging Service provides a versatile and rich feature set as follows:

Global and Realm-Based Log Configuration. You can configure audit logging globally, which ensures that all realms inherit your global log settings. You can also configure audit logging by realm, which allows you to set different log settings for each realm.
Audit Event Handlers. The Audit Logging Service supports a variety of audit event handlers that allow you to write logs to different types of data stores. See "Configuring Audit Event Handlers" for a list of event handlers available in OpenAM 13.5.2-15.
Audit Event Buffering. By default, OpenAM writes each log message separately as they are generated. OpenAM supports message buffering, a type of batch processing, that stores log messages in memory and flushes the buffer after a preconfigured time interval or after a certain number of log messages reaches the configured threshold value.
Tamper-Evident Logging. You can digitally sign your audit logs to ensure no unauthorized tampering of your logs has taken place. To configure this feature, you must deploy a preconfigured logger certificate and store it at /path/to/openam/openam/Logger.jks.
Log Rotation and Retention Policies. OpenAM rotates JSON and CSV audit logs when it reaches a specified maximum size. You can also configure a time-based rotation policy, which disables the max-size rotation policy and implements log rotation based on a preconfigured time sequence. You also have the option to disable log rotation and use an external log rotation tool. preconfigured time sequence. OpenAM also provides the option to disable log rotation completely for these file types. OpenAM does not support external log rotation for JSON and CSV audit logs.
For Syslog, JDBC, ElasticSearch, JMS, and Splunk handlers, OpenAM does not control log rotation and retention as they are handled by each respective service.
Blacklisting Sensitive Fields. The Audit Logging Service supports blacklisting, a type of filtering to hide sensitive values or fields, such as HTTP headers, query parameters, cookies, or the entire field value.
Reverse DNS Lookup. The Audit Logging Service supports a reverse DNS lookup feature for network troubleshooting purposes. Reverse DNS lookup is disabled by default as it enacts a performance hit in operation throughput.

6.2. Audit Log Topics

OpenAM integrates log messages based on four different audit topics. A topic is a category of audit log event that has an associated one-to-one mapping to a schema type. Topics can be broadly categorized as access details, system activity, authentication operations, and configuration changes. The following table shows the basic event topics and associated audit log files, whose filenames are fixed:

Audit Log Topics

Event Topic	File Name	Description
Access	`access.csv`	Captures who, what, when, and output for every access request.
Activity	`activity.csv`	Captures state changes to objects that have been created, updated, or deleted by end users (that is, non-administrators). For this release, only session changes are captured in the logs. Future releases may also record changes to user trusted devices, UMA policies, OAuth 2.0 tokens and others.
Authentication	`authentication.csv`	Captures when and how a subject is authenticated and related events.
Configuration	`config.csv`	Captures configuration changes to the product with a timestamp and by whom. Note that the `userId` indicating the subject who made the configuration change is not captured in the `config.csv` but may be tracked using the `transactionId` in the `access.csv`.

6.3. Default Audit Logging Configuration

By default, OpenAM logs to a comma-separated value (CSV) audit event handler and stores CSV log files under /path/to/openam/openam/log.

To modify the global audit logging configuration, navigate to Configure > Global Services > Audit Logging and change the default configuration as needed.

To override the global audit logging configuration for a realm, navigate to Realms > Realm Name > Services, add the Audit Logging service to the realm, and configure the service as needed.

6.4. Configuring Audit Event Handlers

OpenAM supports the following types of audit event handlers:

OpenAM Audit Event Handlers

Audit Event Handler Type	Publishes to	How to Configure
CSV	CSV files	"Configuring CSV Audit Event Handlers"
Syslog	The syslog daemon	"Configuring Syslog Audit Event Handlers"
JDBC	A relational database	"Implementing JDBC Audit Event Handlers"
Elasticsearch	An Elasticsearch store	"Implementing Elasticsearch Audit Event Handlers"
JMS	JMS topics	"Configuring JMS Audit Event Handlers"

This section provides procedures for configuring each type of audit handler.

6.4.1. Configuring CSV Audit Event Handlers

OpenAM's default audit event handler is the comma-separated values (CSV) handler, which is already configured for the global Audit Logging Service. The global configuration is used to control audit logging in realms that do not have the Audit Logging Service added to them.

The following procedure describes how to configure a CSV audit event handler:

To Configure a CSV Audit Event Handler

Log in to the OpenAM console as an administrator, navigate to Configure > Global Services, and then click Audit Logging.
In the Event Handler Instances table, click Global CSV Handler.
Under General Handler Configuration, verify that the Enabled box is checked.
Select the topics for your audit logs. For a description of each topic, see "Audit Log Topics".
In the Log Directory field, override the default location of your logs if necessary. The default location is: %BASE_DIR%/%SERVER_URI%/log/.
Warning
It is very important that a different log directory be configured for each instance of the CSV audit event handler. If two instances are writing to the same file, it can interfere with log rotation and tamper-evident logs.
For File Rotation, configure how files are rotated once they reach a specified file size or time interval. Enter the following parameters:
1. For Rotation Enabled, keep the Enabled box check-marked. If disabled, OpenAM ignores log rotation and appends to the same file.
2. For Maximum File Size, enter the maximum size of an audit file before rotation.
  Default: 100000000 bytes.
3. OPTIONAL. For File Rotation Prefix, enter an arbitrary string that will be prefixed to every audit log to identify it. This parameter is used when time-based or size-based rotation is enabled.
4. For File Rotation Suffix, enter a timestamp suffix based on the Java SimpleDateFormat that will be added to every audit log. This parameter is used when time-based or size-based log rotation is enabled.
  Default: -MM.dd.yy-kk.mm.
5. For Rotation Interval, enter a time interval to trigger audit log file rotation in seconds. A negative or zero value disables this feature.
  Default: -1
  Note
  Any combination of the three rotation policies (maximum file size, periodic duration, and duration since midnight) can be implemented including none at all.
6. For Rotation Times, enter a time duration after midnight to trigger file rotation, in seconds. For example, you can provide a value of 3600 to trigger rotation at 1:00 AM.
  Note
  Negative durations are not supported.
For File Retention, determine how long log files should be retained in your system. Configure the following file retention parameters:
1. For Maximum Number of Historical Files, enter a number for allowed backup audit files.
  Default: -1, which indicates an unlimited number of files and disables the pruning of old history files.
2. For Maximum Disk Space, enter the maximum amount of disk space that the total number of audit files can store. A negative or zero value indicates that this policy is disabled.
  Default: -1, which indicates an unlimited amount of disk space.
3. For Minimum Free Space Required, enter the minimum amount of disk space required to store audit files. A negative or zero value indicates that this policy is disabled.
  Default: -1, which indicates no minimum amount of disk space is required.
For Buffering, configure if log events should be buffered in memory before they are written to the CSV file:
1. For Buffering Enabled, click the Enabled box to start audit event buffering.
  The default buffer size is 5000 bytes.
  When buffering is enabled, all audit events are put into an in-memory buffer (one per handled topic), so that the original thread that generated the event can fulfill the requested operation, rather than wait for I/O to complete. A dedicated thread (one per handled topic) constantly pulls events from the buffer in batches and writes them to the CSV file. If the buffer becomes empty, the dedicated thread goes to sleep until a new item gets added.
2. For Flush Each Event Immediately, click Enabled to write all buffered events before flushing.
  When the dedicated thread accesses the buffer, it copies the contents to an array to reduce contention, and then iterates through the array to write to the CSV file. The bytes written to the file can be buffered again in Java classes and the underlying operating system.
  When Flush Each Event Immediately is enabled, OpenAM flushes the bytes after each event is written. If the feature is disabled (default), the Java classes and underlying operation system determine when to flush the bytes.
For Tamper Evident Configuration, set up the feature to detect any tampering of the audit logs.
When tamper evident logging is enabled, OpenAM generates an HMAC digest for each audit log event and inserts it into each audit log entry. The digest detects any addition or modification to an entry.
OpenAM also supports another level of tamper evident security by periodically adding a signature entry to a new line in each CSV file. The entry signs the preceding block of events, so that verification can establish if any of these blocks have been added, removed, or edited by some user.
1. Click Is Enabled to turn on the tamper evident feature for CSV logs.
2. In the Certificate Store Location field, enter the location of the keystore. You must manually create the keystore and place it in this location. You can use a simple script to create your Java keystore: create-keystore.sh.
  Default: %BASE_DIR%/%SERVER_URI%/Logger.jks
3. In the Certificate Store Password field, enter the certificate password.
4. In the Certificate Store Password (confirm), re-enter the certificate password.
5. In the Signature Interval field, enter a value in seconds for OpenAM to generate and add a new signature to the audit log entry.
  Default: 900 (seconds)
In the Audit Event Handler Factory field, keep the default class name for the audit event handler.
Click Add to save your changes.
On the Audit Logging page, click Save.

6.4.2. Configuring Syslog Audit Event Handlers

OpenAM can publish audit events to a syslog server, which is based on a widely-used logging protocol. You can configure your syslog settings on the OpenAM console.

The following procedure describes how to configure a Syslog audit event handler:

To Configure a Syslog Audit Event Handler

Log in to the OpenAM console as an administrator, navigate to Configure > Global Services, and then click Audit Logging.
In the Event Handler Instances section, click New.
On the Select Audit Event Handler page, click Syslog, and then click Next.
On the Add Audit Event Handler page, enter a name for your event handler. For example, Syslog Audit Event Handler.
Under General Handler Configuration, verify that the Enabled box is checked.
Select the topics for your audit logs. For a description of each topic, see "Audit Log Topics".
In the Server hostname field, enter the hostname or IP address of the receiving syslog server.
In the Server port field, enter the port of the receiving syslog server.
Select the Transport protocol for your configuration: TCP or UDP.
In the Connection timeout field, enter the number of seconds to connect to the syslog server. If the server has not responded in the specified time, a connection timeout occurs.

Select the syslog facility.

A syslog message includes a PRI field that is calculated from the facility and severity values. All topics set the severity to INFORMATIONAL but allow you to choose the facility:

Syslog Facilities

Facility	Description
AUTH	Security or authorization messages
AUTHPRIV	Security or authorization messages
CLOCKD	Clock daemon
CRON	Scheduling daemon
DAEMON	System daemons
FTP	FTP daemon
KERN	Kernel messages
LOCAL0	Local use 0 (local0)
LOCAL1	Local use 1 (local1)
LOCAL2	Local use 2 (local2)
LOCAL3	Local use 3 (local3)
LOCAL4	Local use 4 (local4)
LOCAL5	Local use 5 (local5)
LOCAL6	Local use 6 (local6)
LOCAL7	Local use 7 (local7)
LOGALERT	Log alert
LOGAUDT	Log audit
LPR	Line printer subsystem
MAIL	Mail system
NEWS	Network news subsystem
NTP	Network time protocol
SYSLOG	Internal messages generated by syslogd
USER	User-level messages
UUCP	Unix-to-unix-copy (UUCP) subsystem

In the Audit Event Handler Factory field, keep the default class name for the audit event handler.
For Buffering Enabled, click the Enabled box to start audit event buffering.
When buffering is enabled, all audit events that get generated are formatted as syslog messsages and put into a queue. A dedicated thread constantly pulls events from the queue in batches and transmits them to the syslog server. If the queue becomes empty, the dedicated thread goes to sleep until a new item gets added. The default queue size is 5000.
Click Add to save your settings.
On the Audit Logging page, click Save.

6.4.3. Implementing JDBC Audit Event Handlers

OpenAM supports audit logging to relational databases using the JDBC audit event handler. You can configure OpenAM to write to Oracle, MySQL, or other databases.

Before configuring the JDBC audit event handler, you must perform several steps to allow OpenAM to log to the database:

To Prepare for JDBC Audit Logging

Create tables in the relational database in which you will write the audit logs. The SQL for Oracle and MySQL table creation is in the audit.sql file under /path/to/tomcat/webapps/openam/WEB-INF/template/sql/db-type.
If you are using a different relational database, tailor the Oracle or MySQL audit.sql file to conform to your database's SQL syntax.
JDBC audit logging requires a database user with read and write privileges for the audit tables. Do one of the following:
- Identify an existing database user and grant that user privileges for the audit tables.
- Create a new database user with read and write privileges for the audit tables.
Obtain the JDBC driver from your database vendor. Place the JDBC driver .zip or .jar file in the container's WEB-INF/lib classpath. For example, place the JDBC driver in /path/to/tomcat/webapps/openam/WEB-INF/lib if you use Apache Tomcat.

The following procedure describes how to configure a JDBC audit event handler. Perform the following steps after you have created audit log tables in your database and installed the JDBC driver in the OpenAM web container:

To Configure a JDBC Audit Event Handler

Log in to the OpenAM console as an administrator, navigate to Configure > Global Services, and then click Audit Logging.
In the Event Handler Instances section, click New.
On the Select Audit Event Handler page, click JDBC, and then click Next.
On the Add Audit Event Handler page, enter a name for your event handler. For example, JDBC Audit Event Handler.
Under General Handler Configuration, verify that the Enabled box is checked.
Select the topics for your audit logs. For a description of each topic, see "Audit Log Topics".
For Database Type, click one of the following:
- Oracle
- MySQL
- Other
For JDBC Database URL, enter the URL for your database server. For example, jdbc:oracle:thin@//host.example.com:1521/ORCL.
In the Database Driver Name field, enter the classname of the driver to connect to the datbase. For example, oracle.jdbc.driver.OracleDriver or com.mysql.jdbc.Driver.
In the Database Username field, enter the username to authenticate to the database server.
This user must have read and write privileges for the audit tables.
In the Database User Password field, enter the password used to authenticate to the database server. Then, re-enter the password in the Database User Password (confirm) field.
In the Connection Timeout (seconds) field, enter the maximum wait time before failing the connection.
Default: 30 (seconds)
In the Maximum Connection Idle Timeout (seconds) field, enter the maximum idle time in seconds before the connection is closed.
Default: 600 (seconds)
In the Maximum Connection Time (seconds) field, enter the maximum time in seconds for a connection to stay open.
Default: 1800 (seconds)
In the Minimum Idle Connections field, enter tne minimum number of idle connections allowed in the connection pool.
In the Maximum Connections field, enter the maximum number of connections in the connection pools.
In the Factory Class Name, enter the fully qualified class name of your custom JDBC audit event handler.
Click Add to save your changes.
On the Audit Logging page, click Save.

6.4.4. Implementing Elasticsearch Audit Event Handlers

OpenAM supports audit logging to Elasticsearch 5.0. When you store OpenAM's audit logs in an Elasticsearch data store, you can use Kibana to perform data discovery and visualization on your logs.

You can experiment with an Elasticsearch audit handler without enabling any Elasticsearch security features. However, for a more secure deployment, ForgeRock recommends that you use Elasticsearch Shield to require authentication to Elasticshield. Depending on your network topology, you might also want to configure SSL for Elasticsearch Shield.

Before configuring the Elasticsearch audit event handler, you must configure an Elasticsearch index with OpenAM's audit schema:

To Prepare for Elasticsearch Audit Logging

Perform the following steps to prepare an Elasticsearch instance for storing OpenAM audit events.

Note

These steps apply to Elasticsearch 5.0 only. Breaking changes in Elasticsearch 6.0 make it incompatible with the schemas provided in this version of OpenAM.

For more information, see Breaking Changes in 6.0 in the Elasticsearch Reference Docs.

Review the JSON file containing OpenAM's audit schema. You can find the JSON file for the audit schema at the path /path/to/tomcat/webapps/openam/WEB-INF/template/elasticsearch/audit.json.
Copy the audit.json file to the system where you will create the Elasticsearch index for OpenAM auditing.
In this example, you create an Elasticsearch index by executing an Elasticsearch REST API call using the curl command. Copy the audit.json file to a location that is accessible to the curl command you will run in the next step.
Create an Elasticsearch index for OpenAM auditing as follows:
```
$ curl \
 --request POST \
 --header "Content-Type: application/json" \
 --data @audit.json \
 http://elasticsearch.example.com:9200/my_openam_audit_index
```
In this example, note the following:
- elasticsearch.example.com is the name of the host on which Elasticsearch runs.
- 9200 is the port number that you use to access Elasticsearch's REST API.
- my_openam_audit_index is the name of the Elasticsearch index that you want to create.
Tip
For more information on connecting to Elasticsearch, see Talking to Elasticsearch in the Elasticsearch documentation.

To Configure an Elasticsearch Audit Event Handler

The following procedure describes how to configure an Elasticsearch audit event handler. Perform the following steps after you have created an Elasticsearch index for OpenAM audit logging:

If your Elasticsearch deployment uses Elasticsearch Shield configured for SSL, import the CA certificate used to sign Elasticsearch node certificates into the Java keystore on the host that runs OpenAM. For example:
```
$ keytool \
 -import \
 -trustcacerts \
 -alias elasticsearch \
 -file /path/to/cacert.pem \
 -keystore $JAVA_HOME/jre/lib/security/cacerts
```
If you are running an OpenAM site, import the CA certificate on all the servers in your site.
Log in to the OpenAM console as an administrator, navigate to Configure > Global Services, and then click Audit Logging.
In the Event Handler Instances section, click New.
On the Select Audit Event Handler page, click Elasticsearch, and then click Next.
On the Add Audit Event Handler page, enter a name for your event handler. For example, Elasticsearch Event Handler.
Under General Handler Configuration:
1. Verify that the Enabled box is checked.
2. Select the topics for your audit logs. For a description of each topic, see "Audit Log Topics".
Under Elasticsearch Configuration:
1. In the Server Hostname field, enter the hostname or IP address of the Elasticsearch server to which OpenAM should connect when writing audit logs.
2. In the Server Port field, enter the port number to access Elasticsearch's REST API. The default port number is 9200.
3. If SSL is enabled in your Elasticsearch deployment, click the Enabled check box for SSL Enabled.
4. In the Elasticsearch Index field, specify the name of the index to be used for OpenAM audit logging. The index you specify in this field must be identical to the index you created in "To Prepare for Elasticsearch Audit Logging".
If you have configured Elasticsearch Shield for user authentication, specify the name and password of an Elasticsearch user in the Username and Password fields under Authentication.
If you are not using Elasticsearch Shield for user authentication, you can leave these fields blank.
Under Buffering, configure whether log events should be buffered in memory before they are written to the Elasticsearch data store:
1. For Buffering enabled, click the Enabled box to start audit event buffering.
  When buffering is enabled, all audit events are put into an in-memory buffer (one per handled topic), so that the original thread that generated the event can fulfill the requested operation, rather than wait for I/O to complete. A dedicated thread (one per handled topic) constantly pulls events from the buffer in batches and writes them to Elasticsearch. If the buffer becomes empty, the dedicated thread goes to sleep until a new item gets added.
2. For Batch Size, specify the number of audit events that OpenAM pulls from the audit buffer when writing a batch of events to Elasticsearch. The default is 500 audit events.
3. For Queue Capacity, specify the maximum number of audit events that OpenAM can queue in this audit handler's buffer. The default is 10000 audit events.
  If the number of events to queue exceeds the queue capacity, OpenAM raises an exception and the excess audit events are dropped, and therefore not written to Elasticsearch.
4. For Write interval, specify how often OpenAM should write buffered events to Elasticsearch. The default interval is 250 milliseconds.
In the Factory Class Name field under Audit Event Handler Factory, keep the default class name for the audit event handler.
Click Add to add the Elasticsearch audit logging event handler to the Audit Logging Service.
On the Audit Logging page, click Save to save your changes to the Audit Logging Service.

If you have configured the audit logging event handler correctly, OpenAM starts logging to Elasticsearch immediately after you have saved your changes to the Audit Logging Service.

6.4.5. Configuring JMS Audit Event Handlers

OpenAM supports audit logging to a JMS message broker. JMS is a Java API for sending messages between clients using a publish and subscribe model as follows:

OpenAM audit logging to JMS requires that the JMS message broker supports using JNDI to locate a JMS connection factory. See your JMS message broker documentation to verify that you can make connections to your broker by using JNDI before attempting to implement an OpenAM JMS audit handler.
OpenAM acts as a JMS publisher client, publishing JMS messages containing audit events to a JMS topic. ^[5]
A JMS subscriber client, which is not part of the OpenAM software and must be developed and deployed separately from OpenAM, subscribes to the JMS topic to which OpenAM publishes audit events. The client then receives the audit events over JMS and processes them as desired.

Before configuring the JMS audit event handler, you must perform several steps to allow OpenAM to publish audit events as a JMS client:

To Prepare for JMS Audit Logging

Obtain JNDI connection properties that OpenAM requires to connect to your JMS message broker. The specific connection properties vary depending on the broker. See your JMS message broker documentation for details.

For example, connecting to an Apache ActiveMQ message broker requires the following properties:

Example Apache ActiveMQ JNDI Connection Properties

Property Name	Example Value
`java.naming.factory.initial`	`org.apache.activemq.jndi.ActiveMQInitialContextFactory`
`java.naming.provider.url`	`tcp://localhost:61616`
`topic.audit`	`audit`

Obtain the JNDI lookup name of the JMS connection factory for your JMS message broker.
For example, for Apache ActiveMQ, the JNDI lookup name is ConnectionFactory.
Obtain the JMS client .jar file from your JMS message broker vendor. Add the .jar file to OpenAM's classpath by placing it in the WEB-INF/lib directory.
For example, place the JMS client .jar file in /path/to/tomcat/webapps/openam/WEB-INF/lib if you use Apache Tomcat.

The following procedure describes how to configure a JMS audit event handler.

If your JMS message broker requires an SSL connection, you might need to perform additional, broker-dependent configuration tasks. For example, you might need to import a broker certificate into OpenAM's keystore, or provide additional JNDI context properties.

See your JMS message broker's documentation for specific requirements for making SSL connections to your broker, and implement them as needed in addition to the steps in the following procedure.

Perform the following steps after you have installed the JMS client .jar file in the OpenAM web container:

To Configure a JMS Audit Event Handler

Log in to the OpenAM console as an administrator, navigate to Configure > Global Services, and then click Audit Logging.
In the Event Handler Instances section, click New.
On the Select Audit Event Handler page, click JMS, and then click Next.
On the Add Audit Event Handler page, enter a name for your event handler. For example, JMS Event Handler.
Under General Handler Configuration:
1. Verify that the Enabled box is checked.
2. Select the OpenAM event handler topics^[5] for your audit logs. For a description of OpenAM event handler topics, see "Audit Log Topics".
Under JMS Configuration:
1. In the Delivery Mode field, specify the JMS delivery mode.
  With persistent delivery, the JMS provider ensures that messages are not lost in transit in case of a provider failure by logging messages to storage when they are sent. Therefore, persistent delivery mode guarantees JMS message delivery, while non-persistent mode provides better performance.
  The default delivery mode is non-persistent delivery. Therefore, if your deployment requires delivery of every audit event to JMS subscriber clients, be sure to set the default configuration to PERSISTENT.
2. For Session Mode, use the default setting, AUTO, unless your JMS broker implementation requires otherwise. See your broker documentation for more information.
3. Specify properties that OpenAM will use to connect to your JMS message broker as key-value pairs in the JNDI Context Properties field. The format for properties is [myPropertyName]=myPropertyValue. For example, [java.naming.provider.url]=tcp://localhost:61616.
4. Specify the name of the JMS topic to which OpenAM will publish messages containing audit events.
  Subscriber clients that process OpenAM audit events must subscribe to this topic.
5. Specify the JNDI lookup name of the JMS connection factory in the JMS Connection Factory Name field.
Under Batch Events, configure whether log events should be batched before they are published to the JMS message broker:
1. For Batch enabled, click the Enabled box to start batch publishing of audit events. Audit events will be queued and published to the JMS message broker in batches.
  If batch publishing is not enabled, OpenAM publishes audit events to the JMS message broker individually.
2. For Capacity, specify the maximum capacity of the publishing queue. Execution is blocked if the queue size reaches capacity.
3. For Max Batched, specify the maximum number of events to be delivered when OpenAM publishes the events to the JMS message broker.
4. For Thread Count, specify the number of worker threads OpenAM should use to process the batch queue.
5. Specify the batching timeout configuration as follows:
  - For Insert Timeout, specify the amount of time, in seconds, for queued events to be transmitted to the JMS message broker.
  - For Polling Timeout, specify the amount of time, in seconds, that worker threads wait for new audit events before becoming idle.
  - For Shutdown Timeout, specify the amount of time, in seconds, that worker threads wait for new audit events before shutting down.
In the Factory Class Name field under Audit Event Handler Factory, keep the default class name for the audit event handler.
Click Add to add the JMS audit logging event handler to the Audit Logging Service.
On the Audit Logging page, click Save to save your changes to the Audit Logging Service.

If you have configured the audit logging event handler correctly, OpenAM starts logging to JMS immediately after you have saved your changes to the Audit Logging Service.

6.5. Configuring Audit Logging

You can easily enable the Audit Logging service on the OpenAM Admin console, either globally or on a per-realm basis.

To Configure Global Audit Logging

Log in to the OpenAM console as an administrator, navigate to Configure > Global Services, and then click Audit Logging.
Make sure you have configured your audit event handler. See "Configuring Audit Event Handlers".
In the Realm Attributes section, click Enabled to turn on Audit Logging.
For Resolve host name, click Enabled if you want to perform DNS host lookups, which populates the record's host name field in the logs. Note that enabling DNS host lookups may result in an overall performance hit due to the hostname searches.
For Field exclusion policies, enter any fields or values to exclude from your audit events in the New Value field, and then click Add.
The purpose of this feature is to allow customers to perform two kinds of filtering: 1) Filter fields from the event. For example, customers with more basic auditing requirements may not be interested in capturing HTTP headers, query parameters, and cookies in the access logs; 2) Filter specific values from within fields that store key-value pairs as JSON. For example, the HTTP headers, query parameters and cookies.
On the Audit Logging page, click Save.

To Configure Audit Logging per Realm

You can configure the audit logging server on a per realm basis, which allows you to set up different log locations for your realms and different types of handlers for each realm.

If no specific realm is configured, audit logging will be governed by the global settings.

Log in to the OpenAM console as an administrator, and select the realm from which you want to work.
Click Services > Add a Service, select Audit Logging, and then click Create.
Make sure you have configured your audit event handler. See "Configuring Audit Event Handlers".
On the Configuration tab, select the Audit logging checkbox to turn on audit logging.
For Field exclusion policies, enter any fields or values to exclude from your audit events in the New Value field, and then click Add.
The purpose of this feature is to allow customers to perform two kinds of filtering: 1) Filter fields from the event. For example, customers with more basic auditing requirements may not be interested in capturing HTTP headers, query parameters, and cookies in the access logs; 2) Filter specific values from within fields that store key-value pairs as JSON. For example, the HTTP headers, query parameters and cookies.
Click Save Changes.

6.6. Configuring the Trust Transaction Header System Property

OpenAM supports the propagation of the transaction ID across the ForgeRock platform, such as from OpenDJ or OpenIDM to OpenAM, using the HTTP header X-ForgeRock-TransactionId. The X-ForgeRock-TransactionId header is automatically set in all outgoing HTTP calls from one ForgeRock product to another. Customers can also set this header themselves from their own applications or scripts calling into the ForgeRock platform.

You can set a new property org.forgerock.http.TrustTransactionHeader to true, which will trust any incoming X-ForgeRock-TransactionId headers. By default, the org.forgerock.http.TrustTransactionHeader is set to false, so that a malicious actor cannot flood the system with requests using the same transaction ID header to hide their tracks.

To Configure the Trust Transactions Header System Property

Log in to the OpenAM console.
Navigate to Configure > Server Defaults > Advanced.
In the Add a Name field, enter org.forgerock.http.TrustTransactionHeader, and enter true in the corresponding Add a Value field.
Click Save Changes.
Your OpenAM instance will now accept incoming X-ForgeRock-Transactionid headers, which can then be tracked in the audit logs.

6.7. Configuring the Legacy Audit Logging

To configure OpenAM logging properties, log in to the OpenAM console as OpenAM administrator, and navigate to Configure > Global Services > System, and then click Logging.

For more information on the available settings, see "Logging" in the Reference reference.

6.7.1. Audit Logging to Flat Files

By default, OpenAM audit logs are written to files in the configuration directory for the instance, such as $HOME/openam/log/.

OpenAM sends messages to different log files, each named after the service logging the message, with two different types log files per service: .access and.error. Thus, the current log files for the authentication service are named amAuthentication.access and amAuthentication.error.

For details, see "Log Files and Messages" in the Reference.

6.7.2. Audit Logging to a Syslog Server

OpenAM supports sending audit log messages to a syslog server for collation.

You can enable syslog audit logging by using the OpenAM console, or the ssoadm command.

Enabling Syslog Audit Logging by Using the OpenAM Console

Log in to the OpenAM console as OpenAM administrator.
Navigate to Configure > Global Services > System, and then click Logging.
Set the Logging Type option to Syslog.
Complete the following settings as appropriate for your syslog server:
- Syslog server host
- Syslog server port
- Syslog server protocol
- Syslog facility
- Syslog connection timeout
For information on these settings, see "Logging" in the Reference.
Save your work.

Enabling Syslog Audit Logging by Using SSOADM

Create a text file, for example, MySyslogServerSettings.txt containing the settings used when audit logging to a syslog server, as shown below:

      iplanet-am-logging-syslog-port=514
       iplanet-am-logging-syslog-protocol=UDP
       iplanet-am-logging-type=Syslog
       iplanet-am-logging-syslog-connection-timeout=30
       iplanet-am-logging-syslog-host=localhost
       iplanet-am-logging-syslog-facility=local5

Use the following SSOADM command to configure audit logging to a syslog server:

$ ssoadm \
      set-attr-defs \
      --adminid amadmin \
      --password-file /tmp/pwd.txt \
      --servicename iPlanetAMLoggingService \
      --schematype Global \
      --datafile MySyslogServerSettings.txt

      Schema attribute defaults were set.

6.7.3. Audit Logging in OpenAM Policy Agents

By default, OpenAM Policy Agents log to local files in their configuration directories for debugging. The exact location depends on where you installed the agent.

By default, OpenAM policy agents send log messages remotely to OpenAM when you log auditing information about URL access attempts. To configure audit logging for a centrally managed policy agent, login to the OpenAM console as administrator, and browse to Realms > Realm Name > Agents > Agent Type > Agent Name > Global, and then scroll down to the Audit section.

^[5] Note that OpenAM and JMS use the term topic differently. An OpenAM audit topic is a category of audit log event that has an associated one-to-one mapping to a schema type. A JMS topic is a distribution mechanism for publishing messages delivered to multiple subscribers.

Chapter 7. Working with Mobile Devices and Applications

When building applications that run on mobile devices, you can use the same OpenAM service that you also use for access management in your web, cloud, and other applications. OpenAM has features that make it particularly well-suited to the mobile world, too.

7.1. Simplifying Access on Mobile Devices

On many mobile devices, users want to avoid repeatedly entering credentials, such as an email address or user name and a password. They do not want new credentials to manage for every application they try. They do not want to share their credentials across applications. Instead, users want single sign-on with few identity providers. They want to authorize access for applications rather than share their credentials.

OpenAM supports modern web standards including "Managing OAuth 2.0 Authorization", "Managing OpenID Connect 1.0 Authorization", and GSMA Mobile Connect. After registering an application with OpenAM as an OAuth/OpenID Connect client, the application can then redirect a user to OpenAM to authenticate and to authorize access to resources that the user owns, such as profile data. The application gets an access token that can be used to gain authorized access without requiring the user to share credentials. OpenID Connect extends OAuth, standardizing how client applications discover and register with identity providers, and also defining how applications can manage user sessions and handle logout when they no longer want to authorize access.

OAuth 2.0 with a Mobile Application

An OAuth 2.0 client application can thus simplify the user experience on the phone to authorizing access.

OAuth 2.0 Mobile Application Demonstration

In addition to serving as an identity provider, OpenAM can also function as an OAuth 2.0 client, protecting access to resources within your control based on authorization granted by an identity provider who users already know and use, such as Facebook, Google, MSN, and so forth. OpenAM's built in authorization policy management makes it straightforward to integrate this capability into your applications.

The OAuth and OpenID Connect standards specify REST interfaces, making them essentially programming language-independent and accessible for web applications and mobile applications alike.

Mobile Connect is an application of OpenID Connect that enables authentication to work through a mobile phone, regardless of the service provided or the device consuming the service. Mobile Connect therefore allows Mobile Network Operators to act as an identity provider for their customers. OpenAM fits well in Mobile Connect deployments as it can play both the role of OpenID Provider and also of Authenticator, with many authentication modules built in as described in "Protecting Access for Mobile Users". For details on using OpenAM in a Mobile Connect installation, see "Using OpenAM with Mobile Connect".

OpenAM also supports Open Authentication architecture with the OATH module mentioned in the next section.

7.2. Protecting Access for Mobile Users

You must give users access to your organization's resources while they are on the go. At the same time, you must manage risk. OpenAM supports risk-based adaptive authentication, device fingerprints, one-time passwords, and other multi-factor authentication capabilities that help you do both. As OpenAM handles authentication through plugin modules that you can chain, your OpenAM service can meet a variety of requirements.

The Adaptive Risk authentication module lets you add risk assessment to any authentication chain, dynamically requiring stronger authentication when circumstances require it (new location, ancient last login time, new device, new IP address, specific application, and so forth). For more information about the Adaptive Risk module, see "Hints for the Adaptive Risk Authentication Module".

Using the Adaptive Risk Module in an Authentication Chain

You can add the Device ID (Match) authentication module to an authentication chain to fingerprint users' devices for additional risk assessment, making it easier to handle sign-on when users authenticate from their own devices. For more information about the Device ID (Match) module, see "Hints for the Device ID (Match) Authentication Module".

OpenAM also lets you decide exactly what stronger authentication means in your situation. You can, for example, add multi-factor authentication involving mobile devices using one-time passwords:

Users can generate one-time passwords with ForgeRock's authenticator mobile app. See "Multi-Factor Authentication" for more information.
OpenAM can generate one-time passwords and then send them to mobile phones using a text message or e-mail. See "Hints for the HOTP Authentication Module" for more information.

In addition to capabilities supporting new applications, OpenAM integrates well with existing systems needed by users on the move. Whether users are authenticating from a mobile device through a gateway using an MSISDN, starting single sign-on by logging on to a laptop, or connecting to a VPN with certificate-based authentication, OpenAM has an authentication module for that.

7.3. Simplifying Access With REST APIs

Representational State Transfer (REST) is a architectural style designed in parallel with HTTP. REST simplifies integration and deployment while enabling layered, web-scale services. REST APIs in OpenAM implement REST in a way that reuses common HTTP verbs and decouples APIs from the programming languages that developers use to interact with them. OpenAM exposes REST APIs for many capabilities, such as those in the following list:

Authentication (including a callback mechanism so applications can work with all OpenAM authentication modules)
Logout
Managing groups
Managing policy agent profiles
Managing realms
Managing user profiles
OAuth 2.0 authorization
OpenAM native authorization
OpenID Connect 1.0 authorization
Resetting forgotten passwords
Token validation
User self-registration

OpenAM Capabilities

As "Using the REST API" in the Developer's Guide provide language-independent access, they make it easier to build cross-device applications. Developers can use the same APIs to access OpenAM both from web applications and also from native mobile applications.

Furthermore, OpenAM REST APIs are built on an underlying common REST framework designed to provide common access to resource providers. The common REST framework standardizes how resource providers serve standard requests (create, read, update, delete, query, patch), and also how resource providers offer extended operations in a managed way (using actions). Applications built to interact with OpenAM REST APIs increasingly can interoperate with other products in the ForgeRock stack, such as OpenIDM for identity management and OpenDJ for highly available data.

7.4. Getting Source Code for Sample Mobile Applications

Source code for the sample mobile applications is available in sample repositories in the ForgeRock commons project. Get local clones of one or more of the following repositories so that you can try these sample applications on your system:

For example, if you have a Mac running OS X 10.8 or later with Xcode installed, try the OpenAM OAuth 2.0 iOS Sample App.

OpenAM OAuth 2.0 iOS Sample Application

Chapter 8. Configuring User Self-Service Features

OpenAM provides user self-service features that enable your customers to self-register to your web site, securely reset forgotten passwords, and retrieve their usernames. OpenAM's user self-service capabilities greatly reduces help desk costs and offers a rich online experience that strengthens customer loyalty.

Note

The Password Reset service, located on the OpenAM console at Configure > Global Services, is deprecated for OpenAM 13.5.2-15 and will no longer be supported in a future OpenAM release.

8.1. About User Self-Service

OpenAM's User Self-Service feature supports automated account registration for new users, forgotten password reset, and forgotten username retrieval for your existing customer base. The User Self-Service features include the following capabilities:

User self-registration. Allows non-authenticated users to register to your site on their own. You can add additional security features like email verification, knowledge-based authentication (KBA) security questions, Google reCAPTCHA, and custom plugins to add to your user self-registration process.
Knowledge-based authentication security questions. Supports the capability to present security questions during the registration process. When enabled, the user is prompted to enter answers to pre-configured or custom security questions. Then, during the forgotten password or forgotten username process, the user is presented with the security questions and must answer them correctly to continue the process.
Forgotten password reset. Allows registered users already in your system to reset their passwords. The default password policy is set in the underlying directory server and requires a minimum password length of eight characters by default. If security questions are enabled, users must also correctly answer their pre-configured security questions before resetting their passwords.
Forgotten username support. Allows users to retrieve their forgotten usernames. If security questions are enabled, users must also correctly answer their pre-configured security questions before retrieving their usernames.
Google reCAPTCHA plugin. Supports the ability to add a Google reCAPTCHA plugin to the registration page. This plug-in protects against any software bots that may be used against your site.
Configurable plugins. Supports the ability to add plugins to customize the user services process flow. You can develop your custom code and drop the .jar file into your container.
Customizable confirmation emails. Supports the ability to customize or localize confirmation email in plain text or HTML.
Password policy configuration. Supports password policy configuration, which is enforced by the underlying OpenDJ directory server and manually aligned with frontend UI templates. The default password policy requires a password with a minimum length of eight characters.
Self registration user attribute whitelist. Supports attribute whitelisting, which allows you to specify which attributes can be set by the user during account creation.

8.2. User Self-Service Process Flows

User Self-Service features support various user flows depending on how you configure your security options, which include email verification, security questions, Google reCAPTCHA, and any custom plugins that you create.

The following diagram shows the basic user self-registration flow without the optional features:

User Self-Registration Basic Flow

The following diagrams show the possible flows for user self-registration flow with the optional features:

User Self-Registration Flow With Options

Forgotten username retrieval and forgotten password reset support various user flows depending on how you configure your security options. If you enabled security questions and the user entered responses to each question during self-registration, the security questions are presented to the user in random order.

The following diagram shows the possible flows for forgotten username:

Forgotten Username Flow

The following diagram shows the possible flows for forgotten password reset:

Forgotten Password Flow

8.3. Configuring the User Self-Service Features

You can configure the user self-service features to use email address verification, which sends an email containing a link for user self-registration and forgotten password reset via OpenAM's email service. You can also send the forgotten username to the user by email if configured.

Tip

For information on the RESTful API for the user self-service features, see "RESTful User Self-Service" in the Developer's Guide.

Follow the steps in the sections below:

"Configuring the Signing and Encryption Key Aliases"
"Configuring the Email Service"
"Configuring the Google reCAPTCHA Plugin"
"Configuring Knowledge-Based Security Questions"
"Configuring User Self-Registration"
"Configuring the Forgotten Password Reset Feature"
"Configuring the Forgotten Username Feature"

8.3.1. Configuring the Signing and Encryption Key Aliases

OpenAM's user self service feature requires two key aliases: one secret key alias for signing and one key pair alias for encryption. OpenAM is pre-configured with a JCEKS keystore with three key aliases that you can use for testing purposes. For more information about keystores and key aliases in OpenAM, see "Managing Certificates and Keystores".

Unlike a JKS keystore that supports asymmetric keys, the JCEKS keystore supports both asymmetric keys for encryption and symmetric keys for signing. In an OpenAM site with multiple OpenAM servers deployed behind a load balancer, the JCEKS keystore allows one server to decrypt and validate a JSON Web Token (JWT) from the other server.

The key aliases must exist in the JCEKS keystore before the user self service feature can be configured, since they need to be specified at configuration time.

To Configure Self Service Key Aliases

To provide user self-service features, you must configure suitable key aliases.Perform the following steps to populate the values of the Encryption Key Pair Alias and the Signing Secret Key Alias properties:

Log in to the OpenAM console as an administrator, for example, amadmin.
Navigate to Configure > Global Services > User Self Service.
Populate the values of the Encryption Key Pair Alias and the Signing Secret Key Alias properties with the names of the key pair aliases in your JCEKS keystore. For example, if you are using the demo keys in the default keystore.jceks file, set the properties as follows:
- Encryption Key Pair Alias to selfserviceenctest.
- Signing Secret Key Alias to selfservicesigntest.
User Self-Service Key Pair Aliases
Save your changes.

8.3.2. Configuring the Email Service

The user self-service feature lets you send confirmation emails via OpenAM's SMTP Email Service to users who are registering at your site or resetting forgotten passwords. If you choose to send confirmation emails, you can configure the Email Service globally.

To Configure the Email Service

By default, OpenAM expects the SMTP service to listen on localhost:465. You can change this setting.

Log in to the OpenAM console as the administrator.
On the Realms page, click the realm in which you will install the Email Service, and then click Services.
Click Services, and then click Add a Service.
On the Choose a Service drop-down list, select Email Service, and then enter the following:
1. Enter the Mail Server Hostname. If you are using the Google SMTP server, you must also configure the Google Mail settings to enable access for less secure applications.
2. Enter the Mail Server Authentication Username. The default is amadmin. If you are testing on a Google account, you can enter a known Gmail address.
3. Enter the Mail Server Authentication Password property value.
4. Enter the Email From Address. The default is no-reply@example.com.
5. Click Create.

8.3.3. Configuring the Google reCAPTCHA Plugin

The user self-service feature supports the Google reCAPTCHA plugin, which can be placed on the Register Your Account, Reset Your Password, and Retrieve Your Username pages. The Google reCAPTCHA plugin protects your user self-service implementation from software bots.

Note

Google reCAPTCHA is the only supported plugin for user self-service. Any other Captcha service will require a custom plugin.

To Configure the Google reCAPTCHA Plugin

Register your web site at a Captcha provider, such as Google reCAPTCHA, to get your site and secret key.
When you register your site for Google reCAPTCHA, you only need to obtain the site and secret key, which you enter in the user self-service configuration page in the OpenAM console. You do not have to do anything with client-side integration and server-side integration. The Google reCAPTCHA plugin appears automatically on the Register Your Account, Reset Your Password, and Retrieve Your Username pages after you configure it in the OpenAM console.
Google reCAPTCHA Page
Log in to the OpenAM console as an administrator.
Click Configure > Global Services > User Self Service.
In the Google Recaptcha Site Key field, enter the site key that you obtained from the Google reCAPTCHA site.
In the Google Recaptcha Secret Key field, enter the secret key that you obtained from the Google reCAPTCHA site.
In the Google Recaptcha Verification URL field, keep the default.

8.3.4. Configuring Knowledge-Based Security Questions

Knowledge-based authentication (KBA) is an authentication mechanism in which the user must correctly answer a number of pre-configured security questions that are set during the initial registration setup. If successful, the user is granted the privilege to carry out an action, such as registering an account, resetting a password, or retrieving a username. The security questions are presented in a random order to the user during the user self-registration, forgotten password reset, and forgotten username processes.

OpenAM provides a default set of security questions and easily allows OpenAM administrators and users to add their own custom questions.

To Configure Security Questions

Log in to the OpenAM console as the administrator.
Click Configure > Global Services > User Self Service.
On the User Self Service page, scroll to the Security Questions section. Enter your own security question in the New Value field, and then click Add. The syntax is: OrderNum|ISO-3166-2 Country Code|Security Question. For example, 5|en|What is your dog's name?. Make sure that order numbers are unique.
Warning
You should never remove any security questions as a user may have reference to a given question.
In the Minimum Answers to Define field, enter the number of security questions that will be presented to the user during the registration process.
In the Minimum Answers to Verify field, enter the number of security questions that must be answered during the Forgotten Password and Forgotten Username services.
Click Finish to save your changes.

8.3.5. Configuring User Self-Registration

OpenAM provides a self-registration feature that allows users to create an account to your web site. Although you can configure user self registration without any additional security mechanisms, such as email verification or KBA security questions, we recommend configuring the email verification service with user self registration at a minimum.

To Configure User Self-Registration

Log in to the OpenAM console as the administrator.
Configure the email service presented in "Configuring the Email Service".
Click Configure > Global Services > User Self Service.
On the User Self Service page, click Enabled next to User Registration.
For Captcha, click Enabled to turn on the Google reCAPTCHA plugin. Make sure you configured the plugin as presented in "Configuring the Google reCAPTCHA Plugin".
For Email Verification, clear the Enabled box if you want to turn off the email verification service. We recommend that you keep it selected.
For Security Questions, click Enabled to display security questions to the user during the self registration, after which the user must enter their answers to the questions. During the forgotten password or forgotten username services, the user will be presented with the security questions to be able to reset their passwords or retrieve their usernames if Security Questions is enabled.
In the Token LifeTime field, enter an appropriate number of seconds for the token lifetime. If the token lifetime expires before the user self-registers, then the user will need to restart the registration process over again.
Default: 900 seconds.
To customize the Self Registration outgoing email, run the following steps:
1. In the Outgoing Email Subject field, enter the Subject line of your email in the New Value field, and then click Add.
  The subject line format is lang|subject-text, where lang is the ISO-639 language code, such as en for English, fr for French, and others. For example, the subject line values could be: en|Registration Email and fr|Inscription E-mail.
2. In the Outgoing Email Body field, enter the text of your email in the New Value field, and then click Add.
  The email body text format is lang|email-text, where lang is the ISO-639 language code. Note that email body text must be all on one line and can contain any HTML tags within the body of the text.
  For example, the email body text could be: en|Thank you for registration to our site! Click <a href="%link%">here</a> to register to the site.
In the Valid Creation Attributes field, enter the user attributes the user can set during the user self-registration. The attributes are based on the OpenAM identity repository.
For Destination After Successful Registration, select one of the following:
- User is automatically logged in and sent to the appropriate page within the system.
- User is sent to a success page without being logged in. In this case, OpenAM displays a "You have successfully registered" page. The user can then click the Login link to log in to OpenAM. This is the default selection.
- User is sent to the login page to authenticate.
Under Advanced Configuration, configure the User Registration Confirmation Email URL for your deployment. The default is: http://openam.example.com:8080/openam/XUI/#register/.
Click Finish to apply your changes.

8.3.6. Configuring the Forgotten Password Reset Feature

The forgotten password feature allows existing users to reset their passwords when they cannot remember them.

To Configure the Forgotten Password Feature

Log in to the OpenAM console as the administrator.
Click Configure > Global Services > User Self Service.
On the User Self Service page, click Enabled next to Forgotten Passwords.
For Captcha, click Enabled to turn on the Google reCAPTCHA plugin. Make sure you configured the plugin as presented in "Configuring the Google reCAPTCHA Plugin".
For Email Verification, clear the Enabled box if you want to turn off the email verification service. We recommend that you keep it selected.
For Security Questions, click Enabled to display security questions to the user during the forgotten password reset process. The user must correctly answer the security questions to be able to reset passwords.
In the Forgotten Password Token LifeTime field, enter an appropriate number of seconds for the token lifetime. If the token lifetime expires before the user resets their password, then the user will need to restart the forgotten password process over again.
Default: 900 seconds.
To customize the Forgotten Password outgoing email, run the following steps:
1. In the Outgoing Email Subject field, enter the subject line of your email in the New Value field, and then click Add.
  The subject line format is lang|subject-text, where lang is the ISO-639 language code, such as en for English, fr for French, and others. For example, the subject line value could be: en|Forgotten Password Email.
2. In the Outgoing Email Body field, enter the text of your email in the New Value field, and then click Add.
  The email body text format is lang|email-text, where lang is the ISO-639 language code. Note that email body text must be all on one line and can contain any HTML tags within the body of the text.
  For example, the email body text could be: en|Thank you for request! Click <a href="%link%">here</a> to reset your password.
Under Advanced Configuration, change the default Forgotten Password Confirmation Email URL for your deployment. The default is: http://openam.example.com:8080/openam/XUI/#passwordReset/.

8.3.7. Configuring the Forgotten Username Feature

The forgotten username feature allows existing users to retrieve their usernames when they cannot remember them.

To Configure the Forgotten Username Feature

Log in to the OpenAM console as the administrator.
Click Configure > Global Services > User Self Service.
On the User Self Service page, click Enabled next to Forgotten Username.
For Captcha, click Enabled to turn on the Google reCAPTCHA plugin. Make sure you configured the plugin as presented in "Configuring the Google reCAPTCHA Plugin".
For Security Questions, click Enabled to display security questions to the user during the forgotten username process. The users must correctly answer the security questions to be able to retrieve their usernames.
For Email Username, click Enabled if you want the user to receive the retrieved username by email.
For Show Username, click Enabled if you want the user to see their retrieved username on the browser.
In the Forgotten Username Token LifeTime field, enter an appropriate number of seconds for the token lifetime. If the token lifetime expires before the user retrieves their username, then the user will need to restart the forgotten username process.
Default: 900 seconds.
To customize the Forgotten Username outgoing email, run the following steps:
1. In the Outgoing Email Subject field, enter the subject line of your email in the New Value field, and then click Add.
  The subject Line format is lang|subject-text, where lang is the ISO 639 language code, such as en for English, fr for French, and others. For example, the subject line value could be: en|Forgotten username email.
2. In the Outgoing Email Body field, enter the text of your email in the New Value field, and then click Add.
  The email body text format is lang|email-text, where lang is the ISO 639 language code. Note that email body text must be all on one line and can contain any HTML tags within the body of the text.
  For example, the email body text could be: en|Thank you for your inquiry! Your username is %username%.

8.4. User Management of Passwords and Security Questions

Once the user has self-registered to your system, the user can change their password and security questions at any time on the user profile page. The user profile page provides tabs to carry out these functions.

User Profile Page Password Tab

User Profile Page Security Questions Tab

Chapter 9. Configuring Session State

OpenAM supports two types of sessions: stateful and stateless.

This chapter describes the differences between stateful and stateless sessions, and shows you how to configure OpenAM for either type of session.

9.1. About OpenAM Sessions

When a user successfully authenticates, OpenAM creates a session to manage the user's access to resources. OpenAM uses information stored in the session to determine if a user's login is still valid, or if a user needs to reauthenticate.

OpenAM sessions are "stateful" or "stateless," and are described in detail in the following sections.

9.1.1. Stateful Sessions

Stateful sessions are sessions that reside in the OpenAM server's memory and, if session failover is enabled, are also persisted in the Core Token Service's token store. OpenAM sends clients a reference to the session in OpenAM memory but it does not contain any of the session state information. The session reference is also known as an SSO token. For browser clients, OpenAM sets a cookie in the browser that contains the session reference. For REST clients, OpenAM returns the session reference in response to calls to the authentication endpoint.

Stateful sessions are malleable. The OpenAM server can modify various aspects of users' sessions during the sessions' lifetime.

9.1.2. Stateless Sessions

Stateless sessions are sessions in which state information is encoded in OpenAM and sent to clients, but the information from the sessions is not retained in OpenAM's memory. For browser-based clients, OpenAM sets a cookie in the browser that contains the session state. When the browser transmits the cookie back to OpenAM, OpenAM decodes the session state from the cookie.

Stateless sessions are immutable. This means that when OpenAM sets a cookie for a stateless session in a user's browser, it never updates the cookie until the user has logged out of OpenAM, or until the user's session has expired.

9.1.3. Configuration By Realm

Session statefulness and statelessness are configured at the realm level. OpenAM realms use stateful sessions by default. Sessions for all users authenticating to a given realm are either stateful or stateless, depending on the individual realm's configuration. OpenAM can be deployed with some realms using stateless sessions and so forth using stateful sessions.

There is, however, one exception to the per-realm session state configuration. When the top-level administrator (by default, the amadmin user) authenticates to OpenAM, the session is always stateful, even if the Top Level Realm is configured for stateless sessions.

9.1.4. Session State During OpenAM Authentication

During authentication, OpenAM maintains the authenticating user's session in its memory regardless of whether you have configured the realm to which the user is authenticating for stateful or stateless sessions.

After authentication has completed, OpenAM deletes in-memory sessions for users authenticating to realms configured for stateless sessions. Sessions for users authenticating to realms configured for stateful sessions remain in OpenAM's memory heap.

9.1.5. Session Customization

You can store custom information in both stateful and stateless sessions with post authentication plugins. For more information about post authentication plugins, see "Creating a Post Authentication Plugin" in the Developer's Guide.

9.2. Session Cookies

OpenAM writes a cookie in the authenticated user's browser for both stateful and stateless sessions. By default, the cookie's name is iPlanetDirectoryPro. For stateful sessions, the size of this cookie's value is relatively small—approximately 100 bytes—and contains a reference to the stateful session on the OpenAM server and several other pieces of information. For stateless sessions, the iPlanetDirectoryPro cookie is considerably larger—approximately 2000 bytes or more—and contains all the information that would be held in the OpenAM server's memory if the session were stateful.

Stateless session cookies are comprised of two parts. The first part of the cookie is identical to the cookie for stateful sessions, which ensures the compatibility of the cookies regardless of the session type. The second part is a base 64-encoded JSON Web Token (JWT), and it contains session information, as illustrated in the figure below.

Stateful and Stateless Session Cookies

The preceding diagram illustrates the difference between stateful and stateless session cookie values. Note that the diagram is not to scale. The iPlanetDirectoryPro cookie for a stateless session is more than ten times larger than for a stateful session.

The size of the stateless session cookie increases when you customize OpenAM to store additional attributes in users' sessions. You are responsible for ensuring that the size of the cookie does not exceed the maximum cookie size allowed by your end users' browsers.

9.3. Core Token Service Usage

OpenAM uses the Core Token Service differently for stateful and stateless sessions.

For stateful sessions, OpenAM uses the Core Token Service's token store to save user sessions when session failover is enabled. In the event of the failure of an OpenAM server, one or more backup servers can retrieve the sessions from the Core Token Service's token store to reestablish users login sessions during session failover.

With stateless sessions, OpenAM does not store user sessions in the Core Token Service's token store. Instead, OpenAM stores sessions in the iPlanetDirectoryPro cookie on the user's browser. If an OpenAM server fails, another server handling the user's request simply reads the stateless session from the iPlanetDirectoryPro cookie. Session failover need not be enabled for the other server to be able to read the session.

Session blacklisting is an optional feature that maintains a list of logged out stateless sessions in the Core Token Service's token store. The next section describes session logout, including session blacklisting for stateless sessions.

9.4. Session Termination

OpenAM manages active sessions, allowing single sign-on when authenticated users attempt to access system resources in OpenAM's control.

OpenAM ensures that user sessions are terminated when a configured timeout is reached, or when OpenAM users perform actions that cause session termination. Session termination effectively logs the user out of all systems protected by OpenAM.

With stateful sessions, OpenAM terminates sessions in four situations:

When a user explicitly logs out
When an administrator monitoring sessions explicitly terminates a session
When a session exceeds the maximum time-to-live
When a user is idle for longer than the maximum session idle time

Under these circumstances, OpenAM responds by removing stateful sessions from the memory heap of the OpenAM server on which the session resides, and from the Core Token Service's token store (if session failover is enabled). With the user's stateful session no longer in memory, OpenAM forces the user to reauthenticate on subsequent attempts to access resources protected by OpenAM.

When a user explicitly logs out of OpenAM, OpenAM also attempts to invalidate the iPlanetDirectoryPro cookie in users' browsers by sending a Set-Cookie header with an invalid session ID and a cookie expiration time that is in the past. In the case of administrator session termination and session timeout, OpenAM cannot invalidate the iPlanetDirectoryPro cookie until the next time the user accesses OpenAM.

Session termination differs for stateless sessions. Since stateless sessions are not maintained in OpenAM's memory, administrators cannot monitor or terminate stateless sessions. Because OpenAM does not modify the iPlanetDirectoryPro cookie for stateless sessions after authentication, the session idle time is not maintained in the cookie. Therefore, OpenAM does not automatically terminate stateless sessions that have exceeded the idle timeout.

As with stateful sessions, OpenAM attempts to invalidate the iPlanetDirectoryPro cookie from a user's browser when the user logs out. When the maximum session time is exceeded, OpenAM also attempts to invalidate the iPlanetDirectoryPro cookie in the user's browser the next time the user accesses OpenAM.

It is important to understand that OpenAM cannot guarantee cookie invalidation. For example, the HTTP response containing the Set-Cookie header might be lost. This is not an issue for stateful sessions, because a logged out stateful session no longer exists in OpenAM memory, and a user who attempts to reaccess OpenAM after previously logging out will be forced to reauthenticate.

However, the lack of a guarantee of cookie invalidation is an issue for deployments with stateless sessions. It could be possible for a logged out user to have an iPlanetDirectoryPro cookie. OpenAM could not determine that the user previously logged out. Therefore, OpenAM supports a feature that takes additional action when users log out of stateless sessions. OpenAM can maintain a list of logged out stateless sessions in a session blacklist in the Core Token Service's token store. Whenever users attempt to access OpenAM with stateless sessions, OpenAM checks the session blacklist to validate that the user has not, in fact, logged out.

For more information about session blacklist options, see "Configuring Session Blacklisting".

9.5. Choosing Between Stateful and Stateless Sessions

With stateful sessions, OpenAM ties users' sessions to specific servers. Servers can be added to OpenAM sites, but as servers are added, the overall workload balances gradually, assuming a short session lifetime. If an OpenAM server fails, sessions are retrieved from the Core Token Service's token store, and performance can take some time to recover. Crosstalk, an expensive operation, is incurred whenever a user arrives at an OpenAM server that is not the user's home server. Adding servers to OpenAM sites does not improve performance in a horizontally scalable manner; as more servers are added to a site, coordination among the servers becomes more complex.

Stateless sessions provide the following advantages:

Elasticity and horizontal scalability: With stateless sessions, you can add and remove OpenAM servers to a site and the session load should balance horizontally. Elasticity is important for cloud deployments with very large numbers of users when there are significant differences between peak and normal system loads.

Stateful sessions provide the following advantages:

Faster performance with equivalent hosts

Stateless sessions must send a larger cookie to the OpenAM server, and the JWT in the stateless session cookie must be decrypted. The decryption operation can significantly impact OpenAM server performance, reducing the number of session validations per second per host.

Because using stateless sessions provides horizontal scalability, overall performance on hosts using stateless sessions can be easily improved by adding more hosts to the OpenAM deployment.

Full feature support

Stateful sessions support all OpenAM features. Stateless sessions do not. For information about restrictions on OpenAM usage with stateless sessions, see "Limitations When Using Stateless Sessions".

Session information is not resident in browser cookies

With stateful sessions, all the information about the session resides on the OpenAM server. With stateless sessions, session information is held in browser cookies. This information could be very long-lived.

The following table contrasts the impact of using stateful and stateless sessions in an OpenAM deployment:

Impact of Deploying OpenAM Using Stateful and Stateless Sessions

Deployment Area	Stateful Session Deployment	Stateless Session Deployment
Hardware	Higher RAM consumption	Higher CPU consumption
Logical Hosts	Smaller number of hosts	Variable or large number of hosts
Session Monitoring	Available	Not available
Session Location	In OpenAM server memory heap	In a cookie in the user's browser
Session Failover	Requires session stickiness to be configured in the load balancer	Does not require session stickiness
Core Token Service Usage	Supports session failover	Supports session blacklisting for logged out sessions
Core Token Service Demand	Heavier	Lighter
Session Security	Sessions are not accessible to users because they reside in memory on the OpenAM server.	Sessions should be signed and encrypted.
Policy Agents	Sessions cached in the Policy Agent can receive change notification.	Sessions cached in the Policy Agent cannot receive change notification.

9.6. Installation Planning for Stateless Sessions

Session blacklisting uses the Core Token Service's token store during the logout process. For more information about deploying the Core Token Service, see "Configuring the Core Token Service" in the Installation Guide.

Also, ensure the trust store used by OpenAM has the necessary certificates installed:

A certificate is required for encrypting JWTs containing stateless sessions.
If you are using RS256 signing, then a certificate is required to sign JWTs. (HMAC signing uses a shared secret.)

The same certificates must be stored on all servers participating in an OpenAM site.

9.7. Configuring OpenAM for Stateless Sessions

To configure stateless sessions for a realm, follow these steps:

Enable Stateless Sessions in a Realm

Navigate to Realms > Realm Name > Authentication > Settings > General.
Select the "Use Stateless Sessions" check box.
Click Save.

To verify that OpenAM creates a stateless session when non-administrative users authenticate to the realm, follow these steps:

Verify that Stateless Sessions Are Enabled

Authenticate to the OpenAM console as the top-level administrator (by default, the amadmin user). Note that the amadmin user's session will be stateful, because OpenAM sessions for the top-level administrator are always stateful.
Select the Sessions tab.
Verify that a session is present for the amadmin user.
In your browser, examine the OpenAM cookie, named iPlanetDirectoryPro by default. Copy and paste the cookie's value into a text file and note its size.
Start up a private browser session that will not have access to the iPlanetDirectoryPro cookie for the amadmin user:
- On Chrome, open an incognito window.
- On Internet Explorer or Microsoft Edge, start InPrivate browsing.
- On Firefox, open a new private window.
- On Safari, open a new private window.
Authenticate to OpenAM as a non-administrative user in the realm for which you enabled stateless sessions. Be sure not to authenticate as the amadmin user this time.
In your browser, examine the iPlanetDirectoryPro cookie. Copy and paste the cookie's value into a second text file and note its size. The size of the stateless session cookie's value should be considerably larger than the size of the stateful session cookie's value for the amadmin user. If the cookie is not larger, you have not enabled stateless sessions correctly.
Return to the original browser window in which the OpenAM console appears.
Refresh the window containing the Sessions tab.
Verify that a session still appears for the amadmin user, but that no session appears for the non-administrative user in the realm with stateless sessions enabled.

9.9. Configuring Session Blacklisting

Session blacklisting ensures that users who have logged out of stateless sessions cannot achieve single sign-on without reauthenticating to OpenAM.

Perform the following steps to configure session blacklisting:

To Configure OpenAM for Session Blacklisting

Make sure that you deployed the Core Token Service during OpenAM installation. The session blacklist is stored in the Core Token Service's token store.
Navigate to Configure > Global Services, click Session, and then locate the Stateless Sessions section.
Select the Enable Session Blacklisting option to enable session blacklisting for stateless sessions. When you configure one or more OpenAM realms for stateless sessions, you should enable session blacklisting in order to track session logouts across multiple OpenAM servers.
Configure the Session Blacklist Cache Size property.
OpenAM maintains a cache of logged out stateless sessions. The cache size should be around the number of logouts expected in the maximum session time. Change the default value of 10,000 when the expected number of logouts during the maximum session time is an order of magnitude greater than 10,000. An underconfigured session blacklist cache causes OpenAM to read blacklist entries from the Core Token Service store instead of obtaining them from cache, which results in a small performance degradation.
Configure the Blacklist Poll Interval property.
OpenAM polls the Core Token Service for changes to logged out sessions if session blacklisting is enabled. By default, the polling interval is 60 seconds. The longer the polling interval, the more time a malicious user has to connect to other OpenAM servers in a cluster and make use of a stolen session cookie. Shortening the polling interval improves the security for logged out sessions, but might incur a minimal decrease in overall OpenAM performance due to increased network activity.
Configure the Blacklist Purge Delay property.
When session blacklisting is enabled, OpenAM tracks each logged out session for the maximum session time plus the blacklist purge delay. For example, if a session has a maximum time of 120 minutes and the blacklist purge delay is one minute, then OpenAM tracks the session for 121 minutes. Increase the blacklist purge delay if you expect system clock skews in a cluster of OpenAM servers to be greater than one minute. There is no need to increase the blacklist purge delay for servers running a clock synchronization protocol, such as Network Time Protocol.
Click Save.

For detailed information about Session Service configuration attributes, see the entries for "Session" in the Reference.

9.10. Limitations When Using Stateless Sessions

The following OpenAM features are not supported in realms that use stateless sessions:

Session upgrade
Session quotas
Authorization policies with conditions that reference current session properties
Cross-domain single sign-on
SAML v2.0 single sign-on and single logout
SAML 1.x single sign-on
SNMP session monitoring
Session management by using the OpenAM console
Session notification

Chapter 10. Configuring Single Sign-On Within One Domain

This chapter describes the configuration of Single Sign-On (SSO) services for multiple resources on one domain. To understand how SSO works, you need to understand some key elements of the HTTP cookie, as described in RFC 6525, HTTP State Management Mechanism.

With SSO, a user can access multiple independent services from a single session.

10.1. The Basics of the HTTP Cookie

Within an HTTP cookie, you can store a single custom name=value pair, such as sessionid=value. Other custom names within a cookie are as follows:

Domain: Normally set to the full URL that was used to access the configurator. To work with multiple subdomains, the Domain should be set to a URL like Domain=server.example.net. This is also known as the cookie domain, as defined in "Configuration Reference" in the Reference.
Path: The directory in the URL to which the cookie applies. If the Path =/openam, the cookie applies to the /openam subdirectory of the FQDN, and lower level directories, including openam/UI and openam/UI/Login.
Secure: If the Secure name is included, the cookie can be transferred only over HTTPS. When a request is made over HTTP, the cookie is not made available to the application.
HttpOnly: When the HttpOnly name is included, that cookie will not be accessible through JavaScript. According to RFC 6265, the noted flag "instructs the user agent to omit the cookie when providing access to cookies via 'non-HTTP' APIs (for example, a web browser API that exposes cookies to scripts)."
Expires: The lifetime of a cookie can be limited, with an Expires name configured with a time, based on UTC (GMT).

Note

Be careful. Do not take a shortcut with a top-level domain. Web browser clients today are designed to ignore cookies set to top-level domains including com, net, and co.uk. In addition, a cookie with a value like Domain= app1.example.net will not work for similar subdomains, such as app2.example.net.

10.2. Cookies and the SSO Session Process

OpenAM uses cookies to track user sessions. The diagram shown next illustrates how OpenAM assigns and tracks cookies.

In the diagram:

The domain shown in the description is example.net.
The protected resource application can be found on app.example.net.
The OpenAM server is located on sso.example.net.

SSO With Policy Agent

A client points their browser to a protected resource application. An agent on the application checks the client browser cookies for the presence of a session. If a session cookie exists and is valid, the agent requests validation (see arrow 8).

If no valid session cookie exists, the agent redirects the client to OpenAM for authentication (AuthN). The client is then sent to OpenAM for AuthN. If the client submits valid credentials, the AuthN service creates a session cookie for the configured domain. The contents of the session cookie varies, depending on the configuration of the realm to which the user authenticates:

If the realm is configured for stateful sessions, an SSO token is embedded in the cookie.
If the realm is configured for stateless sessions, the session itself is embedded in the cookie.

OpenAM issues an HTTP redirect to send the client browser back to the protected resource.

The agent then verifies the validity of the session with the OpenAM session service, before granting access.

10.3. Potential Problems

In general, problems with SSO relate to some sort of mismatch of domain names. For example, a cookie that is configured on a third-level domain, such as sso.example.net will not work with an application on a similar domain, such as app.example.net. Even if the Session ID is valid, the application will not receive the SSO Token. The request is then redirected to OpenAM. The client gets what appears as a SSO Token in the diagram, which is actually a valid SSO tracking cookie that redirects immediately, and the cycle continues. Other issues that may lead to similar problems are shown here:

When a cookie domain does not match a domain for the protected application.
Assume the application is configured on a domain named example.org. That application will not receive an SSO Token configured on the example.net domain.
When a third-level domain is used for the SSO Token.
If an SSO Token is configured on sso.example.net, an application on app.example.net does not receive the corresponding cookie. In this case, the solution is to configure the SSO Token on example.net.
When the Secure flag is used with a regular HTTP application.
If you need encrypted communications for an application protected by OpenAM, use the Secure flag and make sure the application is accessible over HTTPS.
When the path listed in the cookie does not match the path for the application.
Perhaps the cookie is configured with a /helloworld path; that will not match an application that might be configured with a /hellomars path. In that case, the application will not receive the cookie.
When an inappropriate name is used for the cookie domain
As noted earlier, client browsers are configured to ignore first-level domains, such as com and net as well as functional equivalents, such as co.uk and co.jp.
When working with different browsers
The name=value pairs described earlier may not apply to all browsers. The requirements for an HTTP cookie sent to an IE browser may differ from the requirements for other standard browsers, such as Firefox and Chrome. Based on anecdotal reports, IE does not recognize domain names that start with a number. In addition, IE reportedly refuses cookies that include the underscore (_) character in the FQDN.
When a stateless session cookie exceeds the maximum size permitted by the browser
As described in "Session Cookies", the default size of the iPlanetDirectoryPro cookie is approximately 2,000 bytes. When you customize OpenAM sessions by adding attributes, the cookie size grows. Browsers allow cookie sizes between 4,000 and 5,200 bytes, depending on the browser. OpenAM single sign-on does not function correctly when the cookie size exceeds the maximum size allowed by the browser.

10.4. Configure SSO on One Domain

Now that you have read about the SSO process, you should be able to set it up on a server configured with OpenAM and a web service protected by an OpenAM agent. The following procedure assumes that you know how to configure OpenAM, the Apache Web server, and associated OpenAM Apache agent.

Configure SSO on One Domain

Install OpenAM as described in the Installation Guide. This procedure uses a Server URL of http://openam.example.net:8080/openam.
Install the appropriate policy agent, as described in the OpenAM Web Policy Agent User's Guide or the OpenAM Java EE Policy Agent User's Guide. This procedure uses an agent URL of http://app.example.net:80, and an agent name of webagent1.
Make sure that both URLs are configured with IP addresses, as described in "Installing OpenAM Core Services" in the Installation Guide.
Return to the OpenAM server on http://openam.example.net:8080/openam. Log in as the administrative user, normally amadmin. To activate and configure the agent, follow the procedure described in the OpenAM Web Policy Agent User's Guide or the OpenAM Java EE Policy Agent User's Guide.
Now you can configure SSO Only mode. In the OpenAM console, click Realms > Realm Name > Agents > webagent1. Scroll down to SSO Only Mode and activate the Enabled box.
Save your changes.
Make sure you have configured the SSO domain, in this case, example.net. Navigate to Configure > Global Services > System, and then click Platform. Make sure example.net (or your chosen domain) is selected as a cookie domain.
Save your changes.
Restart the web server. The agent should be active. You should now be able to log out of the OpenAM server.
Verify the agent URL, in this case, http://app.example.net. The OpenAM web agent should now redirect requests to the OpenAM server.

If you want to configure OpenAM and an application on two different cookie domains, such as example.org and example.net, you will need to set up Cross-Domain SSO (CDSSO). For more information, see the chapter on "Configuring Cross-Domain Single Sign-On".

Chapter 11. Configuring Cross-Domain Single Sign-On

This chapter shows you how to configure cross-domain single sign-on (CDSSO). When you have multiple domains in a single organization, CDSSO lets your OpenAM servers in one domain work with policy agents from other domains.

Cross-domain single sign-on provides a safe mechanism for managing access across multiple, different domains that you control. CDSSO lets OpenAM authenticate users redirected by policy agents in other DNS domains.

CDSSO is an OpenAM-specific capability. For single sign-on across multiple organizations or when integrating with other access management software, use OpenAM's federation capabilities.

CDSSO requires stateful OpenAM sessions. Be sure that OpenAM is configured for stateful sessions—the default configuration—before attempting to use CDSSO.

Single sign-on depends on cookies to store session information. Yet for security reasons, browsers do not let a web site in one domain to get access to a cookie from another domain. With CDSSO, the policy agents work around this by negotiating with OpenAM to allow access.

The Java EE policy agent allows CDSSO by using a mechanism to write the SSO token from OpenAM authentication to a cookie with the domain the host where the agent runs. The following sequence diagram illustrates this mechanism.

Java EE Policy Agent Mechanism for CDSSO

Whereas the Java EE policy agent has an endpoint specifically to handle the cookie domain translation, the web policy agent handles the request directly as shown in the following sequence diagram.

Web Policy Agent Mechanism for CDSSO

This chapter includes the following procedures:

"To Enable CDSSO For a Java EE Policy Agent"
"To Enable CDSSO For a Web Policy Agent"
"To Indicate Progress During CDSSO Login"
"To Protect Against Cookie Hijacking"

The federation mechanism associated with SAML v2.0 can be used as an alternative to CDSSO for both Web and Java EE policy agents. While using SAML v2.0 adds complexity, it supports attribute mapping, which may be useful when the two domains are associated with data stores that use different attribute names. For details, see "Using Policy Agents With Standalone Mode".

To Enable CDSSO For a Java EE Policy Agent

In the OpenAM console, browse to Realms > Realm Name > Agents > J2EE > Agent Name > SSO.
Scroll down and enable Cross Domain SSO.
Check that the CDSSO Redirect URI is set.
Depending on where you deployed your Java EE agent application, the default is something like /agentapp/sunwCDSSORedirectURI.
Set the list of URLs for CDSSO Servlet URL to the Cross Domain Controller Servlet URLs of the servers the agent accesses, such as http://openam.example.com:8080/openam/cdcservlet.
If the agent accesses OpenAM through a load balancer, use the load balancer URLs, such as http://load-balancer.example.com:8080/openam/cdcservlet.
Leave the CDSSO Clock Skew set to 0.
Make sure instead that the clocks on the servers where you run OpenAM and policy agents are synchronized.
Set the list of URLs for CDSSO Trusted ID Provider to the Cross Domain Controller Servlet URLs of the OpenAM servers the agent accesses, such http://openam.example.com:8080/openam/cdcservlet.
This list should include one CDC Servlet URL for every OpenAM server the agent might access. You do not need to include site or load balancer URLs.
(Optional) To protect the SSO token from network snooping, you can select CDSSO Secure Enable to mark the SSO token cookie as secure.
If you select this, then the SSO token cookie can only be sent over a secure connection (HTTPS).
Add the domains involved in CDSSO in the CDSSO Domain List.
If necessary, update the Agent Root URL for CDSSO list on the Global tab page.
If the policy agent is on a server with virtual host names, add the virtual host URLs to the list.
If the policy agent is behind a load balancer, add the load balancer URL to the list.
Save your work.

To Enable CDSSO For a Web Policy Agent

In the OpenAM console, browse to Realms > Realm Name > Agents > Web > Agent Name > SSO.
Enable Cross Domain SSO.
Set the list of URLs for CDSSO Servlet URL to the Cross Domain Controller Servlet URLs of the servers the agent accesses, such as http://openam.example.com:8080/openam/cdcservlet.
If the agent accesses OpenAM through a load balancer, use the load balancer URLs, such as http://load-balancer.example.com:8080/openam/cdcservlet.
Add the domains involved in CDSSO in the Cookies Domain List.
If necessary, update the Agent Root URL for CDSSO list on the Global tab page.
If the policy agent is on a server with virtual host names, add the virtual host URLs to the list.
If the policy agent is behind a load balancer, add the load balancer URL to the list.
Save your work.

To Indicate Progress During CDSSO Login

The default self-submitting form page that OpenAM presents to users contains hidden fields, but is otherwise blank. If you want to show users that the operation is in progress, then customize the necessary JSP.

Edit a copy of the file config/federation/default/cdclogin.jsp to add a clue that SSO is in progress, such as an image.
You can find this file where you deployed OpenAM, such as /path/to/tomcat/webapps/openam/config/federation/default/cdclogin.jsp.
When you add an image or other presentation element, make sure that you retain the form and JavaScript as is.
Unpack OpenAM-13.5.2.war, and replace the file with your modified version.
Also include any images you reference in the page.
Pack up your custom version of OpenAM, and then deploy it in your web container.

To Access the CDSSO Authentication Login

When a client makes an access request to some protected resource in a cross domain single sign-on deployment, the policy agent redirects the client to the Cross Domain Controller Servlet (CDCServlet) URL. The CDCServlet determines that the client needs to be authenticated and proxies the request through to an authentication interface, which typically is at /UI/Login:

http://openam.example.com:8080/openam/UI/Login

If your application requires access to a specific URL, you can use the loginURI parameter to do so.

For example, you can access the previous authentication UI URL as follows:
```
http://openam.example.com:8080/openam/cdcservlet?loginURI=/UI/Login
```
If you have another authentication UI deployed at /openam/customLoginURI, you can access this URL at:
```
http://openam.example.com:8080/openam/cdcservlet?loginURI=/customLoginURI
```
In this case, you must also add the custom login URI to the whitelist that is specified by using the org.forgerock.openam.cdc.validLoginURIs property.
1. In the OpenAM console, navigate to Configure > Server Defaults > Advanced.
2. Set the value of the org.forgerock.openam.cdc.validLoginURIs property to /UI/Login,/customLoginURI.
3. Save your work.
For more information about this property, see "Advanced" in the Reference.

Module	Criteria
DataStore	REQUISITE
Device-ID-Match	SUFFICIENT
HOTP	REQUISITE
Device-ID-Save	REQUIRED

Preface

1. Who Should Use This Guide

2. Formatting Conventions

3. Accessing Documentation Online

4. Using the ForgeRock.org Site

5. Getting Support and Contacting ForgeRock

Chapter 1. Administration Interfaces and Tools

1.1. OpenAM Web-Based Console

1.1.1. OpenAM Console Responsiveness

1.1.2. OpenAM Console Search Feature

1.2. OpenAM Command-Line Tools

1.3. OpenAM ssoadm.jsp

Chapter 2. Defining Authentication Services

2.1. About Authentication in OpenAM

Tip

2.2. About Authentication Levels

2.3. Configuring Social Authentication

2.3.1. Configuring Pre-Populated Social Authentication Providers

Note

2.3.2. Configuring Custom Social Authentication Providers

2.3.3. Configuring the Social Authentication Implementations Service

Note

Tip

2.4. Configuring Core Authentication Attributes

2.4.1. Core Authentication Attributes - Global

2.4.2. Core Authentication Attributes - Core

2.4.3. Core Authentication Attributes - User Profile

Note

2.4.4. Core Authentication Attributes - Account Lockout

2.4.5. Core Authentication Attributes - General

2.4.6. Core Authentication Attributes - Security

Caution

2.4.7. Core Authentication Attributes - Post Authentication Processing

2.5. Configuring Authentication Modules

2.5.1. Hints for the Active Directory Authentication Module

2.5.2. Hints for the Adaptive Risk Authentication Module

Tip

2.5.3. Hints for the Anonymous Authentication Module

Note

2.5.4. Hints for the Certificate Authentication Module

2.5.5. Hints for the Data Store Authentication Module

2.5.6. Hints for the Device ID (Match) Authentication Module

Important

Caution

Note

2.5.6.1. What the User Sees During Authentication

2.5.7. Hints for the Device ID (Save) Module

Note

2.5.8. Hints for the Federation Authentication Module

2.5.9. Hints for the ForgeRock Authenticator (OATH) Authentication Module

Note

2.5.10. Hints for the ForgeRock Authenticator (Push) Authentication Module

2.5.11. Hints for the ForgeRock Authenticator (Push) Registration Authentication Module

2.5.12. Hints for the HOTP Authentication Module

Note

Note

2.5.13. Hints for the HTTP Basic Authentication Module

2.5.14. Hints for the JDBC Authentication Module

Note

2.5.15. Hints for the LDAP Authentication Module

2.5.16. Hints for the MSISDN Authentication Module

2.5.17. Hints for the OATH Authentication Module

Note

2.5.18. Hints for the OAuth 2.0/OpenID Connect Authentication Module

Tip

Note

Tip

Note

2.5.18.1. OAuth 2.0 Mix-Up Mitigation

Note

Note

2.5.19. Hints for the OpenID Connect id_token bearer Module

Note

Note

2.5.20. Hints for the Persistent Cookie Module

Important

2.5.21. Hints for the RADIUS Authentication Module

2.5.22. Hints for the SAE Authentication Module

2.5.23. Hints for the SAML2 Authentication Module

2.5.24. Hints for the Scripted Authentication Module