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. 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. 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: 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. 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. Configuring Social Authentication OpenAM allows delegation of authentication to any third party OpenID Connect 1.0 server that implements the OpenID Connect Discovery 1.0 specification. The OpenAM console provides wizards for configuring authentication with selected third parties: Facebook, Google, or Microsoft. An additional wizard provides the ability to configure other third party authentication providers. The wizards create an authentication module and an authentication chain containing the correct configuration needed to authenticate with the third party. The wizard also adds configuration data to the realm’s Social Authentication Implementations Service (and provisions the service if it is not already present) that enables the display of logos of configured third-party authentication providers on the OpenAM login screen, as shown below. Configuring Pre-Populated Social Authentication Providers OpenAM provides wizards to quickly enable authentication with Facebook, Google, and Microsoft. Most settings are pre-populated, only a Client ID and Client Secret are required. To obtain a Client ID and Client Secret you should register an application with the third party provider, at the following links: Facebook Facebook App Quickstart Google Google Developers Console You must enable the Google+ API in order to authenticate with Google. To enable the Google+ API, login to the Google Developers Console, select your project, navigate to APIs and auth > APIs, and then set the status of the Google+ API to ON. Microsoft Microsoft account Developer Center To Configure Pre-Populated Social Authentication Providers Once you have registered an application and obtained credentials from the social authentication provider, follow the steps below to configure authentication with the provider: Select Realms > Realm Name > Dashboard > Configure Social Authentication, and then click the link for the social authentication provider you want to configure—Configure Facebook Authentication, Configure Google Authentication, or Configure Microsoft Authentication. On the configure third party authentication page: Select the realm in which to enable social authentication. Enter the Client ID obtained from the third party authentication provider. Enter the Client Secret obtained from the third party authentication provider, and repeat it in the Confirm Client Secret field. Leave the default Redirect URL, unless you are using an external server as a proxy. Click Create. On completion, the wizard displays a message confirming the successful creation of a new authentication module and an authentication chain for the provider, and either the creation of a new Social Authentication Implementations service named socialAuthNService, or an update if it already existed. You can configure the authentication module, authentication chain, and Social Authentication Implementations service that you created by using the wizards in the same way as manually created versions. For more information, see "Configuring Authentication Modules", "Configuring Authentication Chains", and "Configuring the Social Authentication Implementations Service". Configuring Custom Social Authentication Providers OpenAM provides a wizard to quickly enable authentication with any third party provider that supports the OpenID Connect Discovery 1.0 specification. You must first register an application with the third party provider to obtain a Client ID, Client Secret, and the OpenID Discovery URL. To Configure Custom Social Authentication Providers Once you have registered an application and obtained your credentials from the social authentication provider, follow the steps below to configure authentication with the provider: Select Realms > Realm Name > Dashboard > Configure Social Authentication, and then click the Configure Other Authentication link. On the configure social authentication page: Select the realm in which to enable social authentication. Enter the OpenID Discovery URL obtained from the third party authentication provider. Enter a name for the provider in the Provider Name field. OpenAM uses this as a label on the login page to identify the provider. Enter the URL of an image to be used on the login page in the Image URL field. OpenAM places the image on the login page, to enable authentication with the provider. Enter the Client ID obtained from the third party authentication provider. Enter the Client Secret obtained from the third party authentication provider, and repeat it in the Confirm Client Secret field. Leave the default Redirect URL, unless you are using an external server as a proxy. Click Create. On completion, the wizard displays a message confirming the successful creation of a new authentication module and an authentication chain for the provider, and either the creation of a new Social Authentication Implementations service named socialAuthNService, or an update if it already existed. You can configure the authentication module, authentication chain, and Social Authentication Implementations service that you created by using the wizard in the same way as manually created versions. For more information, see "Configuring Authentication Modules", "Configuring Authentication Chains", and "Configuring the Social Authentication Implementations Service". Configuring the Social Authentication Implementations Service You can add logos to the login page to allow users to authenticate using configured social authentication providers. Wizards are provided to configure common social authentication providers, which also configure the Social Authentication Implementations Service to add logos to the login page. You can manually add other authentication chains that contain an OAuth 2.0/OpenID Connect authentication module. To add a social authentication provider to the login screen, you must first configure an OAuth 2.0/OpenID Connect authentication module, and an authentication chain that contains it: Use a wizard. See "Configuring Pre-Populated Social Authentication Providers" and "Configuring Custom Social Authentication Providers". Configure the Social Authentication Implementations Service, and then create an authentication module and a chain. See "To Configure the Social Authentication Implementations Service", "Configuring Authentication Modules" and "Configuring Authentication Chains". To Configure the Social Authentication Implementations Service Once you have created an authentication chain containing an OAuth 2.0/OpenID Connect authentication module, follow the steps below to add a logo for the authentication provider to the login screen: On the Realms page of the OpenAM console, click the realm containing the authentication module and authentication chain to be added to the login screen. On the Services page for the realm: If the Social Authentication Implementations Service exists, click on it. If the Social Authentication Implementations Service does not exist, click Add a Service, and then select Social Authentication Implementations, and then click Create. On the Social Authentication Implementations page: In the Display Names section, enter a Map Key, enter the text to display as ALT text on the logo in the Corresponding Map Value field, and then click Add. OpenAM uses the value in the Map Key fields throughout the configuration to tie the various implementation settings to each other. The value is case-sensitive. In the Authentication Chains section, re-enter the Map Key used in the previous step, select the authentication chain from the Corresponding Map Value list, and then click Add. In the Icons section, re-enter the Map Key used in the previous steps, enter the path to a logo image to be used on the login screen in the Corresponding Map Value list, and then click Add. In the Enabled Implementations field, re-enter the Map Key used in the previous steps, and then click Add. Removing a Map Key from the Enabled Implementations list removes the associated logo from the login screen. There is no need to delete the Display Name, Authentication Chain or Icon configuration to remove the logo from the login screen. Click Save Changes. An icon now appears on the OpenAM login screen, allowing users to authenticate with the third party authentication provider. 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 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 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. 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. 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 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 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 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 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. 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 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 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. 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 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: 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 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 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 You can configure the Anonymous Authentication module using the OpenAM console by clicking Configure > Authentication > Anonymous. 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 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 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. 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. 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". 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: Click Add Module. In the Module Name box, enter Device-ID-Match. In the Type box, select Device Id (Match), and then click Create. Click Save Changes. 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: Click Add Chain. In the Chain Name box, enter a descriptive label for your authentication chain, and then click Create. Click Add Module. 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. 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. 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. 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: 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. In the Maximum stored profile quantity box, enter the max number of stored profiles. Any profile that exceeds this number will not be stored. In the Authentication Level box, enter a number corresponding to the authentication level of the module. Click Save Changes. 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 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". 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 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 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 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. 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. 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 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 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 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. 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 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 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. 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 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. 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. 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) 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 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. Example: `\https://openam.example.com:8443/openam/oauth2/authorize`. Access Token Endpoint URL /oauth2/access_token under the deployment URL. 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`. 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. 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. Consult with the authorization server’s documentation on what value it uses for the issuer field. 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. 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. 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 Hints for the Persistent Cookie Module The Persistent Cookie module supports the configuration of cookie lifetimes based on requests and a maximum time. Note that by default, the persistent cookie is called session-jwt. If Secure Cookie is enabled (Deployment > Servers > Server Name > Security > Cookie), the Persistent Cookie module only works over HTTPS. ssoadm service name: iPlanetAMAuthPersistentCookieService Before you begin, make sure a public key alias is defined in OpenAM. The Persistent Cookie module encrypts a JSON Web Token (JWT) using a public key from the OpenAM keystore. The keystore must be configured under Realms > Realm Name > Authentication > Settings > Security > Persistent Cookie Encryption Certificate Alias. If the keystore changes and the default test key is no longer present, the public key alias must be updated to reflect the change, otherwise the module will fail. Similarly, in multi-instance deployments, the keypair must be available on all OpenAM instances. To configure the Persistent Cookie module globally in the console, navigate to Configure > Authentication, and then click Persistent Cookie. In the window that appears you should see the following attributes: Idle Timeout Specify the maximum idle time between requests in hours. If that time is exceeded, the cookie is no longer valid. ssoadm attribute: openam-auth-persistent-cookie-idle-time Max Life Specify the maximum life of the cookie in hours. ssoadm attribute: openam-auth-persistent-cookie-max-life Enforce Client IP When enabled, enforces that the persistent cookie can only be used from the same client IP to which the cookie was issued. ssoadm attribute: openam-auth-persistent-cookie-enforce-ip Use secure cookie When enabled, adds the "Secure" attribute to the persistent cookie. ssoadm attribute: openam-auth-persistent-cookie-secure-cookie Use HTTP only cookie When enabled, adds the HttpOnly attribute to the persistent cookie. ssoadm attribute: openam-auth-persistent-cookie-http-only-cookie HMAC Signing Key Specify a key to use for HMAC signing of the persistent cookie. Values must be base64-encoded and at least 256 bits (32 bytes) long. For example, to generate an HMAC signing key, run the following: openssl rand -base64 32 or cat /dev/urandom | tr -dc 'a-zA-Z0-9' | fold -w 32 | head -n 1|base64 + Default: a random 256-bit secret key. ssoadm attribute: openam-auth-persistent-cookie-hmac-key When the Persistent Cookie module enforces 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. The Persistent Cookie module belongs with a second module in an authentication chain. To see how this works, navigate to Realms > Realm Name > Authentication > Chains. Create a new chain and add modules as shown in the figure. The following example shows how a Persistent Cookie module is sufficient. If the persistent cookie does not yet exist, authentication relies on LDAP: Select the Settings tab and locate settings for the post-authentication processing class. Set the Class Name to org.forgerock.openam.authentication.modules.persistentcookie.PersistentCookieAuthModule, as shown in the following figure: You should now be able to authenticate automatically, as long as the cookie exists for the associated domain. 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 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 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 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. 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. This feature only takes effect if the security manager is enabled for the JVM. ssoadm attribute: useSecurityManager Hints For the SecurID Authentication Module The SecurID module lets OpenAM authenticate users with RSA Authentication Manager software and RSA SecurID authenticators. 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 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. 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 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. 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 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. 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. 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. 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. 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. 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. 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. 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/. 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 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 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. 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 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 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 Nth 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. 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. 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. 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. 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 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. 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. 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". 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". 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. 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. Creating Multi-Factor Authentication Chains The following procedures provide steps for creating authentication chains that implement multi-factor authentication. 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: Select Authentication > Modules, and then click Add Module. The New Module page appears. 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. Click Create. A page that lets you configure the authentication module appears. 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: Select Authentication > Modules, and then click Add Module. The New Module page appears. 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). Click Create. A page that lets you configure the authentication module appears. 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: Select Authentication > Chains, and then click Add Chain. The Add Chain page appears. Specify a name of your choosing, for example myPushAuthChain, and then click Create. A page appears with the Edit Chain tab selected. Add the Data Store authentication module to the authentication chain as follows: Click Add a Module. The New Module dialog box appears. Fill in the New Module dialog box, specifying the Data Store authentication module. For this example, specify the Required flag. Click OK. The graphic showing your authentication chain now includes a Data Store authentication module. Add the ForgeRock Authenticator (Push) Registration authentication module to the authentication chain as follows: Click Add a Module. The New Module dialog box appears. 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. Click OK. The graphic showing your authentication chain now includes a Data Store, and a ForgeRock Authenticator (Push) Registration authentication module. Add the ForgeRock Authenticator (Push) authentication module to the authentication chain as follows: Click Add a Module. The New Module dialog box appears. Fill in the New Module dialog box, specifying the ForgeRock Authenticator (Push) authentication module that you created. For this example, specify the Required flag. 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. Click Save Changes to save the authentication chain. Test your authentication chain as follows: 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. 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: Select Authentication > Modules, and then click Add Module. The New Module page appears. 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). Click Create. A page that lets you configure the authentication module appears. 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: Select Authentication > Chains, and then click Add Chain. The Add Chain page appears. Specify a name of your choosing, for example myPasswordlessAuthChain, and then click Create. A page appears with the Edit Chain tab selected. Add the ForgeRock Authenticator (Push) authentication module to the authentication chain as follows: Click Add a Module. The New Module dialog box appears. Fill in the New Module dialog box, specifying the ForgeRock Authenticator (Push) authentication module that you created. For this example, specify the Requisite flag. Click OK. The graphic showing your authentication chain now includes a ForgeRock Authenticator (Push) authentication module. Click Save Changes to save the authentication chain. Test your authentication chain as follows: 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. 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. 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: Select Authentication > Settings > General. 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: Select Authentication > Modules, and then click Add Module. The New Module page appears. 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). Click Create. A page that lets you configure the authentication module appears. 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: Select Authentication > Chains, and then click Add Chain. The Add Chain page appears. Specify a name of your choosing, for example myOathAuthChain, and then click Create. A page appears with the Edit Chain tab selected. 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. Click OK. A graphic showing an authentication chain with a single Data Store module appears on the page. Add the ForgeRock Authenticator (OATH) authentication module to the authentication chain as follows: Click Add a Module. The New Module dialog box appears. 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. Click OK. The graphic showing your authentication chain now includes the Data Store and ForgeRock Authenticator (OATH) authentication module. Click Save Changes to save the authentication chain. Test your authentication chain as follows: 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. 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. 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: 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 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. 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". 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. 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. [1] 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. 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. 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. 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. 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. 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. 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. 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". 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. 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. 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. 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: Navigate to Configure > Server Defaults > Advanced, or Deployment > Servers > Server Name > Advanced. 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. 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 any port and 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/. Redirection URL Precedence OpenAM determines the redirection URL based on authentication success or failure. 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. 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. 1. For information about making the usage of one-time passwords mandatory in OpenAM, see"Letting Users Opt Out of One-Time Password Authentication". Administration Interfaces and Tools Defining Authorization Policies