Guide to working with authentication and single sign-on support. ForgeRock® Access Management provides authentication, authorization, entitlement and federation software.

Preface

This guide covers concepts, implementation procedures, and customization techniques for working with the authentication and single sign-on features of ForgeRock Access Management.

This guide is written for anyone using Access Management to manage authentication, sessions, and implement single sign-on.

About ForgeRock Identity Platform™ Software

ForgeRock Identity Platform™ is the only offering for access management, identity management, user-managed access, directory services, and an identity gateway, designed and built as a single, unified platform.

The platform includes the following components that extend what is available in open source projects to provide fully featured, enterprise-ready software:

  • ForgeRock Access Management (AM)

  • ForgeRock Identity Management (IDM)

  • ForgeRock Directory Services (DS)

  • ForgeRock Identity Gateway (IG)

  • ForgeRock Identity Message Broker (IMB)

Chapter 1. Introducing Authentication and Single Sign-On

Authentication is the process of verifying login credentials submitted by a user or an entity comparing them to a database of authorized users. This guide covers how to set up, customize, and use the authentication process.

1.1. About Access Management and Authentication

Access management is about controlling access to resources using two processes: authentication and authorization.

Authentication is how AM verifies the identity of a user or an entity. Authorization is how AM determines whether a user has sufficient privileges to access to a protected resource, and if so, access is granted to that user or entity. AM's authorization process is covered in the Authorization Guide.

AM 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 redirect passengers to border control. Border control then determines, or authenticates, the identity of each passenger 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.

AM uses defined mechanisms to validate credentials and complete the authentication process. The authentication methods can vary. For example, AM is most frequently used to protect web application pages.

Consider a user who wants access to a protected web page. You can deploy an agent on the web application server. The agent redirects the user's request to an AM login page, where the user enters their credentials, such as username and password. AM determines who the user is, and whether the user has the right to access the protected page. AM then redirects the user back to the protected page with authorization credentials that can be verified by the agent. The agent allows the user authorized by AM to access the page.

You can use AM to protect physical devices connected on the Internet of things (IoT). For example, a delivery van tracking system could have its proxying gateway authenticate to a brokering system using an X.509 certificate to allow it to enable an HTTPS protocol and then connect to sensors in its delivery trucks. If the X.509 certificate is valid, the brokering system can monitor a van's fuel consumption, speed, mileage, and overall engine condition to maximize each van's operating efficiency.

1.2. Authentication Features

AM supports a number of authentication features and services for use in your deployment:

  • Authentication Nodes and Trees. AM provides a number of authentication nodes to handle different modes of authenticating users. The nodes must be connected together in a tree to provide multiple authentication paths to users. For more information, see Section 1.3, "About Authentication Trees".

  • Authentication Modules and Chains. AM provides a number of authentication modules to handle different modes of authenticating users or entities. The modules also can be chained together to provide multiple authentication mechanisms, so that a user's or entity's credentials must be evaluated by one module before control passes to another module. For more information, see Section 1.4, "About Authentication Modules and Chains".

  • Authentication Levels. AM allows each module to be configured with an authentication level, which indicates the security level of the user's or entity's credentials. If the user needs to gain access to more sensitive resources, AM may require the user or entity to reauthenticate, providing an additional credential of another type. For more information, see Section 1.5, "About Authentication Levels".

  • Social Authentication. You can configure AM to accept authentication provided by popular third-party identity providers, such as Facebook, Google, and Microsoft. For more information, see Section 1.6, "About Social Authentication".

  • Multi-Factor Authentication. AM supports multi-factor authentication, which requires a user to provide multiple forms of credentials, such as username and password, and a one-time password sent to a user's mobile phone. For more information, see Section 1.7, "About Multi-Factor Authentication".

  • Account Lockout. AM can lock accounts after a pre-configured number of failed authentication attempts. Account lockout works with modules for which users enter a password. For more information, see Section 1.8, "About Account Lockout".

  • Sessions. AM creates an authentication session to track the progress of a user or entity as they authenticate. Once the user is authenticated, AM creates a session to identify the user or entity during any flow.

    For more information, see Section 1.9, "About Sessions".

  • Single Sign-On. AM allows a user or an entity to use one set of credentials to access multiple applications within a single domain. This is known as single sign-on (SSO). AM also supports Cross-Domain Single Sign-On (CDSSO). For more information, see Section 1.10, "About Single Sign-On".

1.3. About Authentication Trees

Authentication trees provide fine-grained authentication by allowing multiple paths and decision points throughout the authentication flow.

Authentication trees are made up of authentication nodes, which define actions taken during authentication, similar to authentication modules within chains. Authentication nodes are more granular than modules, with each node performing a single task such as collecting a username or making a simple decision. Unlike authentication modules, authentication nodes can have multiple outcomes rather than just success or failure.

You can create complex yet customer-friendly authentication experiences by linking nodes together, creating loops, and nesting nodes within a tree.

Figure 1.1. Example Authentication Tree
Designing Authentication Trees

The authentication trees technology demonstrates the direction AM is taking for administration of complex authorization scenarios, while offering a streamlined login experience to users.

Authentication trees differ in the following ways to traditional authentication chains:

  • Authentication nodes are not yet available for all the functionality provided by authentication modules.

  • Authentication trees cannot mix with authentication chains. Each authentication to AM can use either a tree or a chain, but not both together.

  • The functionality derived from post-authentication plugins, used traditionally with authentication chains, is handled differently when using trees. For example:

1.4. About Authentication Modules and Chains

AM allows you to configure authentication processes and then customize how they are applied. AM 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 AM, 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:

Table 1.1. Authentication Criteria, Flags, and Continuation Semantics
CriteriaFailPassExample

Requisite

Assigns fail flag.

Authentication chain fail flag.

Exits chain.

Assigns pass flag.

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

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

Authentication chain fail flag.

Continues chain.

Assigns pass flag.

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

Authentication chain pass flag.

Continues chain.

You could use an optional module to assign a higher authentication level if it passes. Consider a chain with a requisite Data Store module and an optional Certificate module. Users who only passed the Data Store module could be assigned a lower authentication level than users who passed both the Data Store and Certificate modules. The users with the higher authentication level could be granted access to more highly-secured resources.

Tip

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

The AM 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:

Figure 1.2. Authentication Chain with Each Criteria
Authentication chain with each criteria.

With AM, you can further set authentication levels per module, with higher levels being used typically to allow access to more restricted resources. The AM 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.

AM 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 AM to protect access to a wide range of applications used in your organization.

1.5. About Authentication Levels

When a user successfully authenticates, AM creates a session, which allows AM 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 reauthenticate again at a higher authentication level to access the requested resource.

The authentication level sets the level of security associated with a module or a tree path. Typically, the strongest form of authentication is assigned the highest authentication level.

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 AM'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 AM server.

Authorization policies may also require a particular authentication level to access sensitive resources, which might be at a higher level than the user currently has in the session. When an authenticated user tries to access a sensitive resource with a valid session that does not have the required authentication level, AM returns an authorization decision that denies access to the resource and returns an advice indicating that the user needs to reauthenticate at the required authentication level to access the resource. The web or Java agent or policy enforcement point can then send the user back to AM for session upgrade. For more information, see Section 1.9.4, "Session Upgrade".

1.6. About Social Authentication

AM supports delegated authentication through third-party identity providers, such as Facebook, Google, and VKontakte. The AM console provides setup wizards to configure authentication with each identity provider. An additional wizard provides the ability to configure other third-party authenticators. The following table summarizes the social authentication providers and standards that AM 6 supports:

Provider/StandardAuthentication Module?Wizard?
OpenID Connect 1.0YesYes
OAuth 2.0YesNo
FacebookYes [a] Yes
GoogleYes [a] Yes
InstagramYesNo
VKontakteYesYes
WeChatYesNo
WeChat MobileYesNo

[a] Configure a Social Auth OpenID authentication module.

Each AM wizard creates 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 to enable the display of logos of the configured third-party authentication providers on the AM login screen, as shown below.

Figure 1.3. Login Screen With Social Authentication Logos
Login screen with social authentication logos.

Chapter 3, "Implementing Social Authentication" describes how to set up social authentication in AM.

1.7. About Multi-Factor Authentication

Multi-factor authentication is an authentication technique that requires users to provide multiple forms of identification when logging in to AM.

This section describes multi-factor authentication features in AM. See Chapter 4, "Implementing Multi-Factor Authentication" for information about how to set up multi-factor authentication in AM.

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 AM 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 AM:

  1. An AM administrator configures an authentication chain with the Data Store and ForgeRock Authenticator (OATH) authentication modules.

  2. An end user authenticates to AM using that authentication chain.

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

  4. If the user ID and password were correct, AM prompts the user to obtain a one-time password.

  5. The user runs an authenticator app on a mobile phone that generates and displays a one-time password.

  6. The user provides the one-time password to AM 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.

AM supports the Open AuTHentication (OATH) protocols, and also push notification for multi-factor authentication.

1.7.1. About Open AuTHentication (OATH)

The ForgeRock Authenticator (OATH) module supports HMAC one-time password (HOTP) and time-based one-time password (TOTP) authentication as defined in the OATH standard protocols for HOTP (RFC 4226) and TOTP (RFC 6238). Both HOTP and TOTP authentication require an OATH-compliant device that can provide the password.

HOTP authentication generates the one-time password every time the user requests a new password on their device. The device tracks the number of times the user requests a new one-time password with a counter. The one-time password displays for a period of time you designate in the setup, so the user may be further in the counter on their device than on their account.

AM 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 AM 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 AM. 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 AM to match their device. For more information, see Section 4.4.7, "Resetting 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.

1.7.2. Differences Among Authentication Modules That Support HOTP

The ForgeRock Authenticator (OATH), OATH, and HOTP authentication modules 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 AM:

Table 1.2. Comparing the ForgeRock Authenticator (OATH) to the HOTP Authentication Module
RequirementAvailable With the ForgeRock Authenticator (OATH) Authentication Module?Available With the HOTP Authentication Module?
End users can authenticate using a HOTP passwordYesYes
AM can generate a HOTP password and send it to end users in a text message or an e-mail NoYes
End users can register a mobile phone with AM, and an authenticator app on the phone can generate a HOTP or TOTP password that AM accepts as proof of authentication YesNo
End users can authenticate with a TOTP passwordYesNo
End users can opt out of providing a one-time passwordYesNo
End users can authenticate using XUIYesYes
End users can authenticate using the legacy UINoYes

1.7.3. About Push Authentication

You can use push notifications as part of the authentication process in AM.

To receive push notifications when authenticating, end users must register an Android or iOS device with AM. The registered device can then be used as an additional factor when authenticating to AM. AM 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 AM.

Figure 1.4. Overview of Push Authentication
Overview of Push Authentication

The following steps occur when AM receives an authentication request and is configured for multi-factor authentication using push notifications:

  1. The user must provide credentials to enable AM to locate the user in the identity store and determine if they have a registered mobile device.

  2. AM 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 Section 4.4, "Managing Devices for Multi-Factor Authentication".

  3. Once the details of the registered device are obtained, AM creates a push message specific to the registered device. The message has a unique ID, which AM 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.

  4. AM sends the push message to the registered device.

    AM uses cloud-based push notification services to deliver the messages to the devices. Depending on the registered device, AM 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 AM and the CTS for an accepted response from the registered device.

  5. 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 Procedure 4.9, "To Perform Authentication using Push Notifications".

    The app returns the response to the AM cluster.

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

1.7.4. 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 Section 4.3.1, "Creating Authentication Chains for Push Authentication".

1.8. About Account Lockout

AM can lock accounts after repeated authentication failures. Account lockout works with modules for which users can enter a password incorrectly.

Chapter 5, "Implementing Account Lockout" describes how to set up account lockout in AM.

1.9. About Sessions

AM creates an authentication session to track the user's authentication progress through an authentication chain or tree. Once the user has authenticated, AM creates a session to manage the user's or entity's access to resources.

AM session-related services are stateless unless otherwise indicated; they do not hold any session information local to the AM instances. Instead, they store session information either in the CTS token store or on the client. This architecture allows you to scale your AM infrastructure horizontally since any server in the deployment can satisfy any session's request.

Sessions are highly configurable. We recommend you become familiar with basic session concepts before attempting to configure sessions for your environment:

1.9.1. Session Storage Location

Session storage location is configured at the realm level. The following table illustrates where AM can store sessions:

Table 1.3. Session Storage Location
 In the CTS Token StoreOn the ClientIn AM's Memory
Authentication Sessions[a][a] (Default in new installations)[b] (Default after upgrade)
Sessions (Default)

[a] Authentication trees only.

[b] Available for authentication trees and authentication chains.


Session storage location can be heterogeneous within the same AM deployment to suit the requirements of each of your realms.

1.9.1.1. CTS-Based Sessions

CTS-based sessions reside in the CTS token store and can be cached in memory on one or more AM servers to improve system performance [1]. If the session request is redirected to an AM server that does not have the session cached, that server must retrieve the session from the CTS token store.

AM sends a reference to the session to the client, but the reference does not contain any of the session state information. AM can modify a session during its lifetime without changing the client's reference to the session.

  • CTS-Based Authentication Sessions Specifics

    CTS-based authentication sessions are supported for authentication trees only.

    During authentication, the session reference is returned to the client after a call to the authenticate endpoint and stored in the authId object of the JSON response.

    AM maintains the authenticating user's session in the CTS token store. After the authentication flow has completed, if the realm to which the user has authenticated is configured for client-based sessions, AM returns session state to the client and deletes the CTS-based session.

    Authentication session whitelisting is an optional feature that maintains a list of in-progress authentication sessions and their progress in the authentication flow to protect against replay attacks. For more information, see Section 6.4, "Implementing Authentication Session Whitelisting".

  • CTS-Based Sessions

    Once the user is authenticated, the session reference is known as an SSO token. For browser clients, AM sets a cookie in the browser that contains the session reference. For REST clients, AM returns the session reference in response to calls to the authentication endpoint.

    For more information about session cookies, see Section 1.9.2, "Session Cookies".

1.9.1.2. Client-Based Sessions

Client-based sessions are those where AM returns session state to the client after each request, and require it to be passed in with the subsequent request.

Important

Some features are not supported in realms configured for client-based sessions. For more information, see Section 6.2.5, "Limitations When Using Client-Based Sessions".

You should configure AM to sign and/or encrypt client-based sessions and authentication sessions for security reasons. As decrypting and verifying the session may be an expensive operation to perform on each request, AM caches[1] the decrypt sequence in memory to improve performance.

For more information about configuring client-based security, see Section 6.2.3, "Configuring Client-Based Session and Authentication Session Security".

  • Client-Based Authentication Sessions Specifics

    Client-based authentication sessions are supported for authentication trees only, and are configured by default in new installations.

    During authentication, authentication session state is returned to the client after each call to the authenticate endpoint and stored in the authId object of the JSON response.

    After the authentication flow has completed, if the realm to which the user has authenticated is configured for CTS-based sessions, AM creates the user's session in the CTS token store. Then, AM attempts to invalidate the client-based authentication session.

    Storing authentication sessions on the client allows any AM server to handle the authentication flow at any point in time without load-balancing requirements.

    Authentication session whitelisting is an optional feature that maintains a list of in-progress authentication sessions and their progress in the authentication flow to protect against replay attacks. For more information, see Section 6.4, "Implementing Authentication Session Whitelisting".

  • Client-Based Sessions Specifics

    For browser-based clients, AM sets a cookie in the browser that contains the session state. When the browser transmits the cookie back to AM, AM decodes the session state from the cookie. For REST-based clients, AM sends the cookie in a header. For more information about session cookies, see Section 1.9.2, "Session Cookies".

    Session blacklisting is an optional feature that maintains a list of logged out client-based sessions in the CTS token store. For more information about session termination and session blacklisting, see Section 1.9.3, "Session Termination" and Section 6.2.4, "Configuring Session Blacklisting".

1.9.1.3. In-Memory Sessions

In-memory sessions reside in AM's memory. AM sends clients a reference to the session, but the reference does not contain any of the session state information.

  • In-Memory Authentication Sessions Specifics

    In-memory authentication sessions are the only configuration supported for authentication chains. They are also configured by default for authentication trees after an upgrade.

    During authentication, the authentication session reference is returned to the client after a call to the authenticate endpoint and stored in the authId object of the JSON response.

    AM maintains the user's authentication session in its memory. After the authentication flow has completed, AM performs the following tasks:

    • If the realm to which the user has authenticated is configured for CTS-based sessions, AM stores the user's session in the CTS token store and deletes the authentication session from memory.

    • If the realm to which the user has authenticated is configured for client-based sessions, AM stores the user's session in a cookie on the user's browser and deletes the authentication session from memory.

    Authentication session whitelisting is an optional feature that maintains a list of in-progress authentication sessions and their progress in the authentication flow to protect against replay attacks. For more information, see Section 6.4, "Implementing Authentication Session Whitelisting".

    Important

    Deployments where AM stores authentication sessions in memory require sticky load balancing to route all requests pertaining to a particular authentication flow to the same AM server. If a request reaches a different AM server, the authentication flow will start anew.

    Authentication chains only support storing authentication sessions in memory. ForgeRock recommends switching to authentication trees with CTS-based or client-based authentication sessions.

    For information about configuring AM with sticky load balancing, see Section 2.2.3, "Configuring Load Balancing for a Site" in the Installation Guide.

  • In-Memory Sessions Specifics

    AM does not support in-memory sessions for authenticated users.

1.9.1.4. Choosing Where to Store Sessions

AM stores CTS-based sessions in the CTS token store and caches sessions in server memory. If a server with cached sessions fails, or if the load balancer in front of AM servers directs a request to a server that does not have the user's session cached, the AM server retrieves the session from the CTS token store, incurring performance overhead.

Choosing where to store sessions is an important decision you must make by realm. Consider the information in the following tables before configuring sessions:

CTS-based sessions provide the following advantages:

Table 1.4. Advantages of CTS-Based Sessions
AdvantageApplies to Authentication Sessions?Applies to Sessions?

Full Feature Support

CTS-based sessions support all AM features, such as CDSSO and quotas. Client-based sessions do not. For information about restrictions on AM usage with client-based sessions, see Section 6.2.5, "Limitations When Using Client-Based Sessions".

This advantage does not apply to authentication sessions, since they do not provide features.

Session Information Is Not Resident In Browser Cookies

With CTS-based sessions, all the information about the session resides in CTS and might be cached on one or more AM servers. With client-based sessions, session information is held in browser cookies. This information could be very long-lived.


Client-based sessions provide the following advantages:

Table 1.5. Advantages of Client-Based Sessions
AdvantageApplies to Authentication Sessions?Applies to Sessions?

Unlimited Horizontal Scalability for Session Infrastructure

Client-based sessions provides unlimited horizontal scalability for your sessions by storing the session state on the client as a signed and encrypted JWT.

Overall performance on hosts using client-based sessions can be easily improved by adding more hosts to the AM deployment.

Replication-Free Deployments

Global deployments may struggle to keep their CTS token store replication in sync when distances are long and updates are frequent.

Client-based sessions are not constrained by the replication speed of the CTS token store. Therefore, client-based sessions are usually more suitable for deployments where a session can be serviced at any time by any server.


In-memory authentication sessions provide the following advantages:

Table 1.6. Advantages of In-Memory Sessions
AdvantageApplies to Authentication Sessions?Applies to Sessions?

Faster Performance With Equivalent Host

AM servers configured for in-memory authentication sessions can validate more sessions per second per host than those configured for client-based or CTS-based authentication sessions.

Session Information Is Not Resident in Browser Cookies

Authentication session information resides in AM's memory and it is not accessible to users. With client-based sessions, authentication session information is held in browser cookies.


The following table contrasts the impact of storing authentication sessions in different locations:

Table 1.7. Impact of Storage Location for Authentication Sessions
 CTS-Based Authentication SessionsClient-Based Authentication SessionsIn-Memory Authentication Sessions
Authentication MethodAuthentication trees.Authentication trees.Authentication trees and authentication chains.
Session LocationAuthoritative source: CTS token store. Sessions might also be cached in AM's memory for improved performance.On the client. In AM server's memory.
Load Balancer RequirementsNone. Session stickiness recommended for performance.None. Session stickiness recommended for performance.Session stickiness.
Core Token Service UsageAuthoritative source for user sessions. Session whitelisting, when enabled.Session whitelisting, when enabled.None.
Uninterrupted Session AvailabilityNo special configuration required.No special configuration required.Not available.
Session SecuritySessions reside in the CTS token store, and are not accessible to users.Sessions reside on the client and should be signed and encrypted.Sessions reside in AM's memory, and are not accessible to users.

The following table contrasts the impact of storing sessions in different locations:

Table 1.8. Impact of Storage Location for Sessions
 CTS-Based SessionsClient-Based Sessions
HardwareHigher I/O and memory consumption.Higher CPU consumption.
Logical HostsVariable or large number of hosts.Variable or large number of hosts.
Session MonitoringAvailable.Not available.
Session Location

Authoritative source: CTS token store. Sessions might also be cached in AM's memory for improved performance.

In a cookie in the client.
Load Balancer RequirementsNone. Session stickiness recommended for performance.None. Session stickiness recommended for performance.
Uninterrupted Session Availability No special configuration required. No special configuration required.
Core Token Service UsageAuthoritative source for user sessions.Provides session blacklisting for logged out sessions.
Core Token Service DemandHeavier.Lighter.
Session Security Sessions reside in the CTS token store, and are not accessible to users. Sessions should be signed and encrypted. [a]
Cross-Domain Single Sign-On Support All AM capabilities supported.
  • Web and Java agents earlier than version 5: not supported.

  • Web Agents 5.x and Java Agents 5.x: Supported without restricted tokens.

[a] Web Agents 5.x and Java Agents 5.x support either signing or encrypting client-based sessions, but not both. For more information, see Section 6.2.3.4, "Configure Client-Based Session Security for Agents".


1.9.2. Session Cookies

AM issues a cookie to the user or entity regardless of the session location for client-based and CTS-based sessions. By default, the cookie's name is iPlanetDirectoryPro. For sessions stored in the CTS token store, the cookie contains a reference to the session in the CTS token store and several other pieces of information. For sessions stored on the client, the iPlanetDirectoryPro cookie contains all the information that would be held in the CTS token store.

Client-based session cookies are comprised of two parts. The first part of the cookie is identical to the cookie used by CTS-based sessions, which ensures the compatibility of the cookies regardless of the session location. The second part is a JSON Web Token (JWT), and it contains session information, as illustrated below:

  • iPlanetDirectoryPro cookie for CTS-based sessions:

    AQIC...sswo.*AAJ...MA..*
  • iPlanetDirectoryPro cookie for Client-based sessions:

    AQIC...sswo.*AAJ...MA..*ey....................................fQ.

Note that the examples are not to scale. The size of the client-based session cookie increases when you customize AM to store additional attributes in users' sessions. You are responsible for ensuring that the size of the cookie does not exceed the maximum cookie size allowed by your end users' browsers.

Note

You should configure AM to sign and/or encrypt client-based sessions to ensure a malicious user cannot tamper with the session or read its contents. For more information, see Section 6.2.3, "Configuring Client-Based Session and Authentication Session Security".

1.9.3. Session Termination

AM manages active sessions, allowing single sign-on when authenticated users attempt to access system resources in AM's control.

AM ensures that user sessions are terminated when a configured timeout is reached, or when AM users perform actions that cause session termination. Session termination effectively logs the user out of all systems protected by AM.

With CTS-based sessions, AM terminates sessions in four situations:

  • When a user explicitly logs out

  • When an administrator monitoring sessions explicitly terminates a session

  • When a session exceeds the maximum time-to-live

  • When a user is idle for longer than the maximum session idle time

Under these circumstances, AM responds by removing CTS-based sessions from the CTS token store and from AM server memory caches. With the user's session no longer present in CTS, AM forces the user to reauthenticate during subsequent attempts to access resources protected by AM.

When a user explicitly logs out of AM, AM also attempts to invalidate the iPlanetDirectoryPro cookie in users' browsers by sending a Set-Cookie header with an invalid session ID and a cookie expiration time that is in the past. In the case of administrator session termination and session timeout, AM cannot invalidate the iPlanetDirectoryPro cookie until the next time the user accesses AM.

Session termination differs for client-based sessions. Since client-based sessions are not maintained in the CTS token store, administrators cannot monitor or terminate them. Because AM does not modify the iPlanetDirectoryPro cookie for client-based sessions after authentication, the session idle time is not maintained in the cookie. Therefore, AM does not automatically terminate client-based sessions that have exceeded the idle timeout.

As with CTS-based sessions, AM attempts to invalidate the iPlanetDirectoryPro cookie from a user's browser when the user logs out. When the maximum session time is exceeded, AM also attempts to invalidate the iPlanetDirectoryPro cookie in the user's browser the next time the user accesses AM.

It is important to understand that AM cannot guarantee cookie invalidation. For example, the HTTP response containing the Set-Cookie header might be lost. This is not an issue for CTS-based sessions, because a logged out session no longer exists in the CTS token store, and a user who attempts to access AM after previously logging out will be forced to reauthenticate.

However, the lack of a guarantee of cookie invalidation is an issue for deployments with client-based sessions. It could be possible for a logged out user to have an iPlanetDirectoryPro cookie. AM could not determine that the user previously logged out. Therefore, AM supports a feature that takes additional action when users log out of client-based sessions. AM can maintain a list of logged out client-based sessions in a session blacklist in the CTS token store. Whenever users attempt to access AM with client-based sessions, AM checks the session blacklist to validate that the user has not, in fact, logged out.

For more information about session blacklist options, see Section 6.2.4, "Configuring Session Blacklisting".

1.9.4. Session Upgrade

Consider a website for a University. Some information, such as courses and degree catalogs, are free for anyone to see and therefore, do not need to be protected. The University also provides the students with a portal they can use to see their grades, which is protected with a policy that requires users to authenticate. However, to pay tuition, students are required to present additional credentials to increase their authentication level and gain access to these functions.

Allowing authenticated users to provide additional credentials to access sensitive resources is called session upgrade, which is AM's mechanism to perform step-up authentication.

Session upgrade triggers during the following events:

  • An authenticated user is redirected to a URL that has the ForceAuth parameter set to true. For example, https://openam.example.com:8443/openam/XUI/#login/myRealm&ForceAuth=true

    In this case, the user is asked to reauthenticate to the default chain in the realm myRealm.

    Important

    Session upgrade using the ForceAuth parameter is only supported for CTS-based sessions.

  • An authenticated user tries to access a protected resource and AM sends the policy enforcement point (PEP) advice that the user should perform one of the following actions:

    • Authenticate at an authentication level greater than the current level

    • Authenticate to a module

    • Authenticate to a service

    The flow of the session upgrade during policy evaluation is as follows:

    1. An authenticated user tries to access a resource.

    2. The PEP, for example a web or Java agent, sends the request to AM for policy decision.

    3. AM returns an authorization decision that denies access to the resource, and returns an advice indicating that the user needs to present additional credentials to access the resource.

    4. The policy enforcement point sends the user back to AM for session upgrade.

    5. The user provides additional credentials. For example, they may provide a one-time password or swipe their phone screen.

    6. AM authenticates the user.

    7. The user can access now the sensitive resource.

    If session upgrade is successful, one of the following will happen depending on the type of sessions configured for the realm:

    • If the realm is configured for CTS-based sessions, one of the following will happen depending on the mechanism used to perform session upgrade:

      • If you used the ForceAuth parameter, AM modifies the user's session in the CTS store to reflect the successful authentication to a higher level.

      • If you used advices, AM copies the session properties to a new session and hands the client a new session token to replace the original one. The new session reflects the successful authentication to a higher level.

    • If the realm is configured for client-based sessions, AM hands the client a new session token to replace the original one. The new session reflects the successful authentication to a higher level.

    If session upgrade is unsuccessful, AM leaves the user session as it was before the attempt at stronger authentication. If session upgrade failed because the login page times out, AM redirects the user's browser to the success URL from the last successful authentication.

For more information about performing session upgrade, see Section 9.6, "Performing Session Upgrade".

1.9.5. Session Quotas

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.

AM 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, AM takes the appropriate action.

See Section 6.1.1, "Implementing Session Quotas" for instructions.

AM's support for session quotas requires CTS-based sessions. Be sure that AM is configured for CTS-based sessions—the default configuration—before attempting to configure session quotas.

1.10. About Single Sign-On

Single sign-on (SSO) lets users who have authenticated to AM access multiple independent services from a single login session by storing user sessions as HTTP cookies. If you are unfamiliar with HTTP cookies, see Section 7.1, "About HTTP Cookies" for more information.

AM supports SSO within a single domain or across domains:

  • Cross-Domain SSO (CDSSO). Provides SSO when:

    • AM and the web and Java agents are in the same DNS domain. For example, both the agents and AM servers are in the .example.net DNS domain.

    • AM and the web and Java agents are in different DNS domains. For example, the AM servers are in the .internal.net DNS domain, and the agents are in the .example.net domain.

    CDSSO removes the constraint of configuring SSO depending on the DNS domain of AM and the web or Java agents, simplifying the deployment of SSO in the environment.

    For more information, see Section 1.10.1, "Cross-Domain SSO"

  • Classic Cross-Domain SSO. Provides SSO to web and Java agents earlier than version 5 when AM and the agents are in different DNS domains. For example, CDSSO allows AM servers in the DNS domain .internal.net to provide authentication and authorization to agents from other DNS domains, such as .example.net.

    For more information, see Section 1.10.3, "Classic Cross-Domain SSO"

  • Classic Single Domain SSO. Provides SSO to web and Java agents earlier than version 5 when AM and the agents are in the same DNS domain. For example, both the agents and AM servers are in the .example.net DNS domain.

    For more information, see Section 1.10.4, "Classic Single Domain SSO".

1.10.1. Cross-Domain SSO

Cross-domain single sign-on (CDSSO) provides a safe mechanism for managing access across one or multiple domains in a single organization. For example, CDSSO allows your AM servers in the DNS domain .internal.net to provide authentication and authorization to web and Java agents from the .internal.net domain and other DNS domains, such as .example.net.

When implementing CDSSO in your deployment, take into account the following points:

  • CDSSO is an AM-specific capability to provide SSO inside the same organization. For SSO across multiple organizations or when integrating with other access management software, use AM's federation capabilities.

  • CDSSO is the only mode available for Web Agents 5.x and Java Agents 5.x, and it provides SSO for AM servers and the agents within a single domain or across domains in the same organization.

    CDSSO is also supported with IG version 6 or later. For more information, see Single Sign-On and Cross-Domain Single Sign-On in the ForgeRock Identity Gateway Gateway Guide.

  • CDSSO supports CTS-based and client-based sessions. For more information about session state impact on CDSSO, see Table 1.8, "Impact of Storage Location for Sessions".

  • CDSSO does not support web and Java agents earlier than version 5. If you need to configure CDSSO for agents earlier than version 5, see Section 1.10.3, "Classic Cross-Domain SSO".

Web Agents 5.x and Java Agents 5.x wrap the SSO session token inside an OpenID Connect (OIDC) JSON Web Token (JWT) [2]. During the CDSSO flow, the agents create cookies for the different domains specified in the agent profile, and the oauth2/authorize endpoint authorizes the different cookie domains as required.

The following diagram illustrates the CDSSO flow for Web Agents 5.x and Java Agents 5.x:

Figure 1.5. Agents 5 CDSSO Flow
Agents 5 CDSSO Flow

For information about how to configure CDSSO, see Section 7.2, "Implementing Cross-Domain Single Sign-On".

1.10.2. About Realms and SSO

When changing authentication realms, a subject leaves the current SSO realm. The new SSO realm might apply to different applications, and use a different authentication process. For AM, logging in to a new realm means logging out of the current realm.

When a user interactively changes realms through the AM console, AM offers the option of logging out of the current realm to log in to the new realm, or choosing to remain logged in to the current realm.

The result depends on the user's choice:

  • If the user cancels the change at this point, the user remains logged in to the current realm, and is not logged in to the new realm.

  • If the user chooses to log in to the new realm, AM first logs the user out of the current realm, and then prompts the user to log in to the new realm.

1.10.3. Classic Cross-Domain SSO

Classic cross-domain single sign-on (CDSSO) provides a mechanism for web and Java agents earlier than version 5 to manage access across multiple domains in a single organization. For example, CDSSO allows your AM servers in the DNS domain .internal.net to provide authentication and authorization to agents from other DNS domains, such as .example.net.

When implementing classic CDSSO in your deployment, take into account the following points:

  • Classic CDSSO is an AM-specific capability to provide SSO inside the same organization. For SSO across multiple organizations or when integrating with other access management software, use AM's federation capabilities.

  • Classic CDSSO requires CTS-based sessions.

  • Classic CDSSO does not support Web or Java Agents 5.x. If you need to configure CDSSO for Web Agents 5.x and Java Agents 5.x, see Section 1.10.1, "Cross-Domain SSO".

Java agents [3] use a mechanism to write the SSO token from AM authentication to a cookie with the domain of the host where the agent runs. The following sequence diagram illustrates this mechanism:

Figure 1.6. CDSSO Flow for Java Agents (earlier than version 5)
CDSSO Flow for Java Agents (earlier than version 5)

Whereas Java agents[3] have an endpoint specifically to handle the cookie domain translation, web agents [3] handle the request directly as shown in the following sequence diagram:

Figure 1.7. CDSSO Flow for Web Agents (earlier than version 5)
CDSSO Flow for Web Agents (earlier than version 5)

For information about how to configure cross-domain SSO, see Section 7.3, "Implementing Classic Single Domain and Cross-Domain SSO".

1.10.4. Classic Single Domain SSO

Classic single domain SSO provides web and Java agents earlier than version 5 with SSO capabilities when AM and the agents are in the same DNS domain.

The following diagram illustrates single domain SSO:

Figure 1.8. SSO With Web and Java Agents (earlier than version 5)
SSO with Web and Java Agents (earlier than version 5)

  • The domain shown in the description is example.net.

  • The protected resource application can be found on app.example.net.

  • The AM server is located on sso.example.net.

A client points their browser to a protected resource application. An agent protecting the application checks the client browser cookies for the presence of a session. If a session cookie exists and is valid, the agent requests validation (see arrow 8).

If no valid session cookie exists, the agent redirects the client to AM for authentication (AuthN). If the client submits valid credentials, the AuthN service creates a session cookie for the configured domain. The contents of the session cookie varies, depending on the configuration of the realm to which the user authenticates:

  • If the realm is configured for CTS-based sessions, an SSO token is embedded in the cookie.

  • If the realm is configured for client-based sessions, the session itself is embedded in the cookie.

AM issues an HTTP redirect to send the client browser back to the protected resource.

The agent then verifies the validity of the session with the AM session service, before granting access.

For information about how to configure SSO in a single domain, see Section 7.3, "Implementing Classic Single Domain and Cross-Domain SSO".



[1] For information about configuring AM with sticky load balancing, see Section 2.2.3, "Configuring Load Balancing for a Site" in the Installation Guide.

[2] For information about the OIDC standards, see Section 5.1, "OpenID Connect 1.0 Standards" in the OpenID Connect 1.0 Guide.

[3] Earlier than version 5

Chapter 2. Implementing Authentication

AM supports a wide range of authentication modules that can be configured together using authentication chains, and authentication nodes that can be configured together using authentication trees.

AM also supports post-authentication plugins to customize any process after the user or the entity has been authenticated.

After you configure AM authentication, users can authenticate to AM using a browser or a REST API call as described in Chapter 8, "Using Authentication".

This chapter presents the available authentication modules and nodes, and procedures to configure chains, trees, and post-authentication plugins:

Section 2.1, "Setting up a Realm for Authentication"
Section 2.2, "Configuring Authentication Trees"
Section 2.3, "Configuring Authentication Chains and Modules"
Section 2.4, "Configuring the Default Authentication Tree or Chain"

2.1. Setting up a Realm for Authentication

In AM, users always authenticate to a realm. Every AM realm has a set of authentication properties that applies to all authentication performed to that realm. The settings are referred to as core authentication attributes.

To configure core authentication attributes for an entire AM deployment, navigate to Configure > Authentication in the AM console, and then click Core Attributes.

Figure 2.1. The Core Authentication Attributes Page
The core authentication attributes page is divided into seven tabs.

To override the global core authentication configuration in a realm, navigate to Realms > Realm Name > Authentication > Settings in the AM console. Note that when you configure core authentication attributes in a realm, the Global tab does not appear.

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

For detailed information about the core configuration attributes, see Section 11.1, "Core Authentication Attributes".

2.2. Configuring Authentication Trees

This section covers creating authentication trees and configuring authentication nodes.

Authenticating to a tree uses the same syntax as authenticating to a chain. For example, to authenticate to a tree called myAuthTree in the top level realm, use a URL similar to the following: https://openam.example.com:8443/openam/XUI/?realm=/#login/&service=myAuthTree

Procedure 2.1. To Create an Authentication Tree
  1. On the Realms page of the AM console, select the realm in which to create the authentication tree.

  2. On the Realm Overview page, select Authentication in the left-hand menu, and then select Trees.

  3. On the Trees page, select Create Tree. Enter a tree name, for example myAuthTree, and then select Create.

    The authentication tree designer is displayed, with the Start entry point connected to the Failure exit point.

    The authentication tree designer provides the following features on the toolbar:

    Table 2.1. Authentication Tree Designer Toolbar
    ButtonUsage
    Lay out and align nodes according to the order they are connected.
    Toggle the designer window between normal and full screen layout.
    Remove the selected node. Note that the Start entry point cannot be deleted.

  4. Add a node to the tree by dragging the node from the Components panel on the left-hand side and dropping it into the designer area.

  5. (Optional) Configure the node properties by using the right-hand panel. For more information on the available properties for each node, see Section 2.2.1, "Configuring Authentication Nodes"

  6. Connect the node to the tree as follows:

    • Select and drag the output connector from an existing node and drop it onto the new node.

    • Select and drag the output connector from the new node and drop it onto an existing node.

    Nodes have one or more connectors, displayed as dots on the node. Unconnected connectors are colored red and must be connected to other nodes in the tree.

    Tip

    Input connectors appear on the left of the node, output connectors appear on the right.

    A line is drawn between the connectors of connected nodes, and the connectors will no longer be red.

  7. (Optional) Alter a connection by selecting and dragging the green connector in the connection and dropping it onto the new location.

  8. Continue adding, connecting and removing nodes until the tree is complete, and then select Save.

  9. Test your authentication tree by navigating to a URL similar to the following: https://openam.example.com:8443/openam/XUI/?realm=/#login/&service=myAuthTree

Tip

Clean installs of AM provide ready-made sample authentication trees to demonstrate how they can be put together. These sample trees are not installed by default if you are upgrading an existing instance of AM. The sample-trees-6.0.0.5.zip file, in the main AM-6.0.0.5.zip download package, contains the sample trees in JSON files, ready for import by Amster command-line interface. For information on importing files by using Amster, see Importing Configuration Data in the Amster 6 User Guide.

2.2.1. Configuring Authentication Nodes

This section covers the configuration of the authentication nodes that are built into AM.

Tip

A number of additional authentication nodes are available from the ForgeRock Marketplace website.

2.2.1.1. Account lockout Node

The Account lockout node can lock or unlock the authenticating user's account profile.

Properties:

PropertyUsage
Lock Action

Choose whether to LOCK or UNLOCK the authenticating user's account profile.

The Section 2.2.1.6, "Data Store Decision Node" and Section 2.2.1.6, "Data Store Decision Node" both check if the account profile is in the LOCK state.

Example:

The following example uses the Account lockout Decision authentication node with the Retry Limit Decision Node to lock an account after a number of invalid attempts:

Figure 2.2. RetryLimit Tree With Account lockout Decision Node
RetryLimit tree showing Account lockout Decision node usage.

2.2.1.2. Anonymous User Mapping Node

The Anonymous User Mapping node allows users to log in to your application or web site without providing credentials, by assuming the identity of a specified, existing user account. The default user for this purpose is named anonymous.

Typically, you would provide such users with very limited access, for example, anonymous users may have access to public downloads on your site.

Properties:

PropertyUsage
Anonymous User Name

Specifies the username of an account that represents anonymous users. This user must already exist in the realm.

Example:

The following example uses the Anonymous User Mapping authentication node to allow users who have performed social authentication using Google to access AM as an anonymous user if they do not have a matching existing profile.

Figure 2.3. Google-AnonymousUser Tree With Anonymous User Mapping Node
Google-AnonymousUser tree showing Anonymous User Mapping node usage.

2.2.1.3. Auth Level Decision Node

The Auth Level Decision authentication node compares the current authentication level value against a configured value.

Properties:

PropertyUsage
Sufficient Authentication Level The tree evaluation continues along the True path if the current authentication level is equal to or greater than the entered integer. Otherwise, the tree evaluation continues along the False path.

2.2.1.4. Choice Collector Node

The Choice Collector authentication node lets you define two or more options to present to the user when authenticating.

Properties:

PropertyUsage
Choices

Enter two or more choice strings to display to the user.

To remove a choice, select its Delete icon (x). To delete all choices, select the Clear all button in the Choices field.

Default choice Enter the value of the choice to be selected by default.
Prompt Enter the prompt string to display to the user when presenting the choices.

Example:

2.2.1.5. Create Password Node

The Create Password node allows users to create a password when provisioning an account.

The social identity provider will not provide a user's password. Use this node to provide a password to complete the user's credentials before provisioning an account.

The tree must provision an account after asking the user for a password, for example by using the Provision Dynamic Account authentication node. If an account is not provisioned the entered password will not be saved.

Note

You must not place any nodes that request additional input from the user between the Create Password node and the provisioning node, otherwise the password will be lost.

Properties:

PropertyUsage
minPasswordLength

Specifies the minimum number of characters the password must contain.

Example:

The following example uses the Create Password authentication node to allow users who have performed social authentication using Google to provide a password and provision an account, if they do not have a matching existing profile. They must enter a one-time password to verify they are the owner of the Google account.

Figure 2.4. Google-DynamicAccountCreation Tree With Create Password Node
Google-DynamicAccountCreation tree showing Create Password node usage.

2.2.1.6. Data Store Decision Node

The Data Store Decision authentication node verifies that the username and password values exist in the data store configured in the realm.

For example, the username and password could be obtained by a combination of the Username Collector and Password Collector nodes, or the Zero Page Login Collector node.

The tree evaluation continues along the True path if the credentials are located in the configured data store and the user account profile is not locked. Otherwise, the tree evaluation continues along the False path.

Properties:

This node has no configurable properties.

2.2.1.7. Failure URL Node

The Failure URL authentication node sets the URL to be redirected to when authentication fails.

Note

Specifying a failure URL in a tree overrides any gotoOnFail query string parameters.

If not specified, the tree uses the value specified in the Default Failure Login URL property under Realms > Realm Name > Authentication > Settings > Post Authentication Processing.

Tip

The URL is also saved into the sharedState object, under a property named failureUrl, which can be useful for custom node developers. For more information, see Section 10.1, "Customizing Authentication Trees".

Properties:

PropertyUsage
Failure URL Specify the full URL to be redirected to when authentication fails.

2.2.1.8. Get Session Data Node

The Get Session Data authentication node retrieves the value of a specified key from a user's session data, and stores it in the specified key in the tree's sharedState object.

The Get Session Data authentication node is only used during session upgrade—when the user has already successfully authenticated previously—and is now upgrading their session for additional access. For more information on upgrading a session, see Section 1.9.4, "Session Upgrade"

The following table includes example keys that may be available in an existing session, and sample data that they might contain:

Table 2.2. Get Session Data Node Example Keys and Values
KeySample value
AMCtxIde370cca2-02d6-41f9-a244-2b107206bd2a-122934
amlbcookie01
authInstant2018-04-04T09:19:05Z
AuthLevel0
CharSetUTF-8
clientTypegenericHTML
FullLoginURL/openam/UI/Login?realm=%2F
Host198.51.100.1
HostNameopenam.example.com
Localeen_US
Organizationdc=openam,dc=forgerock,dc=org
Principalid=amadmin,ou=user,dc=openam,dc=forgerock,dc=org
Principalsamadmin
ServiceldapService
successURL/openam/console
sun.am.UniversalIdentifierid=amadmin,ou=user,dc=openam,dc=forgerock,dc=org
UserIdamadmin
UserProfileRequired
UserTokenamadmin
webhooksmyWebHook

Properties:

PropertyUsage
Session Data Key Specify the name of a key in the user's session data from which to retrieve the value.
Shared State Key Specify the name of a key in the sharedState object in which to store the retrieved value.

2.2.1.9. HOTP Generator Node

The HOTP Generator authentication node creates a string of random digits, of the length specified. The default length is 8 digits.

Properties:

PropertyUsage
One-time password length Specify the number of digits in the one-time password.

Use alongside the following authentication nodes to add one-time password verification to the authentication tree:

Example:

Figure 2.5. HmacOneTimePassword Tree With HOTP Generator Node
HmacOneTimePassword tree showing HOTP Generator node usage.

2.2.1.10. Inner Tree Evaluator Node

The Inner Tree Evaluator authentication node allows the nesting and evaluation of authentication trees as children within a parent tree. There is no limit to the depth of nested trees.

Any information collected or set by the parent tree, for example, a username or the authentication level, is available to the child trees. Information collected by child trees is available to the parent once evaluation of the child is complete.

The tree evaluation continues along the True path if the child tree reached the Success exit point. Otherwise, the tree evaluation continues along the False path.

Properties:

PropertyUsage
Tree name Enter the name of the tree to evaluate.

2.2.1.11. LDAP Decision Node

The LDAP Decision authentication node verifies that the provided username and password values exist in a specified LDAP user data store, and whether they are expired or locked out.

For example, the username and password could be obtained by a combination of the Username Collector and Password Collector nodes, or by using the Zero Page Login Collector node.

The tree evaluation continues along the True outcome path if the credentials are located in the specified LDAP user data store. If the profile associated with the username and password is locked, or the password has expired, tree evaluation continues along the respective Locked or Expired outcome paths.

If the credentials are not found, the tree evaluation continues along the False outcome path.

Properties:

PropertyUsage

Primary LDAP Server

Specify one or more primary directory servers. Specify each directory server in the following format: host:port.

For example, directory_services.example.com:389.

Secondary LDAP Server

Specify one or more secondary directory servers. Specify each directory server in the following format: host:port.

Secondary servers are used when none of the primary servers are available.

For example, directory_services_backup.example.com:389.

DN to Start User Search

Specify the DN from which to start the user search. More specific DNs, such as ou=sales,dc=example,dc=com, result in better search performance.

If multiple entries exist in the store with identical attribute values, ensure this property is specific enough to return only one entry.

Bind User DN, Bind User Password

Specifies the credentials used to bind to the LDAP user data store.

Attribute Used to Retrieve User Profile

Specifies the attribute used to retrieve the profile of a user from the directory server.

The user search will have already happened, as specified by the Attributes Used to Search for a User to be Authenticated and User Search Filter properties.

Attributes Used to Search for a User to be Authenticated

Specifies the attributes used to match an entry in the directory server to the credentials provided by the user.

The default value of uid will form the following search filter of uid=user. Specifying multiple values such as uid and cn causes the node to create a search filter of (|(uid=user)(cn=user)).

Multiple attribute values allow the user to 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.

User Search Filter

Specifies an additional filter to append to user searches.

For example, searching for mail and specifying a User Search Filter of (objectClass=inetOrgPerson), causes AM to use (&(mail=address)(objectClass=inetOrgPerson)) as the resulting search filter, where address is the mail address provided by the user.

Search Scope

Specifies the extent of searching for users in the directory server.

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.

Default: SUBTREE

LDAP Connection Mode

Specifies whether to use SSL or StartTLS to connect to the LDAP user data store. AM must be able to trust the certificates used.

Possible values: LDAP, LDAPS, and StartTLS

Default: LDAP

Return User DN to DataStore

When enabled, the node returns the DN rather than the User ID. From the DN value, AM 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, AM uses uid=demo to search the data store.

Default: Enabled

User Creation Attributes

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

Minimum Password Length

Specifies the minimum acceptable password length.

Default: 8

LDAP Behera Password Policy Support

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

Default: Enabled

Trust All Server Certificates

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

Default: Disabled

LDAP Connection Heartbeat Interval

Specifies how often AM 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. Set the units for the interval in the LDAP Connection Heartbeat Time Unit property.

Default: 10

LDAP Connection Heartbeat Time Unit

Specifies the time unit corresponding to LDAP Connection Heartbeat Interval.

Default: Seconds

LDAP Operations Timeout

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

Default: 0 (means no timeout)

2.2.1.12. Meter Node

The Meter authentication node increments a specified metric key each time tree evaluation passes through the node. For information on the Meter metric type, see Section 10.7.2, "Monitoring Metric Types" in the Setup and Maintenance Guide. The metric is exposed in all available interfaces, as described in Section 8.3.1, "Monitoring Interfaces" in the Setup and Maintenance Guide.

Properties:

PropertyUsage
Metric Key Specify the name of a metric to increment when tree evaluation passes through the node.

2.2.1.13. Modify Auth Level Node

The Modify Auth Level authentication node lets you increase or decrease the current authentication level value.

The tree evaluation continues along the single outcome path after modifying the authentication level.

Properties:

PropertyUsage
Value to add Enter a positive integer to increase the current authentication level, or a negative integer to decrease the current authentication level by the specified value.

2.2.1.14. OAuth 2.0 Node

The OAuth 2.0 authentication node lets AM authenticate users of OAuth 2.0-compliant resource servers. References in this section are to RFC 6749, The OAuth 2.0 Authorization Framework.

The tree evaluation continues along the Account Exists path if an account matching the attributes retrieved from the social identity provider is found in the user data store. Otherwise, the tree evaluation continues along the No account exists path.

Properties:

PropertyUsage
Client ID

Specifies the client_id parameter as described in section 2.2 of The OAuth 2.0 Authorization Framework (RFC 6749).

Client Secret

Specifies the client_secret parameter as described in section 2.3 of The OAuth 2.0 Authorization Framework (RFC 6749).

Authentication Endpoint URL

Specifies the URL to the social provider's endpoint handling authentication as described in section 3.1 of The OAuth 2.0 Authorization Framework (RFC 6749).

Example: https://accounts.google.com/o/oauth2/v2/auth

Access Token Endpoint URL

Specifies the URL to the endpoint handling access tokens as described in section 3.2 of The OAuth 2.0 Authorization Framework (RFC 6749).

Example: https://www.googleapis.com/oauth2/v4/token

User Profile Service URL

Specifies the user profile URL that returns profile information.

Exaple: https://www.googleapis.com/oauth2/v3/userinfo

OAuth Scope

Specifies a list of user profile attributes that the client application requires, according to The OAuth 2.0 Authorization Framework (RFC 6749). Ensure you use the correct scope delimiter as required by the identity provider, for example commas or spaces.

The list depends on the permissions that the resource owner, such as the end user, grants to the client application.

Scope Delimiter

Specifies the delimiter used to separate scope values.

Some authorization servers use non-standard separators for scopes, for example commas.

Redirect URL

Specifies the URL the user is redirected to by the social identity provider after authenticating.

For authentication trees in AM, set this property to the URL of the XUI, for example https://openam.example.com:8443/openam/XUI/.

Social Provider

Specifies the name of the social provider for which this module is being set up.

Example: Google

Auth ID Key

Specifies the attribute the social identity provider uses to identify an authenticated individual.

Example: id

Use Basic Auth

Specifies that the client uses HTTP Basic authentication when authenticating to the social provider.

Default: true

Account Provider

Specifies the name of the class that implements the account provider.

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

Account Mapper

Specifies the name of the class that implements the method of locating local accounts based on the attributes returned from the social identity provider.

Provided implementations are:

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

The Account Mapper classes can take two constructor parameters: a comma-separated list of attributes and a prefix to apply to their values. For example, to prefix all received property values with facebook- before searching, specify:

org.forgerock.openam.authentication.modules.common.mapping.JsonAttributeMapper|*|facebook-

Attribute Mapper

Specifies the list of fully qualified class names for implementations that map attributes from the OAuth 2.0 authorization server to AM profile attributes.

Provided implementations are:

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

The Attribute Mapper classes can take two constructor parameters: a comma-separated list of attributes and a prefix to apply to their values, to help differentiate between the providers. For example, to prefix all incoming values with facebook-, specify:

org.forgerock.openam.authentication.modules.common.mapping.JsonAttributeMapper|*|facebook-

Be aware however using an asterisk applies the prefix to all values, including email addresses, postal addresses, and so on.

Account Mapper Configuration

Specifies the attribute configuration used to map the account of the user authenticated in the OAuth 2.0 provider to the local data store in AM. Valid values are in the form provider-attr=local-attr.

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

Attribute Mapper Configuration

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

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

Save attributes in the session

When enabled, saves the attributes in the Attribute Mapper Configuration field to the AM session.

OAuth 2.0 Mix-Up Mitigation Enabled

Controls whether the OAuth 2.0 authentication node carries out additional verification steps when it receives the authorization code from the authorization server.

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.

The Token Issuer property must be entered when the OAuth 2.0 Mix-Up Mitigation feature is enabled, so that the validation can succeed. The authorization code response will contain an issuer value (iss) that will be validated by the client.

Note

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

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

Token Issuer

Corresponds to the expected issuer identifier value in the iss field of the ID token.

Example: https://accounts.google.com

2.2.1.15. OTP Collector Decision Node

The OTP Collector Decision authentication node requests and verifies one-time passwords.

The tree evaluation continues along the True outcome path if the entered one-time password is valid for the authentication in progress. Otherwise, the tree evaluation continues along the False outcome path.

Properties:

PropertyUsage
One Time Password Validity Length

Specify the length of time, in minutes, that a one-time password remains valid.

Default: 5

2.2.1.16. OTP Email Sender Node

The OTP Email Sender authentication node sends an email containing a generated one-time password to the user.

Properties:

PropertyUsage
Mail Server Host Name

Specifies the hostname of the SMTP email server.

Mail Server Host Port

Specifies the outgoing mail server port. Common ports are 25, 465 (when connecting over SSL), or 587 (for StartTLS).

Mail Server Authentication Username

Specifies the username AM uses to connect to the mail server.

Mail Server Authentication Password

Specifies the password AM uses to connect to the mail server.

Email From Address

Specifies the email address from which the one-time password will appear to have been sent.

Email Attribute Name

Specifies the user's profile attribute containing the email address to which to email the OTP.

Default: mail

Mail Server Secure Connection

Specifies how to connect to the mail server. If a secure method is specified, AM must trust the server certificate of the mail server.

The possible values for this property are:

  • NON SSL/TLS

  • SSL/TLS

  • Start TLS

Default: SSL/TLS

Gateway Implementation Class

Specifies the class the node uses to send SMS and email messages. A custom class must implement the com.sun.identity.authentication.modules.hotp.SMSGateway interface.

Default: com.sun.identity.authentication.modules.hotp.DefaultSMSGatewayImpl

2.2.1.17. OTP SMS Sender Node

The OTP SMS Sender authentication node uses an email-to-SMS gateway provider to send an SMS message containing a generated one-time password to the user.

The node sends an email to an address formed by joining the following values together:

  • The user's telephone number, obtained by querying a specified profile attribute, for example telephoneNumber.

  • The @ character.

  • The email-to-SMS gateway domain, obtained by querying the profile attribute specified by the Mobile Carrier Attribute Name property.

For example, if configured to use the TextMagic email-to-SMS service, the node might send an email through the specified SMTP server to the address: 18005550187@textmagic.com.

Properties:

PropertyUsage
Mail Server Host Name

Specifies the hostname of the SMTP email server.

Mail Server Host Port

Specifies the outgoing mail server port. Common ports are 25, 465 (when connecting over SSL), or 587 (for StartTLS).

Mail Server Authentication Username

Specifies the username AM uses to connect to the mail server.

Mail Server Authentication Password

Specifies the password AM uses to connect to the mail server.

Email From Address

Specifies the email address from which the one-time password will appear to have been sent.

Mobile Phone Number Attribute Name

Specifies the user's profile attribute containing the mobile phone number to which to send the SMS containing the OTP.

Default: telephoneNumber

Mobile Carrier Attribute Name

Specifies the user's profile attribute containing the mobile carrier domain used as the email to SMS gateway.

Mail Server Secure Connection

Specifies how to connect to the mail server. If a secure method is specified, AM must trust the server certificate of the mail server.

The possible values for this property are:

  • NON SSL/TLS

  • SSL/TLS

  • Start TLS

Default: SSL/TLS

Gateway Implementation Class

Specifies the class the node uses to send SMS and email messages. A custom class must implement the com.sun.identity.authentication.modules.hotp.SMSGateway interface.

Default: com.sun.identity.authentication.modules.hotp.DefaultSMSGatewayImpl

2.2.1.18. Page Node

The Page authentication node combines multiple nodes that request input into a single page for display to the user. Drag and drop nodes on to the page node to combine them.

The outcome paths are determined by the last node in the page node. Only the last node in the page can have more than one outcome path.

Only nodes that use callbacks to request input can be added to a page node. Other nodes, such as the Data Store Decision Node and Push Sender Node must not be added to a page node.

Properties:

This node has no configurable properties.

Example:

The following example uses a page node containing a username collector, a password collector, and a choice collector:

Figure 2.6. Example Tree With Page Node
Example tree showing Page node usage.

The user is presented with all of the requests for input on a single page:

Figure 2.7. User View of Example Tree with Page Node
User's view of an example tree containing a page node.

2.2.1.19. Password Collector Node

The Password Collector authentication node prompts the user to enter their password. The captured password is transient, persisting only until the authentication flow reaches the next node requiring user interaction.

The tree evaluation continues along the single outcome path after capturing the password.

Properties:

This node has no configurable properties.

2.2.1.20. Polling Wait Node

The Polling Wait authentication node pauses progress of the authentication tree for a specified number of seconds, for example in order to wait for a response to a one-time password email or push notification.

Requests to the tree made during the wait period are sent a PollingWaitCallback callback and an authentication ID. For example, the following callback indicates a wait time of 10 seconds:

{
    "authId": "eyJ0eXAiOiJK...u4WvZmiI",
    "callbacks": [
        {
            "type": "PollingWaitCallback",
            "output": [
                {
                    "name": "waitTime",
                    "value": "10000"
                },
                {
                    "name": "message",
                    "value": "Waiting for response..."
                }
            ]
        }
    ]
}

The client must wait 10 seconds before returning the callback data, including the authId. For example:

$ curl \
--request POST \
--header 'Accept-API-Version: resource=2.0, protocol=1.0' \
--header 'Content-Type: application/json' \
--data '{
  "authId": "eyJ0eXAiOiJK...u4WvZmiI",
  "callbacks": [
      {
          "type": "PollingWaitCallback",
          "output": [
              {
                  "name": "waitTime",
                  "value": "10000"
              },
              {
                  "name": "message",
                  "value": "Waiting for response..."
              }
          ]
      }
  ]
}' 'https://openam.example.com:8443/openam/json/realms/root/authenticate?authIndexType=service&authIndexValue=Example'

For more information on authenticating using the REST API, see Section A.6, "Authentication and Logout".

When using the XUI for authentication, it automatically waits for the required amount of time and resubmit the page in order to continue tree evaluation. The message displayed whilst waiting is configurable by using the Waiting Message property.

Tree evaluation continues along the Done outcome path when the next request is received after the wait time has passed.

Enabling Spam detection adds a Spam outcome path to the node. Tree evaluation continues along the Spam outcome path if more than the specified number of requests are received during the wait time.

Enabling the user to exit without waiting adds an Exited outcome path to the node. Tree evaluation continues along the Exited outcome path if the user clicks the button that appears when the option is enabled. The message displayed on the exit button is configurable by using the Exit Message property.

Properties:

PropertyUsage
Seconds To Wait

Specify the number of seconds to pause the authentication tree.

Default: 8

Enable Spam Detection

Specify whether to track the number of responses received during the wait time, and continue tree evaluation along the Spam outcome path if the number specified in the Spam Tolerance property is exceeded.

Default: Disabled

Spam Tolerance

Specify the number of responses to allow during the wait time before continuing tree evaluation along the Spam outcome path. This property only applies if spam detection is enabled.

Default: 3

Waiting Message

Specifies the optional message to display to the user.

You can provide the message in multiple languages by specifying the locale in the KEY field, for example en-US. For information on valid locale strings, see JDK 8 and JRE 8 Supported Locales. The locale selected for display is based on the user's locale settings in their browser.

Messages provided in the node override the defaults provided by AM. For information about customizing and translating the default messages, see Section 10.1.1.5, "Localizing an Authentication Node".

Exitable

Specify whether the user can exit the node during the wait period. Enabling this option adds a button with a configurable message to the page. Clicking the button causes tree evaluation to continue along the Exited outcome path.

Default: Disabled

Exit Message

Specifies the optional message to display to the user on the button used to exit the node before the wait period has elapsed. For example, Cancel or Lost phone? Use Recovery Code. This property only applies if the Exitable property is enabled.

You can provide the message in multiple languages by specifying the locale in the KEY field, for example en-US. For information on valid locale strings, see JDK 8 and JRE 8 Supported Locales. The locale selected for display is based on the user's locale settings in their browser.

Messages provided in the node override the defaults provided by AM. For information about customizing and translating the default messages, see Section 10.1.1.5, "Localizing an Authentication Node".

2.2.1.21. Provision Dynamic Account Node

The Provision Dynamic Account node provisions an account following successful authentication by a social identity provider node. Accounts are provisioned using properties defined in the attribute mapper configuration of a social authentication node earlier in the tree evaluation, for example the OAuth 2.0 Node.

If a password has been acquired from the user, for example by using the Create Password Node, it is used when provisioning the account. Otherwise, a 20 character random string is used.

Properties:

PropertyUsage
Account Provider

Specifies the name of the class that implements the account provider.

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

Example:

The following example uses the Provision Dynamic Account authentication node to allow users who have performed social authentication using Google to provide a password and provision an account, if they do not have a matching existing profile. They must enter a one-time password to verify they are the owner of the Google account.

Figure 2.8. Google-DynamicAccountCreation Tree With Provision Dynamic Account Node
Google-DynamicAccountCreation tree showing Provision Dynamic Account node usage.

2.2.1.22. Provision IDM Account Node

The Provision IDM Account node redirects users to an IDM instance to provision an account.

Ensure you have configured the details of the IDM instance in AM, by navigating to Configure > Global Services > IDM Provisioning.

For information on using IDM for provisioning, see Integrating IDM With the ForgeRock Identity Platform in the Samples Guide.

Properties:

PropertyUsage
Account Provider

Specifies the name of the class that implements the account provider.

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

Example:

The following example uses the Provision IDM Account authentication node to allow users who have performed social authentication using Facebook to provision an account using IDM, if they do not have a matching existing profile.

Figure 2.9. Facebook-ProvisionIDMAccount Tree With Provision IDM Account Node
Facebook-ProvisionIDMAccount tree showing Provision IDM Account node usage.

2.2.1.23. Push Result Verifier Node

The Push Result Verifier node works together with the Push Sender Node to validate the user's response to a previously sent push notification message.

Tree evaluation continues along the Success outcome path if the push notification was positively responded to by the user. For example, using the ForgeRock Authenticator app, the user slid the switch with a checkmark on horizontally to the right.

Tree evaluation continues along the Failure outcome path if the push notification was negatively responded to by the user. For example, using the ForgeRock Authenticator app, the user tapped the cancel icon in the top-right of the screen.

If the push notification was not responded to within the Message Timeout value specified in the Push Sender Node then tree evaluation continues along the Expired outcome path.

If a response to the push message has not yet been received, then tree evaluation continues along the Waiting outcome path.

Tip

If the push message contained any additional information, for example if it was a registration request, the values are stored in the sharedState object of the tree, in a key named pushContent. For information on creating or customizing authentication nodes, see Section 10.1.1, "Creating or Modifying an Authentication Node".

Properties:

This node has no configurable properties.

2.2.1.24. Push Sender Node

The Push Sender authentication node sends push notification messages to a device such as a mobile phone, enabling multi-factor authentication.

The Push Sender authentication node requires that the Push Notification Service has also been configured. For information on the properties used by the service, see Section 11.3.4, "Push Notification Service". For information on provisioning the credentials used by the service, see How to set up AM Push Notification Service credentials in the ForgeRock Knowledge Base.

Tree evaluation continues along the Sent outcome path if the push notification was successfully sent to the handling service.

If the user does not have a registered device, tree evaluation continues along the Not Registered outcome path. To determine whether the user has a registered device, the tree must have already acquired a username, for example by using a Username Collector Node.

Note

Authentication trees are not capable of registering a device to a profile. For information on using authentication chains to register devices, see Section 4.3.1, "Creating Authentication Chains for Push Authentication".

If the user chooses to skip push authentication, tree evaluation continues along the Skipped outcome path. You can configure whether the user is able to skip the node by setting the Two Factor Authentication Mandatory property. See Section 4.2, "Letting Users Opt Out of One-Time Password Authentication".

Properties:

PropertyUsage
Message Timeout

Specifies the number of milliseconds the push notification message will remain valid. The Push Result Verifier Node rejects responses to push messages that have timed out.

User Message

Specifies the optional message to send to the user.

You can provide the message in multiple languages by specifying the locale in the KEY field, for example en-US. For information on valid locale strings, see JDK 8 and JRE 8 Supported Locales. The locale selected for display is based on the user's locale settings in their browser.

Messages provided in the node override the defaults provided by AM. For information about customizing and translating the default messages, see Section 10.1.1.5, "Localizing an Authentication Node".

The following variables can be used in the VALUE field:

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

Example: Login attempt from {{user}} at {{issuer}}.

Remove 'skip' option

Enable this option in the node to make the push authentication mandatory. When set to Disabled the user can skip the push authentication requested by the node, and tree evaluation continues along the Skipped outcome path.

Default: Disabled

Note

Nodes in authentication trees are not affected by the Two Factor Authentication Mandatory property, available at Realms > Realm Name > Authentication > Settings > General, as it only applies to modules within authentication chains.

Example:

Figure 2.10. Example Push Tree
Push Example tree showing Push Sender and Push Result Verifier node usage.

The example tree above shows one possible implementation of multi-factor push authentication.

If the user has a registered device:

  1. A push notification is sent to their registered device.

  2. The Polling Wait Node pauses the authentication tree for 8 seconds, during which time the user can respond to the push notification on their device, for example by using the ForgeRock Authenticator application.

    • If the user responds positively, they are authenticated successfully and logged in.

    • If the user responds negatively, they are not authenticated successfully and do not receive a session.

    • If the push notification expires, the tree will send a new push notification.

      Tip

      A Retry Limit Decision node could be used here to constrain the number of times a new code is sent.

    • If the user has not yet responded, the tree loops back a step and the Polling Wait Node pauses the authentication tree for another 8 seconds.

    If the user exits the Polling Wait Node, they can enter a recovery code in order to authenticate.

    Tip

    In this situation, configure the Exit Message property in the Polling Wait node with a message such as: Lost phone? Use a Recovery Code, which appears as follows:

    Example Exit Message

    A Retry Limit Decision node allows three attempts at entering a recovery code before failing the authentication.

If the user does not have a registered device:

  1. Because trees cannot currently register devices, a Set Failure URL node redirects the user to an authentication chain which can register a device to the user's profile.

  2. That registration chain redirects the user back to the push example tree when registration is complete.

If the configuration allows it and the user chooses to skip multi-factor authentication:

  1. An Inner Tree Evaluator node provides an alternative method of authentication, for example an LDAP Decision node.

  2. Depending on the outcome of the inner tree, the push example tree evaluation continues to the Success or Failure outcome.

2.2.1.26. Recovery Code Collector Decision Node

The Recovery Code Collector Decision authentication node allows users to authenticate using a recovery code provided when registering a device for multi-factor authentication.

Use this node when a tree is configured to use push notifications or one-time passwords but the user has lost the registered device, and must therefore use an alternative method for authentication. For more information on obtaining the recovery codes for a registered device, see Section 4.4.3, "Accessing Your Recovery Codes".

Tree evaluation continues along the True outcome path if the provided recovery code matches one belonging to the user. To determine whether the provided code belongs to the user, the tree must have already acquired the username, for example by using a Username Collector Node.

If the recovery code does not match, or a username has not been acquired, tree evaluation continues along the False outcome path.

Properties:

PropertyUsage
Recovery Code Type

Specify the type of recovery code the user will submit for verification.

Default: OATH

2.2.1.27. Register Logout Webhook Node

The Register Logout Webhook authentication node registers the specified webhook to trigger when a user's session ends. The webhook triggers when a user explicitly logs out, or the maximum idle time or expiry time of the session is reached.

The webhook is only registered if tree evaluation passes through the Register Logout Webhook node. You can register multiple webhooks during the authentication process, but they must be unique.

For more information on webhooks, see Section 2.2.2, "Configuring Authentication Webhooks".

Properties:

PropertyUsage
Webhook name Specify the name of the webhook to register.

2.2.1.28. Remove Session Properties Node

The Remove Session Properties authentication node enables the removal of properties from the session. The session properties may have been set by a Set Session Properties node elsewhere in the tree.

If a specified key is not found in the list of session properties that will be added to the session upon successful authentication, no error is thrown and tree evaluation continues along the single outcome path.

If a specified key is found, the tree evaluation continues along the single outcome path after setting the value of the property to null.

Properties:

PropertyUsage
Property Names Enter one or more key names of properties to remove from the session.

2.2.1.29. Retry Limit Decision Node

The Retry Limit Decision authentication node allows the specified number of passes through to the Retry outcome path, before continuing tree evaluation along the Reject outcome path.

Properties:

PropertyUsage
Retry limit

Specify the number of times to allow a retry.

Default: 3

Example:

Figure 2.12. RetryLimit Tree
RetryLimit tree showing Retry Limit Decision node usage.

2.2.1.30. Scripted Decision Node

The Scripted Decision authentication node allows execution of scripts during authentication. Tree evaluation continues along the path matching the result.

The script defines the possible outcome paths by setting one or more values of a string variable named outcome. For more information on creating scripts, see Section B.3.1, "Managing Scripts With the AM Console".

The tree evaluation continues along the outcome path that matches the value of the outcome variable when script execution completes.

For information about the API available for use in the Scripted Decision Node, see Section 11.5, "Scripted Decision Node API Functionality".

Properties:

PropertyUsage
Script Select the script to execute from the drop-down field.
outcomes Enter the possible strings that can be assigned to the outcome variable by the script. These strings provide the possible outcome paths the tree can continue along.

2.2.1.32. Set Session Properties Node

The Set Session Properties authentication node allows the addition of key:value properties to the user's session if authentication is successful.

Tip

You can access session properties using a variable in a webhook. For more information, see Section 2.2.2, "Configuring Authentication Webhooks".

The tree evaluation continues along the single outcome path after setting the specified properties in the session.

Properties:

PropertyUsage
Properties To add a session property, select the Add button, enter a key name and a value, and then select the plus icon. Repeat the steps to add multiple properties.

2.2.1.33. Social Facebook Node

The Social Facebook authentication node is a duplicate of the OAuth 2.0 Node node, preconfigured to work with Facebook. Only the Client ID and Client Secret are required to be populated.

The tree evaluation continues along the Account Exists path if an account matching the attributes retrieved from Facebook are found in the user data store. Otherwise, the tree evaluation continues along the No account exists path.

Properties:

PropertyUsage
Client ID

Specifies the client_id parameter as provided by Facebook.

Client Secret

Specifies the client_secret parameter as provided by Facebook.

Authentication Endpoint URL

Specifies the URL to the social provider's endpoint handling authentication as described in section 3.1 of The OAuth 2.0 Authorization Framework (RFC 6749).

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

Access Token Endpoint URL

Specifies the URL to the endpoint handling access tokens as described in section 3.2 of The OAuth 2.0 Authorization Framework (RFC 6749).

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

User Profile Service URL

Specifies the user profile URL that returns profile information.

Default: https://graph.facebook.com/v2.6/me?fields=name%2Cemail%2Cfirst_name%2Clast_name

OAuth Scope

Specifies a comma-separated list of user profile attributes that the client application requires, according to The OAuth 2.0 Authorization Framework (RFC 6749) . The list depends on the permissions that the resource owner, such as the end user, grants to the client application.

Redirect URL

Specifies the URL the user is redirected to by Facebook after authenticating, to continue the authentication tree flow.

Set this property to the URL of the AM XUI, for example https://openam.example.com:8443/openam/XUI/.

Social Provider

Specifies the name of the social provider for which this module is being set up.

Default: facebook

Auth ID Key

Specifies the attribute the social identity provider uses to identify an authenticated individual.

Default: id

Use Basic Auth

Specifies that the client uses HTTP Basic authentication when authenticating to the social provider.

Default: true

Account Provider

Specifies the name of the class that implements the account provider.

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

Account Mapper

Specifies the name of the class that implements the method of locating local accounts based on the attributes returned from Facebook.

Default:

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

Attribute Mapper

Specifies the list of fully qualified class names for implementations that map attributes from Facebook to AM profile attributes.

Default:

org.forgerock.openam.authentication.modules.common.mapping.JsonAttributeMapper|uid|facebook-

Account Mapper Configuration

Specifies the attribute configuration used to map the account of the user authenticated in the Social Facebook provider to the local data store in AM. Valid values are in the form provider-attr=local-attr.

Default: id=uid.

Attribute Mapper Configuration

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

Default: name=cn, last_name=sn, id=uid, first_name=givenname, email=mail.

Save attributes in the session

When enabled, saves the attributes in the Attribute Mapper Configuration field to the AM session.

Default: true.

OAuth 2.0 Mix-Up Mitigation Enabled

Controls whether the authentication node carries out additional verification steps when it receives the authorization code from the authorization server.

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.

The Token Issuer property must be entered when the OAuth 2.0 Mix-Up Mitigation feature is enabled, so that the validation can succeed. The authorization code response will contain an issuer value (iss) that will be validated by the client.

Note

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

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

Token Issuer

Corresponds to the expected issuer identifier value in the iss field of the ID token.

Example: https://graph.facebook.com

Example:

The following example uses the Provision IDM Account authentication node to allow users who have performed social authentication using Facebook to provision an account using IDM, if they do not have a matching existing profile.

Figure 2.13. Facebook-ProvisionIDMAccount Tree With Provision IDM Account Node
Facebook-ProvisionIDMAccount tree showing Provision IDM Account node usage.

2.2.1.34. Social Google Node

The Social Google authentication node is a duplicate of the OAuth 2.0 Node node, preconfigured to work with Google. Only the Client ID and Client Secret are required to be populated.

The tree evaluation continues along the Account Exists path if an account matching the attributes retrieved from Google are found in the user data store. Otherwise, the tree evaluation continues along the No account exists path.

Properties:

PropertyUsage
Client ID

Specifies the client_id parameter as provided by Google.

Client Secret

Specifies the client_secret parameter as provided by Google.

Authentication Endpoint URL

Specifies the URL to the social provider's endpoint handling authentication as described in section 3.1 of The OAuth 2.0 Authorization Framework (RFC 6749).

Default: https://accounts.google.com/o/oauth2/v2/auth

Access Token Endpoint URL

Specifies the URL to the endpoint handling access tokens as described in section 3.2 of The OAuth 2.0 Authorization Framework (RFC 6749).

Default: https://www.googleapis.com/oauth2/v4/token

User Profile Service URL

Specifies the user profile URL that returns profile information.

Default: https://www.googleapis.com/oauth2/v3/userinfo

OAuth Scope

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

Default: profile email.

Redirect URL

Specifies the URL the user is redirected to by Google after authenticating, to continue the authentication tree flow.

Set this property to the URL of the AM XUI, for example https://openam.example.com:8443/openam/XUI/.

Social Provider

Specifies the name of the social provider for which this module is being set up.

Default: google

Auth ID Key

Specifies the attribute the social identity provider uses to identify an authenticated individual.

Default: sub

Use Basic Auth

Specifies that the client uses HTTP Basic authentication when authenticating to Google.

Default: true

Account Provider

Specifies the name of the class that implements the account provider.

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

Account Mapper

Specifies the name of the class that implements the method of locating local accounts based on the attributes returned from Google.

Default:

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

Attribute Mapper

Specifies the list of fully qualified class names for implementations that map attributes from Google to AM profile attributes.

Default:

org.forgerock.openam.authentication.modules.common.mapping.JsonAttributeMapper|iplanet-am-user-alias-list|google-

Account Mapper Configuration

Specifies the attribute configuration used to map the account of the user authenticated in the Social Google provider to the local data store in AM. Valid values are in the form provider-attr=local-attr.

Default: sub=uid.

Attribute Mapper Configuration

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

Default: sub=uid, name=cn, given_name=givenName, family_name=sn, email=mail.

Save attributes in the session

When enabled, saves the attributes in the Attribute Mapper Configuration field to the AM session.

Default: true.

OAuth 2.0 Mix-Up Mitigation Enabled

Controls whether the authentication node carries out additional verification steps when it receives the authorization code from the authorization server.

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.

The Token Issuer property must be entered when the OAuth 2.0 Mix-Up Mitigation feature is enabled, so that the validation can succeed. The authorization code response will contain an issuer value (iss) that will be validated by the client.

Note

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

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

Token Issuer

Corresponds to the expected issuer identifier value in the iss field of the ID token.

Example: https://accounts.google.com

Example:

The following example uses the Anonymous User Mapping authentication node to allow users who have performed social authentication using Google to access AM as an anonymous user if they do not have a matching existing profile.

Figure 2.14. Google-AnonymousUser Tree With Anonymous User Mapping Node
Google-AnonymousUser tree showing Anonymous User Mapping node usage.

2.2.1.35. Social Ignore Profile Node

The Social Ignore Profile authentication node specifies if a local user profile should be ignored. If tree evaluation passes through this node, after successful social authentication, AM issues an SSO token regardless of whether a user profile exists in the data store. The presence of a user profile is not checked.

Properties:

This node has no configurable properties.

2.2.1.36. Success URL Node

The Success URL authentication node sets the URL to be redirected to when authentication succeeds.

Note

Specifying a success URL in a tree overrides any goto query string parameters.

If not specified, the tree uses the value specified in the Default Success Login URL property under Realms > Realm Name > Authentication > Settings > Post Authentication Processing.

Tip

The URL is also saved into the sharedState object, under a property named successUrl, which can be useful for custom node developers. For more information, see Section 10.1, "Customizing Authentication Trees".

Properties:

PropertyUsage
Success URL Specify the full URL to be redirected to when the authentication succeeds.

2.2.1.37. Timer Start Node

The Timer Start authentication node starts a named timer metric, which can be stopped elsewhere in the tree by using the Timer Stop Node.

Properties:

PropertyUsage
Start Time Property Specify a property name into which to store the current time. Specify the same value in any instances of the Timer Stop Node that measure the time elapsed since tree evaluation passed through this node.

2.2.1.38. Timer Stop Node

The Timer Stop authentication node records the time elapsed since tree evaluation passed through the specified Timer Start Node in the specified metric name. For information on the Timer metric type, see Section 10.7.2, "Monitoring Metric Types" in the Setup and Maintenance Guide.

Note that the time stored in the specified Start Time Property property is not reset by the Timer Stop Node, so other Timer Stop Nodes in the tree can also calculate the time elapsed since tree evaluation passed through the same Timer Start Node.

The metric is exposed in all available interfaces, as described in Section 8.3.1, "Monitoring Interfaces" in the Setup and Maintenance Guide.

Properties:

PropertyUsage
Start Time Property Specify the property name containing the time from which to calculate the elapsed time.
Metric Key Specify the name of a metric in which to store the calculated elapsed time.

2.2.1.39. Username Collector Node

The Username Collector authentication node prompts the user to enter their username.

The tree evaluation continues along the single outcome path after capturing the username.

Properties:

This node has no configurable properties.

2.2.1.40. Zero Page Login Collector Node

The Zero Page Login Collector authentication node checks whether selected headers are provided in the incoming authentication request, and if so, uses their value as the provided username and password.

The tree evaluation continues along the Has Credentials outcome path if the specified headers are available in the request, or the No Credentials path if the specified headers are not present.

A common use for the Zero Page Login Collector authentication node is to connect the Has Credentials outcome connector to the input of a Data Store Decision node, and the No Credentials outcome connector to the input of a Username Collector node followed by a Password Collector node, and then into the same Data Store Decision node as earlier. For an example of this layout, see the default Example authentication tree provided in AM. See Figure 2.15, "Example Tree With Zero Page Login Node".

The password collected by the Zero Page Login Collector node is transient, persisting only until the authentication flow reaches the next node requiring user interaction.

Properties:

PropertyUsage
Username Header name

Enter the name of the header that contains the username value.

Default: X-OpenAM-Username

Password Header name

Enter the name of the header that contains the password value.

Default: X-OpenAM-Password

Allow without referer

If enabled, the node accepts incoming requests that do not contain a Referer HTTP header. If a Referer HTTP header is present, the value is not checked.

If disabled, a Referer HTTP header must be present in the incoming request, and the value must appear in the Referer whitelist property.

Default: Enabled

Referer whitelist

Specify a list of URLs allowed in the Referer HTTP header of incoming requests. Incoming requests containing a Referer HTTP header value not specified in the whitelist causes tree evaluation to continue along the No Credentials outcome path.

Note

You must disable the Allow without referer property for the Referer whitelist property to take effect.

Example:

Figure 2.15. Example Tree With Zero Page Login Node
Example tree showing Zero Page Login node usage.

2.2.2. Configuring Authentication Webhooks

This section covers creating webhooks, which are used to send HTTP POST calls to a server with contextual information about an authentication session when a predefined event occurs, for example, logging out.

Webhooks are used from within authentication trees, by the following nodes:

Procedure 2.2. To Create an Authentication Webhook

Perform the following steps to create an authentication webhook for use within an authentication tree:

  1. Log in to the AM console as an administrator, for example, amadmin.

  2. Navigate to Realms > Realm Name > Authentication > Webhooks.

    • To create a new webhook, select Create Webhook, specify a Webhook Name, and then select Create.

    • To edit an existing webhook, select the name of the webhook.

    A screen similar to the following appears:

  3. Complete the fields as required:

    Url

    Specifies the URL to which the HTTP POST is sent when the event occurs.

    Body

    Specifies the body of the HTTP POST. You can send different formats by also setting the correct Content-Type header in the Header property, for example:

    • Form Data. Enter the body value in the format parameter=value&parameter2=value2, and set a Content-Type header of application/x-www-form-urlencoded.

    • JSON Data. Enter the body value in the format {"parameter":"value","parameter2":"value2"}, and set a Content-Type header of application/json.

    Headers

    Specifies any HTTP headers to add to the POST.

    To add a header, enter the name of the header in the Key field, and the value, and then click the Add button ().

    To remove a header, select the Delete button ().

    Each of the fields in a webhook supports variables for retrieving values from the user's session after successfully authenticating. Specify a variable in the following format:

    ${variable_name}

    Any custom properties added to the session using the Set Session Properties Node can be accessed by using a variable, as well as the following session properties:

    AMCtxId
    amlbcookie
    authInstant
    AuthLevel
    CharSet
    clientType
    FullLoginURL
    Host
    HostName
    IndexType
    Locale
    Organization
    Principal
    Principals
    Service
    successURL
    sun.am.UniversalIdentifier
    UserId
    UserProfile
    UserToken
    webhooks

    The following figure shows an example webhook, using variable substitutions:

    Warning

    Specifying a variable that is not present in the user's session places the literal variable text in to the HTTP POST, for example user=${UserId}, rather than user=demo.

2.3. Configuring Authentication Chains and Modules

AM provides several authentication modules and chains, the most important being the following:

  • The Amster authentication module and amsterService authentication chain, used by Amster clients.

  • The DataStore authentication module and ldapService authentication chain, configured for all users in new installations.

To configure authentication modules and chains, see the following sections:

Section 2.3.1, "Configuring Authentication Modules"
Section 2.3.2, "Configuring Authentication Chains"

2.3.1. Configuring Authentication Modules

The AM console provides two places where you can configure authentication modules:

  1. Under Configure > Authentication, you configure default properties for global authentication modules.

  2. 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 instead of the LDAP 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 to send the password during authentication.

2.3.1.1. Active Directory Authentication Module

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

For detailed information about this module's configuration properties, see Section 11.2.1, "Active Directory Module Properties".

2.3.1.2. Adaptive Risk Authentication Module

The Adaptive Risk module is designed to assess risk during authentication, so that AM 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:

Figure 2.16. Adaptive Risk Module in an Authentication Chain
Including the Adaptive Risk module in an authentication chain

In the example authentication chain shown, AM has users authenticate first using the LDAP module providing a user ID and password combination. Upon success, AM 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 AM finishes authentication processing without requiring further credentials. Otherwise, the Adaptive Risk module evaluates the score to be above the risk threshold, and returns failure. AM 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, AM performs the save as post-authentication processing, only after the entire authentication chain returns success. You must set up AM to save the data as part of post-authentication processing by editing the authentication chain to add org.forgerock.openam.authentication.modules.adaptive.AdaptivePostAuthenticationPlugin to the list of post-authentication plugins.

When the Adaptive Risk module relies on the client IP address, and AM 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 AM to consume and forward the header as necessary. For details, see Section 2.2.4, "Handling HTTP Request Headers" in the Installation Guide.

For detailed information about this module's configuration properties, see Section 11.2.2, "Adaptive Risk Authentication Module Properties".

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

For detailed information about this module's configuration properties, see Section 11.2.3, "Anonymous Authentication Module Properties".

2.3.1.4. 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 used to manage authentication by applications. If all certificates are signed by a recognized Certificate Authority (CA), then you might not need additional configuration. If you need to look up public keys of AM 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:

  • How to access the directory service.

  • How to look up the certificates and CRLs, based on the fields in the certificates that AM clients present to authenticate.

Access to the LDAP server and how to search for users is similar to LDAP module configuration as in Section 2.3.1.15, "LDAP Authentication Module". The primary difference is that, unlike for LDAP configuration, AM 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.

For detailed information about this module's configuration properties, see Section 11.2.4, "Certificate Authentication Module Properties".

2.3.1.5. Data Store Authentication Module

The Data Store authentication module allows a login using the identity repository of the realm to authenticate users. 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.

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.

For detailed information about this module's configuration properties, see Section 11.2.5, "Data Store Authentication Module Properties".

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

For detailed information about this module's configuration properties, see Section 11.2.6, "Device ID (Match) Authentication Module Properties".

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

  • User agents associated with the configuration of a web browser

  • Installed fonts

  • Plugins installed for the web browser

  • Resolution and color depth associated with a display

  • Timezone or geolocation of a device

For example, when a user who typically authenticates to AM 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 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 themselves using two-factor authentication.

Important

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

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

Caution

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

The Device ID (Match) module 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:

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

  2. 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 whether the client device successfully "matches" the stored profile. If a match is successful, AM 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.

  3. HOTP - Requisite. If the user's device does not match a stored profile, AM 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 Section 2.3.1.12, "HOTP Authentication Module".

  4. 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, AM 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, AM 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 Section 2.3.1.7, "Device ID (Save) Module".

    Note

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

Procedure 2.3. To Configure the Device ID (Match) Authentication Module
  1. Log into the AM console as an administrator.

  2. On the Realms page, click the realm from which you want to work.

  3. Click Authentication > Modules.

  4. To add the Device ID (Match) module, do the following substeps:

    1. Click Add Module.

    2. In the Module Name box, enter Device-ID-Match.

    3. In the Type box, select Device Id (Match), and then click Create.

    4. Click Save Changes.

      Figure 2.17. Device ID (Match) Module
      Device ID (Match)

  5. To make adjustments to the default scripts, click Scripts drop-down list, and then click Device Id (Match) - Client Side.

  6. 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 Section B.3, "Managing Scripts".

Procedure 2.4. To Configure an Authentication Chain With a Device ID (Match) Authentication Module
  1. Log into the AM console as an administrator.

  2. On the Realms page, click the realm from which you want to work.

  3. Click Authentication > Chains.

  4. On the Authentication Chains page, do the following steps:

    1. Click Add Chain. In the Chain Name box, enter a descriptive label for your authentication chain, and then click Create.

    2. Click Add Module.

    3. On the New Module dialog, select the authentication module, select the criteria, and then click Ok to save your changes. Repeat the last two steps to enter each module to your chain.

      For example, you can enter the following modules and criteria:

      Table 2.3. Device ID Chain
      ModuleCriteria
      DataStoreREQUISITE
      Device-ID-MatchSUFFICIENT
      HOTPREQUISITE
      Device-ID-SaveREQUIRED

      It is assumed that you have added the Device Id (Match) and Device Id (Save) modules. If you have not added these modules, see Procedure 2.3, "To Configure the Device ID (Match) Authentication Module" and Procedure 2.5, "To Configure the Device ID (Save) Authentication Module".

  5. Review your authentication chain, and then click Save Changes.

2.3.1.6.1. What the User Sees During Authentication

When the user logs on to the AM console, AM 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, AM 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, AM 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", AM prompts the user to enter a descriptive name for the trusted device.

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

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

For detailed information about this module's configuration properties, see Section 11.2.7, "Device ID (Save) Authentication Module Properties".

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.

Procedure 2.5. To Configure the Device ID (Save) Authentication Module
  1. Log into the AM console as an administrator.

  2. Click the realm from which you want to work.

  3. Click Authentication > Modules.

  4. To add the Device ID (Save) module, click Add Module.

  5. In the Module Name box, enter Device-ID-Save.

  6. In the Type box, select Device Id (Save), and then click Create.

  7. To configure the Device-Id (Save) module, do the following:

    1. Click the Automatically store new profiles checkbox. If this box is left unchecked, the user will be prompted to give consent to store new profiles.

    2. In the Maximum stored profile quantity box, enter the max number of stored profiles. Any profile that exceeds this number will not be stored.

    3. In the Authentication Level box, enter a number corresponding to the authentication level of the module.

    4. Click Save Changes.

      Figure 2.18. Device ID (Save) Module
      Device ID (Save)

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

For detailed information about this module's configuration properties, see Section 11.2.8, "Federation Authentication Module Properties".

2.3.1.9. 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 AM, see Chapter 4, "Implementing Multi-Factor Authentication".

For detailed information about this module's configuration properties, see Section 11.2.10, "ForgeRock Authenticator (OATH) Authentication Module Properties".

Note

AM 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 AM 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 Section 1.7.2, "Differences Among Authentication Modules That Support HOTP" for more information.

2.3.1.10. 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 AM, see Chapter 4, "Implementing Multi-Factor Authentication".

For detailed information about this module's configuration properties, see Section 11.2.11, "ForgeRock Authenticator (Push) Authentication Module Properties".

2.3.1.11. 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 AM, see Section 4.4, "Managing Devices for Multi-Factor Authentication".

For detailed information about this module's configuration properties, see Section 11.2.12, "ForgeRock Authenticator (Push) Registration Authentication Module Properties".

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

For detailed information about this module's configuration properties, see Section 11.2.13, "HOTP Authentication Module Properties".

Note

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

2.3.1.13. HTTP Basic Authentication Module

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

For detailed information about this module's configuration properties, see Section 11.2.14, "HTTP Basic Authentication Module Properties".

2.3.1.14. JDBC Authentication Module

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

For detailed information about this module's configuration properties, see Section 11.2.15, "JDBC Authentication Module Properties".

2.3.1.15. LDAP Authentication Module

AM connects to directory servers using Lightweight Directory Access Protocol (LDAP). To build an easy-to-manage, high-performance, pure Java directory service, try ForgeRock Directory Services.

For detailed information about this module's configuration properties, see Section 11.2.16, "LDAP Authentication Module Properties".

2.3.1.16. Legacy OAuth 2.0/OpenID Connect Authentication Module

Note

Use of this authentication module is deprecated. Use the replacements instead, as described in Section 2.3.1.26, "Social Authentication Modules"

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

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, AM uses the SMTP settings from the configuration for the OAuth 2.0/OpenID Connect authentication module.

For detailed information about this module's configuration properties, see Section 11.2.17, "Legacy OAuth 2.0/OpenID Connect Authentication Module Properties".

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

For detailed information about this module's configuration properties, see Section 11.2.18, "MSISDN Authentication Module Properties".

2.3.1.18. 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 AM 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. AM 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 AM 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 AM. 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 AM to match their device. See Section 4.4.7, "Resetting 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 AM, 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.

For detailed information about this module's configuration properties, see Section 11.2.19, "OATH Authentication Module Properties".

Note

AM 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 AM 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 Section 1.7.2, "Differences Among Authentication Modules That Support HOTP" for more information.

2.3.1.19. OpenID Connect id_token bearer Module

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

Note

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

To provision AM as an OpenID Connect client, you should instead configure an OAuth 2.0 or OpenID Connect social auth module. AM also provides a wizard to configure an OpenID Connect module that will authenticate against an OpenID Connect 1.0 provider. For more information, see Section 3.2, "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 AM 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 AM user.

You configure the OpenID Connect id_token bearer module to specify how AM 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 AM user profile.

Example 2.1. OpenID Connect id_token Bearer Example

The OpenID Connect id_token bearer module configuration must match the claims returned in the id_token JWT used to authenticate.

Before configuring the module, use an OpenID Connect client to obtain an id_token. Decode the id_token value to see the claims in the middle portion of the JWT. The claims in the decoded id_token look something like the following example, which was obtained at Google's OAuth 2.0 Playground:

{
      azp: "azp_id.apps.googleusercontent.com",
      aud: "aud_id.apps.googleusercontent.com",
      sub: "subject_id",
      at_hash: "access_token_hash",
      iss: "https://accounts.google.com",
      iat: 1505814261,
      exp: 1505817861,
      name: "Google User",
      picture: "https://lh5.googleusercontent.com/***/photo.jpg",
      given_name: "Google",
      family_name: "User",
      locale: "en"
      }

The azp, aud, and iss values are literally reused in the module configuration. Also notice that, in this example, name is mapped to cn for user accounts in the identity repository. The following figure shows an example configuration for this id_token format.

Figure 2.19. Sample OpenID Connect id_token Bearer Module Configuration
OpenID Connect id_token Bearer Module Configuration

The following example command demonstrates a REST call that authenticates the user using the module:

$ curl \
--request POST \
--header "Content-Type: application/json" \
--header "Accept-API-Version: resource=2.0, protocol=1.0" \
--header "oidc_id_token: eyJ...ifQ.eyJ...In0.BT1...iZA" \
https://openam.example.com:8443/openam/json/realms/root/authenticate?authIndexType=module&authIndexValue=OIDCBearer
{
    "tokenId": "nIq...AA*",
    "successUrl": "/openam/console",
    "realm": "/"
}

Notice that the id_token value, abbreviated as eyJ...ifQ.eyJ...In0.BT1...iZA, is the value of the oidc_id_token header as seen in the configuration. The request targets a module named OIDCBearer as specified by the authIndexType and authIndexValue parameters. For detailed information about the authentication REST API, see Section A.6, "Authentication and Logout".


For detailed information about this module's configuration properties, see Section 11.2.20, "OpenID Connect id_token bearer Authentication Module Properties".

2.3.1.21. RADIUS Authentication Module

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

For detailed information about this module's configuration properties, see Section 11.2.22, "RADIUS Authentication Module Properties".

2.3.1.22. SAE Authentication Module

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

For detailed information about this module's configuration properties, see Section 11.2.23, "SAE Authentication Module Properties".

2.3.1.23. SAML2 Authentication Module

The SAML2 authentication module lets administrators integrate SAML v2.0 single sign-on and single logout into an AM 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 Section 2.4.2.3, "Implementing SAML v2.0 Single Sign-On in Integrated Mode" in the SAML v2.0 Guide and make sure that you have made any required changes to your service provider configuration.

For detailed information about this module's configuration properties, see Section 11.2.24, "SAML2 Authentication Module Properties".

2.3.1.24. Scripted Authentication Module

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 AM 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 can run, 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 AM configuration data. This makes it easy to update a script on one AM server, and then to allow replication to copy it to other servers. You can manage the scripts through the AM 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 Section 10.2.2, "Using Server-side Authentication Scripts in Authentication Modules".

For detailed information about this module's configuration properties, see Section 11.2.25, "Scripted Authentication Module Properties".

2.3.1.25. SecurID Authentication Module

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

Important

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

For detailed information about this module's configuration properties, see Section 11.2.26, "SecurID Authentication Module Properties".

2.3.1.26. Social Authentication Modules

The social authentication modules let AM authenticate clients of OAuth 2.0 or OpenID Connect 1.0 resource servers. References in this section are to RFC 6749, The OAuth 2.0 Authorization Framework.

AM provides pre-configured authentication modules for the following social identity providers:

  • Instagram

  • VKontakte

  • WeChat

AM provides two authentication modules for the WeChat social identity provider. The Social Auth WeChat authentication module implements a login flow that requires the user to scan an on-screen QR code with the WeChat app. The Social Auth WeChat Mobile authentication module implements an alternative login flow for users authenticating on their mobile device, who would not be able to scan a QR code displayed on the mobile device's screen.

AM provides two generic authentication modules, one for OAuth 2.0, and another for OpenID Connect 1.0, for authenticating users of standards-compliant social identity providers, for example Facebook and Google.

Tip

A wizard for configuring common social authentication providers, such as Facebook, Google, and VKontakte, is available by navigating to Realms > Realm Name > Dashboard > Configure Social Authentication. For more information, see Section 3.1, "Configuring Pre-Populated Social Authentication Providers".

If the social authentication module is configured to create an account when none exists, then you must provide valid SMTP settings in the Email tab. The social identity provider must also provide the user's email address. As part of account creation, the social authentication module sends the resource owner an email with an account activation code. To send email, AM uses the SMTP settings from the Email tab of the configuration of the social authentication module.

For detailed information about the social authentication module's configuration properties, see the following sections:

2.3.1.27. Windows Desktop SSO Authentication Module

The Windows Desktop SSO module uses Kerberos authentication. The user presents a Kerberos token to AM 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 AM 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.

For detailed information about this module's configuration properties, see Section 11.2.33, "Windows Desktop SSO Authentication Module Properties".

Warning

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

2.3.1.28. Windows NT Authentication Module

The Windows NT module lets AM authenticate against a Microsoft Windows NT server.

This module requires that you install a Samba client in a bin directory under the AM configuration directory, such as $HOME/openam/openam/bin.

For detailed information about this module's configuration properties, see Section 11.2.34, "Windows NT Authentication Module Properties".

2.3.2. Configuring Authentication Chains

Once you have configured authentication modules and added the modules to the list of module instances, you can configure authentication chains. Authentication chains let you handle cases where alternate modules or credentials are needed. If you need modules in the chain to share user credentials, then set options for the module.

Tip

AM 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 Chapter 3, "Implementing Social Authentication".

Procedure 2.6. To Create an Authentication Chain
  1. On the Realms page of the AM console, click the realm for which to create the authentication chain.

  2. On the Realm Overview page, click Authentication in the left-hand menu, and then click Chains.

  3. On the Authentication Chains page, click Add Chain. Enter new chain name, and then click Create.

  4. On the New Module dialog, select the authentication module in the chain, and then assign appropriate criteria (Optional, Required, Requisite, Sufficient) as described in Section 1.4, "About Authentication Modules and Chains". You can also configure where AM redirects the user upon successful and failed authentication, and plug in your post-authentication processing classes as necessary.

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

    Note

    OATH and OTP codes are never added to the shared state, and cannot be shared between other modules in the chain.

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

    Figure 2.21. Authentication Chain First Module
    Configuring the first module in an authentication chain

    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.

    Figure 2.22. Authentication Chain Second Module
    Configuring the second module in an authentication chain

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

2.3.3. Implementing Post-Authentication Plugins

Post-authentication plugins (PAP) let you include custom processing at the end of the authentication process and when users log out of AM.

In the AM console, you add post-authentication plugins to an authentication chain. Navigate to Realms > Realm Name > Authentication > Chains > Auth Chain Name > Settings > Post Authentication Processing Class > Class Name.

See Section 10.2.3, "Creating Post-Authentication Plugins for Chains" for more information about post authentication plugins.

Standard Post-Authentication Plugins

AM provides some post-authentication plugins as part of the standard product delivery.

Class name: org.forgerock.openam.authentication.modules.adaptive.AdaptivePostAuthenticationPlugin

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

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.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 AM. It makes use of the JASPI JwtSession module to create and verify the persistent cookie.

Class name: com.sun.identity.authentication.spi.ReplayPasswd[4]

Password replay post-authentication plugin class that uses a DES/ECB/NoPadding encryption algorithm. This class is deprecated in favor of the com.sun.identity.authentication.spi.JwtReplayPassword class.

The plugin encrypts the password captured by AM during the authentication process and stores it in a session property. IG or a web agent looks up for the property, decrypts it, and replays the password into legacy applications.

To configure password replay for AM and IG, see the ForgeRock Identity Gateway Gateway Guide.

Class name: com.sun.identity.authentication.spi.JwtReplayPassword[4]

Password replay post-authentication plugin class that uses a JWT-based AES A128CBC-HS256 encryption algorithm.

The plugin encrypts the password captured by AM during the authentication process and stores it in a session property. IG looks up for the property, decrypts it, and replays the password into legacy applications.

Only IG 6 or later is supported.

To configure password replay for AM and IG, see the ForgeRock Identity Gateway Gateway Guide.

If necessary, you can also write your own custom post-authentication plugin as described in Section 10.2.3, "Creating Post-Authentication Plugins for Chains".

2.4. Configuring the Default Authentication Tree or Chain

By default, AM configures a default authentication chain, ldapService, which uses the DataStore module for authentication. This default authentication chain is configured for both administrators and non-administrators out-of-the-box after installation.

Warning

Special care must be given when setting your default authentication tree or chain.

If you leave the default authentication to the ldapService chain, the user can still post their username and password into the authentication endpoint to retrieve a session, regardless of the services configured for authentication.

For example, consider a deployment where you disable module-based authentication and keep the default authentication chain to the out-of-the-box ldapStore authentication chain using DataStore module. If you have set up two factor authentication for your users, your users can still access their accounts without performing the correct two factor authentication chain login sequence by using the default ldapService chain.

When you set the default authentication tree or chain, make sure it is set to your most secure tree or chain once you are ready to go to production and not left to the default ldapService chain.

Procedure 2.7. To Set the Default Authentication Tree or Chain
  1. Before you select the default tree or chain for users, and especially for administrators, test the authentication tree or chain first.

    When making a request to the XUI, specify the realm or realm alias as the value of a realm parameter in the query string, or the DNS alias in the domain component of the URL. If you do not use a realm alias, then you must specify the entire hierarchy of the realm, starting at the top-level realm. For example https://openam.example.com:8443/openam/XUI/?realm=/customers/europe#login/.

    For example, to test an authentication chain named NewChain in a subrealm called subrealm, the URL would be: http://openam.example.com:8080/openam/XUI/?realm=/subrealm#login&service=NewChain. If you cannot log in, then go back and fix the authentication chain's configuration before making it the default.

  2. Navigate to Realms > Realm Name > Authentication > Settings > Core.

  3. Adjust the Administrator Authentication Configuration drop-down to the required tree or chain. Administrative users, such as amAdmin, use this tree or chain to log in.

    By default, amAdmin can log in at /openam/XUI/#Login. You can change the URL for your deployment.

  4. Adjust the Organization Authentication Configuration drop-down to the required tree or chain. Non-administrative users use this tree or chain to log in.

  5. Save your work.



[4] Only one password replay post-authentication plugin class can be active for a given AM deployment.

Chapter 3. Implementing Social Authentication

Social authentication refers to AM's ability to delegate authentication through third-party identity providers, such as Facebook and Google, and other third-party providers.

AM allows delegation of authentication by providing provider-specific, and also generic OAuth 2.0 and OpenID Connect 1.0 authentication modules. For background information, see Section 1.6, "About Social Authentication".

Note

To allow AM to contact internet services through a proxy, see Section 1.1.2.4, "Settings for Configuring a JVM Proxy" in the Installation Guide.

This chapter explains the server configuration required to implement social authentication in AM:

Section 3.1, "Configuring Pre-Populated Social Authentication Providers"
Section 3.2, "Configuring Custom Social Authentication Providers"
Section 3.3, "Configuring the Social Authentication Implementations Service"

3.1. Configuring Pre-Populated Social Authentication Providers

AM provides wizards to quickly enable authentication with Facebook, Google, and VKontakte. 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

Note

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.

VKontakte

VKontakte Developers - My apps

Procedure 3.1. 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:

  1. 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 VKontakte Authentication.

  2. On the configure third party authentication page:

    1. Select the realm in which to enable social authentication.

    2. Enter the Client ID obtained from the third party authentication provider.

    3. Enter the Client Secret obtained from the third party authentication provider, and repeat it in the Confirm Client Secret field.

    4. Leave the default Redirect URL, unless you are using an external server as a proxy.

    5. Click Create.

    Figure 3.1. The Configure Google Authentication Wizard
    The Configure Google Authentication wizard.

    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 Section 2.3.1, "Configuring Authentication Modules", Section 2.3.2, "Configuring Authentication Chains", and Section 3.3, "Configuring the Social Authentication Implementations Service".

3.1.1. Integrating Social Authentication with Identity Management

The wizards configure the settings for logging in to AM using social identity providers such as Google, Facebook, and VKontakte.

To use AM social authentication as part of an IDM deployment, some additional configuration of the created authentication modules is required.

Procedure 3.2. To Integrate Social Authentication with Identity Management

After using the social authentication wizard, perform the following additional steps to configure AM to work with an IDM deployment:

  1. When using Google as the social identity provider, in the AM console navigate to Realms > Realm Name > Authentication > Modules > GoogleSocialAuthentication.

    Modify the configuration as follows:

    1. Add sub=iplanet-am-user-alias-list to the Account Mapper Configuration property.

      The iplanet-am-user-alias-list property defines one or more aliases for mapping a user's multiple profiles.

    2. Add org.forgerock.openam.authentication.modules.common.mapping.JsonAttributeMapper|iplanet-am-user-alias-list|google- to the Attribute Mapper property.

    3. Add org.forgerock.openam.authentication.modules.oidc.JwtAttributeMapper|iplanet-am-user-alias-list|google- to the Attribute Mapper property.

  2. When using Facebook as the social identity provider, in the AM console navigate to Realms > Realm Name > Authentication > Modules > FacebookSocialAuthentication.

    Modify the configuration as follows:

    1. Add id=iplanet-am-user-alias-list to the Account Mapper Configuration property.

      The iplanet-am-user-alias-list property defines one or more aliases for mapping a user's multiple profiles.

    2. Add org.forgerock.openam.authentication.modules.common.mapping.JsonAttributeMapper|iplanet-am-user-alias-list|facebook- to the Attribute Mapper property.

  3. Enable the Create account if it does not exist property.

  4. Save your changes.

3.2. Configuring Custom Social Authentication Providers

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

Procedure 3.3. 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:

  1. Select Realms > Realm Name > Dashboard > Configure Social Authentication, and then click the Configure Other Authentication link.

  2. On the configure social authentication page:

    1. Select the realm in which to enable social authentication.

    2. Enter the OpenID Discovery URL obtained from the third party authentication provider.

    3. Enter a name for the provider in the Provider Name field. AM uses this as a label on the login page to identify the provider.

    4. Enter the URL of an image to be used on the login page in the Image URL field. AM places the image on the login page, to enable authentication with the provider.

    5. Enter the Client ID obtained from the third party authentication provider.

    6. Enter the Client Secret obtained from the third party authentication provider, and repeat it in the Confirm Client Secret field.

    7. Leave the default Redirect URL, unless you are using an external server as a proxy.

    8. Click Create.

    Figure 3.2. The Configure Social Authentication Wizard
    The Configure Social Authentication wizard.

    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 Section 2.3.1, "Configuring Authentication Modules", Section 2.3.2, "Configuring Authentication Chains", and Section 3.3, "Configuring the Social Authentication Implementations Service".

3.3. 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 social authentication modules.

To add a social authentication provider to the login screen, you must first configure a social authentication module, and an authentication chain that contains it:

Procedure 3.4. To Configure the Social Authentication Implementations Service

Once you have created an authentication chain containing a social authentication module, perform the following steps to add a logo for the authentication provider to the AM login screen:

  1. On the Realms page of the AM console, click the realm containing the authentication module and authentication chain to be added to the login screen.

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

  3. On the Social Authentication Implementations page:

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

      Note

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

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

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

    4. In the Enabled Implementations field, re-enter the Map Key used in the previous steps, and then click Add.

      Tip

      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.

    5. Click Save Changes.

    Figure 3.3. Configuring the Social Authentication Implementations service
    Configuring the Social Authentication Implementations service.

An icon now appears on the AM login screen, allowing users to authenticate with the third party authentication provider.

Chapter 4. Implementing Multi-Factor Authentication

Multi-factor authentication is a security process that requires users to provide more than one form of credentials when logging in or accessing a resource. A common multi-factor authentication scenario is for users to submit a user ID and password, and then submit a one-time password generated by an authenticator application on their mobile phone to access a resource.

This chapter covers how administrators implement and support multi-factor authentication, and how end users authenticate using multi-factor authentication. See the following sections:

Section 4.1, "Configuring Multi-Factor Authentication Service Settings"
Section 4.2, "Letting Users Opt Out of One-Time Password Authentication"
Section 4.3, "Creating Multi-Factor Authentication Chains"
Section 4.4, "Managing Devices for Multi-Factor Authentication"
Section 4.5, "Authenticating Using Multi-Factor Authentication"

For conceptual information about multi-factor authentication, see Section 1.7, "About Multi-Factor Authentication".

4.1. Configuring Multi-Factor Authentication Service Settings

AM 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 Section 2.2.7, "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 Section 2.2.8, "ForgeRock Authenticator (Push) Service" in the Reference.

Push Notification Service

Configures how AM 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 to set up AM Push Notification Service credentials in the ForgeRock Knowledge Base.

For detailed information about the available properties, see Section 2.2.19, "Push Notification Service" in the Reference.

To configure these services globally for an AM 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.

4.2. Letting Users Opt Out of One-Time Password Authentication

Letting users opt out of providing one-time passwords when they perform multi-factor authentication is an important implementation decision. The Two Factor Authentication Mandatory setting under Realms > Realm Name > Authentication > Settings > General configures whether users can opt out.

When the Two Factor Authentication Mandatory setting is enabled, users must provide a one-time password every time they authenticate to a chain that includes a ForgeRock Authenticator (OATH) authentication module. When the setting is disabled, the user can optionally skip one-time passwords.

By default, AM 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. AM does not provide an option to skip multi-factor authentication during the initial attempt at multi-factor authentication:

Initial screen in the multi-factor authentication process if two step verification is mandatory

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 Section 4.3.2, "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:

  1. The Data Store authentication module prompts the user to provide a user ID and password.

  2. The user provides a valid user ID and password.

  3. Data Store authentication passes, and authentication proceeds to the next module in the chain—the ForgeRock Authenticator (OATH) module.

  4. The ForgeRock Authenticator (OATH) authentication module determines that the user has opted out of providing one-time passwords.

  5. ForgeRock Authenticator (OATH) authentication passes. Because it is the last authentication module in the chain, AM 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:

  1. The Data Store authentication module prompts the user to provide a user ID and password.

  2. The user provides a valid user ID and password.

  3. Data Store authentication passes, and authentication proceeds to the next module in the chain—the ForgeRock Authenticator (OATH) module.

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

  5. The user obtains a one-time password from the authenticator app on their mobile phone.

  6. If the one-time password is valid, ForgeRock Authenticator (OATH) authentication passes. Because it is the last authentication module in the chain, AM considers authentication to have completed successfully. However, if the one-time password is not valid, ForgeRock Authenticator (OATH) authentication fails, and AM considers authentication to have failed.

4.3. Creating Multi-Factor Authentication Chains

The following procedures provide steps for creating authentication chains that implement multi-factor authentication.

4.3.1. Creating Authentication Chains for Push Authentication

Push authentication uses two separate authentication modules:

  • A module to register a device to receive push notifications called ForgeRock Authenticator (Push) Registration.

  • A module to perform the actual authentication itself, called ForgeRock Authenticator (Push).

You can insert both modules into a single chain to register devices and then authenticate with push notifications. See Procedure 4.1, "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 Procedure 4.2, "To Create an Authentication Chain for Push Registration and Passwordless Authentication".

For information on the potential limitations of passwordless authentication, see Section 1.7.4, "Limitations When Using Passwordless Push Authentication".

Procedure 4.1. 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:

  1. Log in to the AM console as an AM administrator, for example amadmin.

  2. Select the realm that will contain the authentication chain.

  3. Create a ForgeRock Authenticator (Push) Registration authentication module as follows:

    1. Select Authentication > Modules, and then click Add Module.

      The New Module page appears.

    2. Fill in fields in the Create New Module dialog box as follows:

      • Name: Specify a module name of your choosing, for example push-reg.

      • Type: Select ForgeRock Authenticator (Push) Registration.

    3. Click Create.

      A page that lets you configure the authentication module appears.

    4. Configure the module to meet your organization's requirements.

      For more information about the authentication module's configuration settings, see Section 2.3.1.11, "ForgeRock Authenticator (Push) Registration Authentication Module".

  4. Create a ForgeRock Authenticator (Push) authentication module as follows:

    1. Select Authentication > Modules, and then click Add Module.

      The New Module page appears.

    2. Fill in fields in the Create New Module dialog box as follows:

      • Name: Specify a module name of your choosing, for example push-authn.

      • Type: Select ForgeRock Authenticator (Push).

    3. Click Create.

      A page that lets you configure the authentication module appears.

    4. Configure the module to meet your organization's requirements.

      For more information about the authentication module's configuration settings, see Section 2.3.1.10, "ForgeRock Authenticator (Push) Authentication Module".

  5. Create the authentication chain as follows:

    1. Select Authentication > Chains, and then click Add Chain.

      The Add Chain page appears.

    2. Specify a name of your choosing, for example myPushAuthChain, and then click Create.

      A page appears with the Edit Chain tab selected.

    3. Add the Data Store authentication module to the authentication chain as follows:

      1. Click Add a Module.

        The New Module dialog box appears.

      2. Fill in the New Module dialog box, specifying the Data Store authentication module. For this example, specify the Requisite flag.

      3. Click OK.

        The graphic showing your authentication chain now includes a Data Store authentication module.

    4. Add the ForgeRock Authenticator (Push) Registration authentication module to the authentication chain as follows:

      1. Click Add a Module.

        The New Module dialog box appears.

      2. Fill in the New Module dialog box, specifying the ForgeRock Authenticator (Push) Registration authentication module that you just created. For this example, specify the Requisite flag.

      3. Click OK.

        The graphic showing your authentication chain now includes a Data Store, and a ForgeRock Authenticator (Push) Registration authentication module.

    5. Add the ForgeRock Authenticator (Push) authentication module to the authentication chain as follows:

      1. Click Add a Module.

        The New Module dialog box appears.

      2. Fill in the New Module dialog box, specifying the ForgeRock Authenticator (Push) authentication module that you created. For this example, specify the Required flag.

      3. Click OK.

        The graphic showing your authentication chain now includes a Data Store, a ForgeRock Authenticator (Push) Registration, and a ForgeRock Authenticator (Push) authentication module.

      An authentication chain setup for Push authentication.
    6. Click Save Changes to save the authentication chain.

  6. Test your authentication chain as follows:

    1. Navigate to a URL similar to the following: http://openam.example.com:8080/openam/XUI/?realm=/#login/&service=myPushAuthChain

      A login screen prompting you to enter your user ID and password appears.

    2. Follow the procedure described in Procedure 4.9, "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 AM displays the user profile page.

Procedure 4.2. 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 Procedure 4.1, "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:

  1. Log in to the AM console as an AM administrator, for example amadmin.

  2. Select the realm that will contain the authentication chain.

  3. Create a ForgeRock Authenticator (Push) authentication module as follows:

    1. Select Authentication > Modules, and then click Add Module.

      The New Module page appears.

    2. Fill in fields in the Create New Module dialog box as follows:

      • Name: Specify a module name of your choosing, for example push-authn.

      • Type: Select ForgeRock Authenticator (Push).

    3. Click Create.

      A page that lets you configure the authentication module appears.

    4. Configure the module to meet your organization's requirements.

      For more information about the authentication module's configuration settings, see Section 2.3.1.10, "ForgeRock Authenticator (Push) Authentication Module".

  4. Create the authentication chain as follows:

    1. Select Authentication > Chains, and then click Add Chain.

      The Add Chain page appears.

    2. Specify a name of your choosing, for example myPasswordlessAuthChain, and then click Create.

      A page appears with the Edit Chain tab selected.

    3. Add the ForgeRock Authenticator (Push) authentication module to the authentication chain as follows:

      1. Click Add a Module.

        The New Module dialog box appears.

      2. Fill in the New Module dialog box, specifying the ForgeRock Authenticator (Push) authentication module that you created. For this example, specify the Requisite flag.

      3. Click OK.

        The graphic showing your authentication chain now includes a ForgeRock Authenticator (Push) authentication module.

      An authentication chain setup for passwordless push authentication.
    4. Click Save Changes to save the authentication chain.

  5. Test your authentication chain as follows:

    1. Navigate to a URL similar to the following: http://openam.example.com:8080/openam/XUI/?realm=/#login/&service=myPasswordlessAuthChain

      A login screen prompting you to enter your user ID appears.

    2. Follow the procedure described in Procedure 4.9, "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 AM displays the user profile page, without having to enter a password.

4.3.2. Creating Authentication Chains for One-Time Password Authentication

This section covers one-time password authentication.

Procedure 4.3. 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 Section 1.4, "About Authentication Modules and Chains" 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:

  1. Log in to the AM console as an AM administrator, for example amadmin.

  2. Select the realm that will contain the authentication chain.

  3. You can allow users to opt out of using OATH-based one-time passwords as follows:

    1. Select Authentication > Settings > General.

    2. Make sure that the Two Factor Authentication Mandatory is not enabled.

      See Section 11.1.5, "General" for details about this configuration setting.

    For information about how letting users skip multi-factor authentication impacts the behavior of authentication chains, see Section 4.2, "Letting Users Opt Out of One-Time Password Authentication".

  4. Create a ForgeRock Authenticator (OATH) authentication module as follows:

    1. Select Authentication > Modules, and then click Add Module.

      The New Module page appears.

    2. Fill in fields in the Create New Module dialog box as follows:

      • Name: Specify a module name of your choosing.

      • Type: Select ForgeRock Authenticator (OATH).

    3. Click Create.

      A page that lets you configure the authentication module appears.

    4. Configure the ForgeRock Authenticator authentication module to meet your organization's requirements.

      For more information about the authentication module's configuration settings, see Section 2.3.1.9, "ForgeRock Authenticator (OATH) Authentication Module".

  5. Create the authentication chain as follows:

    1. Select Authentication > Chains, and then click Add Chain.

      The Add Chain page appears.

    2. Specify a name of your choosing, for example myOathAuthChain, and then click Create.

      A page appears with the Edit Chain tab selected.

    3. Click Add a Module. Fill in fields in the New Module dialog box as follows:

      • Select Module: Select the existing Data Store module to use in this chain.

      • Select Criteria: Select a flag setting for the module in the authentication chain. For this example, specify the Requisite flag.

        See Section 1.4, "About Authentication Modules and Chains" for information about authentication module flag settings.

    4. Click OK.

      A graphic showing an authentication chain with a single Data Store module appears on the page.

    5. Add the ForgeRock Authenticator (OATH) authentication module to the authentication chain as follows:

      1. Click Add a Module.

        The New Module dialog box appears.

      2. Fill in the New Module dialog box, specifying the ForgeRock Authenticator (OATH) authentication module that you just created. For this example, specify the Requisite flag.

      3. Click OK.

        The graphic showing your authentication chain now includes the Data Store and ForgeRock Authenticator (OATH) authentication module.

      An authentication chain setup for OATH authentication.
    6. Click Save Changes to save the authentication chain.

  6. Test your authentication chain as follows:

    1. Navigate to a URL similar to the following: http://openam.example.com:8080/openam/XUI/?realm=/#login/&service=myOathAuthChain

      A login screen prompting you to enter your user ID and password appears.

    2. Follow the procedure described in Procedure 4.8, "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 AM displays the user profile page.

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

This section covers the following topics relating to devices used for multi-factor authentication:

Section 4.4.1, "Downloading the ForgeRock Authenticator App"
Section 4.4.2, "Registering a Device for Multi-Factor Authentication"
Section 4.4.3, "Accessing Your Recovery Codes"
Section 4.4.4, "Opting Out of One-Time Password Authentication"
Section 4.4.5, "Recovering After Replacing a Lost Device"
Section 4.4.6, "Recovering After a Device Becomes Out of Sync"
Section 4.4.7, "Resetting Registered Devices by using REST"

4.4.1. Downloading the ForgeRock Authenticator App

If you have not already done so, download and install the ForgeRock Authenticator app on your phone, so that you can perform multi-factor authentication.

The ForgeRock Authenticator app supports push authentication notifications and one-time passwords.

The app is available for both Android and iOS devices, and is free to download. Source code is also available:

4.4.2. Registering a Device for Multi-Factor Authentication

Registering a device with AM 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.

Procedure 4.4. To Register a Device for Multi-Factor Authentication
  1. When visiting a protected resource without having any registered devices for multi-factor authentication, AM requires that you register a device.

    Initial screens in a multi-factor authentication process. Push notification on the left, and OATH authentication on the right.

    To register your mobile phone with AM, click Register Device. A screen with a QR code appears:

    The device registration screens with QR code in the multi-factor authentication process. Push notification on the left, and one-time password (OATH) authentication on the right.
  2. Start the ForgeRock Authenticator app on the device to register, and then click the plus icon:

    ForgeRock Authenticator Setup Screen

    The screen on the device changes to an interface similar to your camera app.

  3. Point the camera at the QR code on the AM page and the ForgeRock Authenticator app will acquire the QR code and read the data encoded within.

    If you are logging in to AM 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.

    ForgeRock Authenticator scanning a QR code.
  4. 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):

    ForgeRock Authenticator with a registered account.

Your device is now registered. You will able to use it to perform multi-factor authentication.

Important

After registering a new device and successfully performing multi-factor authentication, you should obtain the recovery codes for the registered device and store them somewhere safe. See Section 4.4.3, "Accessing Your Recovery Codes".

4.4.3. Accessing Your Recovery Codes

After successful first-time authentication with multi-factor authentication, you should safeguard your ability to use multi-factor authentication in case you lose your phone. AM 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.

Procedure 4.5. To Access Your Recovery Codes

After registering a new device with AM, use the following steps to access your recovery codes:

  1. Log in to AM.

  2. Select Dashboard from the top-level menu.

  3. Locate the entry for the device type in the Authentication Devices section, click the context menu button, and then click Recovery Codes:

    Menu for Managing Phones Used for Multi-Factor Authentication.

    A list of recovery codes appears:

    Recovery Codes
  4. 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 AM if you lose your phone.

See Section 4.4.5, "Recovering After Replacing a Lost Device" for the procedure to authenticate to AM using a recovery code instead of performing multi-factor authentication.

4.4.4. Opting Out of One-Time Password Authentication

Unless the AM 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. [5] 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 AM.

The decision to opt out of using one-time passwords in AM 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:

Procedure 4.6. To Opt out or Opt in to Using One-Time Passwords
  1. Log in to AM.

  2. Select Dashboard from the top navigation bar.

  3. In the Authentication Devices section of the Dashboard page, click the context menu button, and then click Settings:

    Authentication Devices Menu
  4. Enable or disable the 2-Step Authentication option:

    2-Step Authentication Setting
  5. Click Save.

4.4.5. Recovering After Replacing a Lost Device

If you register a device with AM and then lose it, you must authenticate to AM using a recovery code, delete the lost device, and then register the new device. Follow these steps:

Procedure 4.7. To Register a New Device After Losing a Registered Device
  1. Log in to AM. 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 AM user profile.

  2. Select Dashboard from the top-level menu.

  3. Locate the entry for your phone in the Authentication Devices section, click the context menu button, and then click Delete:

    Context-Sensitive Menu for Managing Devices Used for Multi-Factor Authentication
  4. If you have not already done so, install the ForgeRock Authenticator app on your new phone. See Section 4.4.1, "Downloading the ForgeRock Authenticator App".

  5. Register your new device. See Section 4.4.2, "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 AM without a verification code require administrative support to reset their device profiles. See Section 4.4.7, "Resetting Registered Devices by using REST" for more information.

4.4.6. Recovering After a Device Becomes Out of Sync

If you repeatedly enter valid one-time passwords that appear to be valid passwords, but AM rejects the passwords as unauthorized, it is likely that your device has become out of sync with AM.

When a registered device becomes out of sync with AM, you must authenticate to AM using a recovery code, delete your device, and then re-register your device. You can do so by performing the steps in Procedure 4.7, "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 AM without a verification code require administrative support to reset their device profiles. See Section 4.4.7, "Resetting Registered Devices by using REST" for more information.

4.4.7. Resetting Registered Devices by using REST

As described in Section 4.4.5, "Recovering After Replacing a Lost Device", a user who has lost a mobile phone registered with AM 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.

AM provides a REST API to reset a device profile by deleting information about a user's registered device. Either the user or an administrator can call the REST API to reset a device profile. Device profile reset can be implemented as follows:

  • Administrators provide authenticated users with a self-service page that calls the REST API to let the users reset their own device profiles.

  • Administrators can call the REST API themselves to reset users' device profiles.

  • Administrators can call the REST API themselves to reset a device when the HOTP counter exceeds the HOTP threshold window and requires a reset.

    Note

    The reset action deletes the OATH device profile, which by default has a limit of one profile per device, and sets the Select to Enable Skip option to its default value of Not Set.

Reset OATH Devices

To reset a user's OATH device profile, perform an HTTP POST to the /users/user/devices/2fa/oath?_action=reset endpoint.

When making a REST API call, specify the realm in the path component of the endpoint. You must specify the entire hierarchy of the realm, starting at the top-level realm. Prefix each realm in the hierarchy with the realms/ keyword. For example /realms/root/realms/customers/realms/europe.

The following example resets the OATH devices of a user named myUser in a subrealm of the top-level realm called mySubrealm:

$ curl \
--request POST \
--header "Content-Type: application/json" \
--header "Accept-API-Version: resource=1.0" \
--header "iplanetDirectoryPro: AQIC5w...2NzEz*" \
--data '{}' \
https://openam.example.com:8443/openam/json/realms/root/realms/mySubrealm/users/myUser/devices/2fa/oath?_action=reset
{
    "result":true
}

Reset Push Devices

To reset push devices over REST, perform an HTTP POST to the /users/user/devices/push?_action=reset endpoint as follows:

$ curl \
--request POST \
--header "Content-Type: application/json" \
--header "Accept-API-Version: resource=1.0" \
--header "iplanetDirectoryPro: AQIC5w...2NzEz*" \
--data '{}' \
http://openam.example.com:8080/openam/json/realms/root/realms/mySubrealm/users/myUSER/devices/push?_action=reset"
{
    "result":true
}

4.5. Authenticating Using Multi-Factor Authentication

This section provides an example of how end users might authenticate with AM configured for multi-factor authentication. Use the following procedures to complete multi-factor authentication using the ForgeRock Authenticator:

Procedure 4.8, "To Perform Authentication using a One-Time Password"
Procedure 4.9, "To Perform Authentication using Push Notifications"
Procedure 4.8. To Perform Authentication using a One-Time Password

This example uses the authentication chain as created in Section 4.3.2, "Creating Authentication Chains for One-Time Password Authentication".

Because the first module in the authentication chain is a Data Store module, AM presents you with a page for entering your user ID and password. After you provide those credentials, AM verifies them. If your credentials are valid, AM proceeds to the ForgeRock Authenticator (OATH) authentication module.

On the ForgeRock Authenticator (OATH) screen, follow these steps to complete one-time password authentication:

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

    ForgeRock Authenticator after selecting an account
  2. In the One-time Password section, click the refresh icon. A one-time password is displayed:

    ForgeRock authenticator displaying a new one-time password
  3. On the ForgeRock Authenticator (OATH) page in AM, enter the one-time password that the authenticator app generated on your phone, and then click Submit:

    Screen in which to enter a one-time password

    AM will display the user's profile page.

Procedure 4.9. To Perform Authentication using Push Notifications

This example uses one of the authentication chains as created in Section 4.3.1, "Creating Authentication Chains for Push Authentication".

AM presents you with a page for entering only your user ID, or user ID and password. After you provide those credentials, AM verifies them. If your credentials are valid and the account has a device registered for push notifications, AM proceeds to the ForgeRock Authenticator (Push) authentication module, and a push notification is sent to the registered device.

Note

The device needs access to the Internet to receive push notifications, and the AM server must be able to receive responses from the device.

Follow these steps to complete authentication using push notifications:

  1. On your registered device, you will receive a push notification from AM. 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:

      Push notification when locked

      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:

      Push notification when unlocked and app closed

      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.

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

      The Push Notification Authentication Screen

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

      The Touch ID screen

      AM 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, AM will report that authentication has failed and return to the first screen in the chain.

      Note

      If you do not approve or deny the request on the registered device, the AM Push Authentication page will timeout and the authentication will fail. The timeout can be configured in the ForgeRock Authenticator (Push) authentication module settings. See Section 2.3.1.10, "ForgeRock Authenticator (Push) Authentication Module".



[5] For information about making the usage of one-time passwords mandatory in AM, see Section 4.2, "Letting Users Opt Out of One-Time Password Authentication".

Chapter 5. Implementing Account Lockout

Account lockout is a security mechanism that locks a user after repeated failed login attempts.

Most deployments implement the backend user store's password policy to control account lockout. If that is not an option to your deployment, you can configure account lockout.

Note

Account lockout settings only apply to authentication modules and chains.

To implement account lockout in authentication trees, use an Account lockout Node together with a Retry Limit Decision Node.

AM supports two different approaches to account lockout, where AM locks an account after repeated authentication failures—persistent lockout and memory lockout:

  • Persistent (physical) lockout sets the user account status to inactive in the user profile. For persistent lockout, AM 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.

  • 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 AM restarts.

Note

Failed login attempts during the transactional authorization flow do not increment account lockout counters. For more information on transactional authorization, see Chapter 3, "Implementing Transactional Authorization" in the Authorization Guide.

If login failures are stored in AM's memory, this may result in user accounts not being locked out even after multiple login failures. To avoid this issue, make sure to implement persistent lockout instead. For more information, see Section 5.1, "Configuring Account Lockout".

This chapter describes how to configure account lockout in AM.

5.1. Configuring Account Lockout

You configure account lockout by editing settings for the core authentication module. For details, see Section 2.1, "Setting up a Realm for Authentication".

Procedure 5.1. To Configure Account Lockout
  1. Access the settings in the AM console under Realms > Realm Name > Authentication > Settings > Account Lockout.

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

  3. (Optional) If you have configured CTS-based or client-based authentication sessions, ensure the Store Invalid Attempts in Data Store switch is enabled. Failure to do so may result in users not being locked out even after multiple login failures.

  4. To save account login failures to the Data Store, enable Store Invalid Attempts in Data Store. This step is necessary when using CTS-based or client-based authentication sessions.

  5. You can set up email notification upon lockout to an administrator if AM is configured to send mail. You can configure AM to send mail in Configure > Server Defaults > General > Mail Server.

  6. For persistent lockout, AM 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 AM servers accessing the user data store can also see the number.

Note

To unlock a user's account, find the user under Realms > Realm Name > Identities. Select the user you want to unlock, and set the user's User Status to Active. Save your changes.

Chapter 6. Implementing Sessions

Before you configure sessions in your environment, ensure you are familiar with the differences between sessions and authentication sessions, and where they are stored. For more information, see Section 1.9, "About Sessions".

You can configure authentication session storage location independently from session storage location. For example, you could configure the same realm for client-based authentication sessions and CTS-based sessions if it suits your environment.

To configure sessions, see the following sections:

Section 6.1, "Implementing CTS-Based Sessions"
Section 6.2, "Implementing Client-Based Sessions"
Section 6.3, "Implementing In-Memory Authentication Sessions"

To configure authentication session whitelisting, a feature that protects authentication sessions from replay attacks, see Section 6.4, "Implementing Authentication Session Whitelisting".

6.1. Implementing CTS-Based Sessions

By default, AM configures the CTS token store schema in the AM configuration store. Before configuring your AM deployment to use CTS-based sessions or authentication sessions, we recommend you install and configure an external CTS token store. For more information, see Chapter 3, "Implementing the Core Token Service" in the Installation Guide.

CTS-based sessions and authentication sessions benefit from configuring sticky load balancing. For more information, see Section 2.2.3, "Configuring Load Balancing for a Site" in the Installation Guide.

To configure CTS-based sessions and authentication sessions, see the following procedures:

To configure session quotas, a feature that lets you limit the amount of active sessions for a user, see Section 6.1.1, "Implementing Session Quotas".

Procedure 6.1. To Configure CTS-Based Authentication Sessions

Important

Configuring storage location for authentication sessions is only supported for authentication trees. Authentication chains always store authentication sessions in AM's memory. For more information, see Section 1.9.1, "Session Storage Location".

  1. Log in to the AM console as an administrative user, for example, amAdmin.

  2. Navigate to Realms > Realm Name > Authentication > Settings > Trees.

  3. From the Authentication session state management scheme drop-down list, select CTS.

  4. In the Max duration (minutes) field, enter the maximum life of the authentication session in minutes.

  5. Save your changes.

Procedure 6.2. To Configure CTS-Based Sessions
  1. Log in to the AM console as an administrative user, for example, amAdmin.

  2. Navigate to Realms > Realm Name > Authentication > Settings > General.

  3. Ensure the Use Client-based Sessions check box is not selected.

  4. Save your changes.

  5. Verify that AM creates a CTS-based session when non-administrative users authenticate to the realm. Perform the following steps:

    1. Authenticate to AM as a non-administrative user in the realm you enabled for CTS-based sessions.

    2. In a different browser, authenticate to AM as an administrative user, for example, amAdmin.

    3. Navigate to Realms > Realm Name > Sessions.

    4. Verify that a session is present for the non-administrative user.

6.1.1. Implementing Session Quotas

AM 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, AM takes the appropriate action.

AM's support for session quotas requires CTS-based sessions.

Procedure 6.3. 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:

  1. Log in to the AM console as an administrative user, for example, amAdmin.

  2. Navigate to Configure > Global Services > Sessions.

  3. Set Enable Quota Constraints to ON.

  4. 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 Section 10.3, "Customizing CTS-Based Session Quota Exhaustion Actions".

  5. Set Active User Sessions to the session quota.

    The default is 5 sessions.

  6. Save your work.

6.2. Implementing Client-Based Sessions

To configure client-based sessions and authentication sessions for a realm, see the following sections:

6.2.1. Planning for Client-Based Sessions

Before configuring your AM deployment to use client-based sessions or client-based authentication sessions, perform the following tasks:

  • Ensure the trust store used by AM has the necessary certificates installed:

    • A certificate is required for encrypting JWTs containing client-based sessions.

    • If you are using RS256 signing, then a certificate is required to sign JWTs. (HMAC signing uses a shared secret.)

    The same certificates must be stored on all servers participating in an AM site.

    For more information about managing certificates for AM, see Chapter 5, "Setting Up Keys and Keystores" in the Setup and Maintenance Guide.

  • Ensure that your users' browsers can accommodate larger session cookie sizes required by client-based sessions. For more information about session cookie sizes, see Section 1.9.2, "Session Cookies".

  • Ensure that the AM web container can accommodate an HTTP header that is 16K in size or greater. When using Apache Tomcat as the AM web container, configure the server.xml file's maxHttpHeaderSize property to 16384 or higher.

  • Ensure that your deployment does not require any of the capabilities specified in the list of limitations that apply to client-based sessions.

6.2.2. Configuring Client-Based Sessions

To configure client-based sessions and authentication sessions, see the following procedures:

Procedure 6.4. To Configure Client-Based Authentication Sessions

Important

Configuring storage location for authentication sessions is only supported for authentication trees. Authentication chains always store authentication sessions in AM's memory. For more information, see Section 1.9.1, "Session Storage Location".

  1. Log in to the AM console as an administrative user, for example, amAdmin.

  2. Navigate to Realms > Realm Name > Authentication > Settings > Trees.

  3. From the Authentication session state management scheme drop-down list, select JWT.

  4. In the Max duration (minutes) field, enter the maximum life of the authentication session in minutes.

  5. Save your changes.

Procedure 6.5. To Configure Client-Based Sessions
  1. Log in to the AM console as an administrative user, for example, amAdmin.

  2. Navigate to Realms > Realm Name > Authentication > Settings > General.

  3. Select the Use Client-based Sessions check box.

  4. Save your changes.

  5. Verify that AM creates a client-based session when non-administrative users authenticate to the realm. Perform the following steps:

    1. Authenticate to the AM console as the top-level administrator (by default, the amAdmin user). Note that sessions for the top-level administrator are always stored in the CTS token store.

    2. Navigate to Realms > Realm Name > Sessions.

    3. Verify that a session is present for the amAdmin user.

    4. In your browser, examine the AM cookie, named iPlanetDirectoryPro by default. Copy and paste the cookie's value into a text file and note its size.

    5. Start up a private browser session that will not have access to the iPlanetDirectoryPro cookie for the amAdmin user:

      • On Chrome, open an incognito window.

      • On Internet Explorer or Microsoft Edge, start InPrivate browsing.

      • On Firefox, open a new private window.

      • On Safari, open a new private window.

    6. Authenticate to AM as a non-administrative user in the realm for which you enabled client-based sessions. Be sure not to authenticate as the amAdmin user this time.

    7. In your browser, examine the iPlanetDirectoryPro cookie. Copy and paste the cookie's value into a second text file and note its size. The size of the client-based session cookie's value should be considerably larger than the size of the cookie used by the CTS-based session for the amAdmin user. If the cookie is not larger, you have not enabled client-based sessions correctly.

    8. Return to the original browser window in which the AM console appears.

    9. Refresh the window containing the Sessions page.

    10. Verify that a session still appears for the amAdmin user, but that no session appears for the non-administrative user in the realm with client-based sessions enabled.

6.2.4. Configuring Session Blacklisting

Session blacklisting ensures that users who have logged out of client-based sessions cannot achieve single sign-on without reauthenticating to AM. Session blacklisting does not apply to authentication sessions.

Perform the following steps to configure session blacklisting:

Procedure 6.9. To Configure Session Blacklisting
  1. Make sure that you deployed the Core Token Service during AM installation. The session blacklist is stored in the Core Token Service's token store.

  2. Navigate to Configure > Global Services, click Session, and then locate the Client-based Sessions section.

  3. Select the Enable Session Blacklisting option to enable session blacklisting for client-based sessions. When you configure one or more AM realms for client-based sessions, you should enable session blacklisting in order to track session logouts across multiple AM servers.

  4. Configure the Session Blacklist Cache Size property.

    AM maintains a cache of logged out client-based sessions. The cache size should be around the number of logouts expected in the maximum session time. Change the default value of 10,000 when the expected number of logouts during the maximum session time is an order of magnitude greater than 10,000. An underconfigured session blacklist cache causes AM to read blacklist entries from the Core Token Service store instead of obtaining them from cache, which results in a small performance degradation.

  5. Configure the Blacklist Poll Interval property.

    AM polls the Core Token Service for changes to logged out sessions if session blacklisting is enabled. By default, the polling interval is 60 seconds. The longer the polling interval, the more time a malicious user has to connect to other AM servers in a cluster and make use of a stolen session cookie. Shortening the polling interval improves the security for logged out sessions, but might incur a minimal decrease in overall AM performance due to increased network activity.

  6. Configure the Blacklist Purge Delay property.

    When session blacklisting is enabled, AM tracks each logged out session for the maximum session time plus the blacklist purge delay. For example, if a session has a maximum time of 120 minutes and the blacklist purge delay is one minute, then AM tracks the session for 121 minutes. Increase the blacklist purge delay if you expect system clock skews in a cluster of AM servers to be greater than one minute. There is no need to increase the blacklist purge delay for servers running a clock synchronization protocol, such as Network Time Protocol.

  7. Click Save.

For detailed information about Session Service configuration attributes, see the entries for Section 2.2.26, "Session" in the Reference.

6.2.5. Limitations When Using Client-Based Sessions

The following AM features are not supported in realms that use client-based sessions:

6.3. Implementing In-Memory Authentication Sessions

Authentication chains always store authentication sessions in AM's memory. Perform the steps in the following procedure only for realms that configure authentication trees:

Procedure 6.10. To Configure In-Memory Authentication Sessions
  1. Ensure you have configured AM for sticky load-balancing. For more information, see Section 2.2.3, "Configuring Load Balancing for a Site" in the Installation Guide.

  2. Log in to the AM console as an administrative user, for example, amAdmin.

  3. Navigate to Realms > Realm Name > Authentication > Settings > Trees.

  4. From the Authentication session state management scheme drop-down list, select In-Memory.

  5. In the Max duration (minutes) field, enter the maximum life of the authentication session in minutes.

  6. Save your changes.

6.4. Implementing Authentication Session Whitelisting

Enable authentication session whitelisting to protect authentication sessions from replay attacks.

When authentication session whitelisting is enabled, AM generates a key-value pair for each authentication session and stores it for the length of the authentication flow in the following ways:

  • For client-based authentication sessions, AM stores the key-value pair in the CTS token store.

  • For CTS-based authentication sessions, AM creates the key-value pair as a session property in the authentication session.

  • For in-memory sessions, AM creates the key-value pair as a session property in the authentication session.

Each time the authentication flow reaches an authentication node, AM modifies the value of the stored key-value pair and sends it to the user or client that it is authenticating. The next request to AM to continue the authentication flow must contain the key-value pair and must match the value expected by AM.

If the authenticating user or client cannot provide the key-value pair with the values AM expects, AM would not continue the authentication flow, therefore protecting the authentication flow against malicious users wanting to rewind the authentication flow to a previous node.

Perform the following steps to configure authentication session whitelisting:

Procedure 6.11. To Configure Authentication Session Whitelisting
  1. Navigate to Realms > Realm Name > Authentication > Settings > Trees.

  2. Select Enable whitelisting.

  3. Save your changes.

Chapter 7. Implementing Single Sign-On

Single sign-on (SSO) allows a user or an entity to access multiple independent services from a single login session. AM supports SSO on the domain level and across multiple domains using cross-domain single sign-on (CDSSO).

7.1. About HTTP Cookies

To understand how SSO works, you need to understand some key elements of the HTTP cookie, as described in RFC 6525, HTTP State Management Mechanism .

Within an HTTP cookie, you can store a single custom name=value pair, such as sessionid=value. Other custom names within a cookie are as follows:

Domain

Normally set to the full URL that was used to access the configurator. To work with multiple subdomains, the Domain should be set to a URL like Domain=server.example.net. This is also known as the cookie domain.

Path

The directory in the URL to which the cookie applies. If the Path =/openam, the cookie applies to the /openam subdirectory of the URL, and lower level directories, including openam/XUI.

Secure

If the Secure name is included, the cookie can be transferred only over HTTPS. When a request is made over HTTP, the cookie is not made available to the application.

HttpOnly

When the HttpOnly flag is included, that cookie will not be accessible through JavaScript. According to RFC 6265, the noted flag "instructs the user agent to omit the cookie when providing access to cookies via 'non-HTTP' APIs (for example, a web browser API that exposes cookies to scripts)."

For more information, see Section 7.1.1, "Configuring HttpOnly".

Expires

The lifetime of a cookie can be limited, with an Expires name configured with a time, based on UTC (GMT).

Warning

Do not take a shortcut with a top-level domain. Web browser clients today are designed to ignore cookies set to top-level domains including com, net, and co.uk. In addition, a cookie with a value like Domain= app1.example.net will not work for similar subdomains, such as app2.example.net.

7.1.1. Configuring HttpOnly

AM supports an HttpOnly flag, which is affixed to the Set-cookie HTTP response header transmitted from the server to the browser. The HttpOnly flag mitigates against cross-site scripting (XSS) vulnerabilities that can be exploited through JavaScript or other scripting languages.

When the HttpOnly flag is enabled:

  • AM sets the token as HttpOnly. For example, AM returns a Set-Cookie header upon successful authentication. When HttpOnly is enabled, the header will include an HttpOnly flag with the original token in the payload of the Set-Cookie header as shown in the following example:

    Set-Cookie: iPlanetDirectoryPro='AQIC5..*; Domain=example.com; Path=/; HttpOnly
    ...
    
  • When an invalid token is detected during the authentication process, the token is ignored and authentication continues. An additional Set-Cookie header is set to remove the invalid token from the client.

  • Upon logout, the session cookie on the client is cleared by the Set-Cookie header in the response. For example:

    Set-Cookie: iPlanetDirectoryPro=""; Expires=Thu, 01 Jan 1970 00:00:10 GMT; Path=/; Domain=example.com; HttpOnly
    Set-Cookie: amlbcookie=LOGOUT; Expires=Thu, 01 Jan 1970 00:00:10 GMT; Path=/; Domain=example.com
    ...
    
  • The User self-service auto login feature during the user registration process returns a Set-Cookie header in the response.

  • Session upgrade automatically occurs upon the current SSO token when the authentication flow is called again and the token was previously passed in.

Perform the following steps to configure the HttpOnly flag:

Procedure 7.1. To Configure the HttpOnly Flag
  1. Log into the AM console as an administrator.

  2. In the AM console, navigate to Configure > Server Defaults > Advanced.

  3. Set the value of the com.sun.identity.cookie.httponly property to true.

  4. Save your changes, and restart the AM instances.

7.2. Implementing Cross-Domain Single Sign-On

CDSSO provides SSO capabilities for AM servers and web or Java agents within a single domain or across domains in the same organization. For general information about how CDSSO works in AM, see Section 1.10.1, "Cross-Domain SSO".

Implementing CDSSO in AM requires a working web or Java agent 5 and little to none additional configuration:

Procedure 7.2. To configure CDSSO
  1. Install and configure an appropriate web or Java agent for your environment. For more information, see the ForgeRock Access Management Web Agents User Guide and the ForgeRock Access Management Java Agents User Guide.

  2. Make sure that the clocks on the servers where you run AM and agents are synchronized. This ensures the timestamps stored in the web or Java agent and AM logs are consistent.

  3. Navigate to Realms > Realm Name > Applications > Agents > Web / Java > Agent Name > SSO.

  4. (Optional) To protect the SSO token from network snooping:

    • For web agents, enable Cookie Security (com.sun.identity.agents.config.cookie.secure.

    • For Java agents, enable CDSSO Secure Enable (com.sun.identity.agents.config.cdsso.secure.enable).

  5. (Optional) If AM and the web or Java agent are configured in different DNS domains, add the agent domain to the CDSSO list:

    • For web agents, configure the agent domain in the Cookies Domain List property.

    • For Java agents, configure the agent domain in the CDSSO Domain List property (com.sun.identity.agents.config.cdsso.domain).

  6. (Optional) If necessary, update the Agent Root URL for CDSSO list on the Global tab page:

    1. Navigate to Realms > Realm Name > Applications > Agents > Web / Java > Agent Name > Global.

    2. Update the Agent Root URL for CDSSO list (sunIdentityServerDeviceKeyValue):

      • If the web or Java agent is on a server with virtual host names, add the virtual host URLs to the list.

      • If the web or Java agent is behind a load balancer, add the load balancer URL to the list.

  7. Protect your environment against cookie hijacking by configuring restricted tokens. See Section 7.2.1, "Protecting Against Cookie Hijacking".

7.3. Implementing Classic Single Domain and Cross-Domain SSO

This section contains procedures about configuring AM for legacy single domain and cross-domain SSO, for example, for web or Java agents earlier than 5.

The federation mechanism associated with SAML v2.0 can be used as an alternative to CDSSO for both Web and Java agents. While using SAML v2.0 adds complexity, it supports attribute mapping, which may be useful when the two domains are associated with data stores that use different attribute names. For details, see Section 2.4.3.3, "Using Web or Java Agents With Standalone Mode" in the SAML v2.0 Guide.

7.3.1. Implementing Classic Single Domain SSO

This section describes how to configure AM for classic SSO on a single domain, for example, when using web or Java agents earlier than version 5. For general information about how classic single domain SSO works in AM, see Section 1.10.4, "Classic Single Domain SSO".

The following procedure assumes that you know how to configure AM, the Apache Web server, and associated AM Apache agent.

Procedure 7.4. To Configure Classic Single Domain SSO
  1. Install and configure an appropriate web or Java agent of a version earlier than 5. For more information, see the ForgeRock Access Management Web Agents documentation and the ForgeRock Access Management Java Agents documentation.

  2. Ensure you have configured the SSO domain, for example, example.net, in AM:

    1. Navigate to Configure > Global Services > Platform.

    2. Check if your cookie domain is present in the Cookie Domains field. If not present, configure it, save your changes, and restart AM.

  3. Navigate to a URL protected by the agent, for example, http://app.example.net. You should be redirected to AM for authentication and returned back to the protected resource once AM verifies your credentials.

If you want to configure AM and an application on two different cookie domains, such as example.org and example.net, you need to set up cross-domain SSO (CDSSO). For more information, see Section 7.2, "Implementing Cross-Domain Single Sign-On".

7.3.2. Implementing Classic Cross-Domain SSO

This section describes how to configure AM for classic CDSSO, which concerns web or Java agents earlier than version 5. For general information about how classic CDSSO works in AM, see Section 1.10.3, "Classic Cross-Domain SSO".

Important

When implementing classic CDSSO, protect against session cookie hijacking by configuring restricted tokens. For more information, see Section 7.2.1, "Protecting Against Cookie Hijacking".

This section comprises several procedures:

Procedure 7.5. To Enable Classic CDSSO For Java Agents
  1. In the AM console, navigate to Realms > Realm Name > Applications > Agents > Java > Agent Name > SSO.

  2. Scroll down and enable Cross Domain SSO.

  3. Check that the CDSSO Redirect URI is set.

    Depending on where you deployed your Java agent application, the default may resemble /agentapp/sunwCDSSORedirectURI.

  4. Set the list of URLs for CDSSO Servlet URL to the Cross Domain Controller Servlet URLs of the servers the agent accesses, such as https://openam.example.com:8443/openam/cdcservlet.

    If the agent accesses AM through a load balancer, use the load balancer URLs, such as https://load-balancer.example.com:8443/openam/cdcservlet.

  5. Leave the CDSSO Clock Skew set to 0.

    Make sure instead that the clocks on the servers where you run AM and Java agents are synchronized.

  6. Set the list of URLs for CDSSO Trusted ID Provider to the Cross Domain Controller Servlet URLs of the AM servers the agent accesses, such as https://openam.example.com:8443/openam/cdcservlet.

    This list should include one CDC Servlet URL for every AM server the agent might access. You do not need to include site or load balancer URLs.

  7. (Optional) To protect the SSO token from network snooping, you can select CDSSO Secure Enable to mark the SSO token cookie as secure.

    If you select this, then the SSO token cookie can only be sent over a secure connection (HTTPS).

  8. Add the domains involved in CDSSO in the CDSSO Domain List.

  9. If necessary, update the Agent Root URL for CDSSO list on the Global tab page.

    If the Java agent is on a server with virtual host names, add the virtual host URLs to the list.

    If the Java agent is behind a load balancer, add the load balancer URL to the list.

  10. Save your work.

Procedure 7.6. To Enable Classic CDSSO For Web Agents
  1. In the AM console, navigate to Realms > Realm Name > Applications > Agents > Web > Agent Name > SSO.

  2. Enable Cross Domain SSO.

  3. Set the list of URLs for CDSSO Servlet URL to the Cross Domain Controller Servlet URLs of the servers the agent accesses, such as http://openam.example.com:8080/openam/cdcservlet.

    If the agent accesses AM through a load balancer, use the load balancer URLs, such as http://load-balancer.example.com:8080/openam/cdcservlet.

  4. Add the domains involved in CDSSO in the Cookies Domain List.

  5. If necessary, update the Agent Root URL for CDSSO list on the Global tab page.

    If the web agent is on a server with virtual host names, add the virtual host URLs to the list.

    If the web agent is behind a load balancer, add the load balancer URL to the list.

  6. Save your work.

Procedure 7.7. Accessing the Classic CDSSO Authentication Login

When a client makes an access request to some protected resource in a cross domain single sign-on deployment (CDSSO), the web or Java agent redirects the client to the Cross Domain Controller Servlet (CDCServlet) URL. The CDCServlet determines that the client needs to be authenticated and proxies the request to an authentication interface, typically at /XUI/#login, for example, http://openam.example.com:8080/openam/XUI/#login.

If your application requires access to a specific URL, use the loginURI parameter. For example, you can access the http://openam.example.com:8080/openam/XUI/#login URL navigating to http://openam.example.com:8080/openam/cdcservlet?loginURI=/XUI/#login.

If you have another authentication UI deployed at /openam/customLoginURI, you can access this URL by navigating to http://openam.example.com:8080/openam/cdcservlet?loginURI=/customLoginURI. In this case, add the custom login URI to the whitelist specified by the org.forgerock.openam.cdc.validLoginURIs property by performing the following steps:

  1. In the AM console, navigate to Configure > Server Defaults > Advanced.

  2. Set the value of the org.forgerock.openam.cdc.validLoginURIs property to /XUI/#login,/customLoginURI.

    For more information about this property, see Section 2.3.1.7, "Advanced Properties" in the Reference.

  3. Save your work.

Procedure 7.8. To Indicate Progress During Classic CDSSO Login

The default self-submitting form page that AM presents to users contains hidden fields, but is otherwise blank. If you want to show users that the operation is in progress, then customize the necessary JSP.

  1. Edit a copy of the file config/federation/default/cdclogin.jsp to add a clue that SSO is in progress, such as an image.

    You can find this file where you deployed AM, such as /path/to/tomcat/webapps/openam/config/federation/default/cdclogin.jsp.

    When you add an image or other presentation element, make sure that you retain the form and JavaScript as is.

  2. Unpack the AM-6.0.0.5.war file and replace the cdclogin.jsp file with your modified version. Also, include in the .war file any images referenced in your file.

  3. Pack up your custom version of AM, and then deploy it in your web container.

7.4. Troubleshooting SSO

In general, problems with single sign-on relate to some sort of mismatch of domain names. For example, a cookie that is configured on a third-level domain, such as sso.example.net will not work with an application on a similar domain, such as app.example.net. The following list describes scenarios that may lead to similar problems:

  • When a cookie domain does not match a domain for the protected application.

    Assume the application is configured on a domain named example.org. That application will not receive an SSO token configured on the example.net domain.

  • When a third-level domain is used for the SSO token.

    If an SSO token is configured on sso.example.net, an application on app.example.net does not receive the corresponding session token. In this case, the solution is to configure the SSO token on example.net.

  • When the Cookie Security or the CDSSO Secure Enable properties are configured in the agent profile with a regular HTTP application.

    If you need encrypted communications for an application protected by AM, use the Cookie Security or the CDSSO Secure Enable properties and make sure the application is accessible over HTTPS.

  • When the path listed in the cookie does not match the path for the application.

    Perhaps the cookie is configured with a /helloworld path; that will not match an application that might be configured with a /hellomars path. In that case, the application will not receive the cookie.

  • When an inappropriate name is used for the cookie domain

    As noted earlier, client browsers are configured to ignore first-level domains, such as com and net as well as functional equivalents, such as co.uk and co.jp.

  • When working with different browsers

    The name= value pairs described earlier may not apply to all browsers. The requirements for an HTTP cookie sent to an IE browser may differ from the requirements for other standard browsers, such as Firefox and Chrome. Based on anecdotal reports, IE does not recognize domain names that start with a number. In addition, IE reportedly refuses cookies that include the underscore (_) character in the FQDN.

  • When a client-based session cookie exceeds the maximum size permitted by the browser

    As described in Section 1.9.2, "Session Cookies", the default size of the iPlanetDirectoryPro cookie is approximately 2,000 bytes. When you customize AM sessions by adding attributes, the cookie size grows. Browsers allow cookie sizes between 4,000 and 5,200 bytes, depending on the browser. AM single sign-on does not support a cookie size that exceeds the maximum cookie size allowed by the browser.

Chapter 8. Using Authentication

This chapter covers how to authenticate and log out.

You can authenticate:

8.1.  Authenticating From a Browser

You can use the XUI to authenticate from a browser.

8.1.1. Authenticating Using the XUI

When using the XUI, the base URL to authenticate to 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/.

8.1.1.1. Specifying the Realm in the Login URL

When making a request to the XUI, specify the realm or realm alias as the value of a realm parameter in the query string, or the DNS alias in the domain component of the URL. If you do not use a realm alias, then you must specify the entire hierarchy of the realm, starting at the top-level realm. For example https://openam.example.com:8443/openam/XUI/?realm=/customers/europe#login/.

The following table demonstrates additional examples:

Table 8.1. Options for Specifying the Realm in XUI Login URLs
DescriptionExample URL
Full path of the realm as a parameter of XUI

http://openam.example.com:8080/openam/XUI/?realm=/customers/europe#login

Realm alias of the realm as a parameter of XUI

http://openam.example.com:8080/openam/XUI/?realm=myrealm#login

DNS Alias of the realm as the fully-qualified host name in the URL

http://myRealm.example.com:8080/openam/XUI/#login


The DNS alias is overridden by any use of either the full path or a realm alias as a query string parameter.

8.1.1.2. Example XUI Login URLs

Use any of the options listed in Section 8.1.2, "Authentication Parameters" as URL parameters. The following are example URLs with parameters:

Table 8.2. Example XUI Login URLs
DescriptionExample URL
Log in to the top level realm, requesting that AM display the user interface in German.

http://openam.example.com:8080/openam/XUI/?realm=/#login&locale=de

Log in to the myRealm subrealm whose parent is the top-level realm, requesting that AM display the user interface in German.

http://openam.example.com:8080/openam/XUI/?realm=/myRealm#login&locale=de

Log in to the myRealm subrealm whose parent is the top-level realm using the HOTPChain authentication chain, requesting that AM display the user interface in German.

http://openam.example.com:8080/openam/XUI/?realm=/myRealm#login&locale=de&service=HOTPChain


8.1.2. Authentication Parameters

AM 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 AM end the user's current session and start a new session.

authlevel

Request that AM 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 AM force the user to authenticate even if they already has a valid session. On successful authentication, AM updates the session token.

goto

On successful authentication, or successful logout, request that AM redirect the user to the specified location. Values must be URL-encoded. See Section 8.1.3, "Constraining Post-Login Redirects" for more information.

gotoOnFail

On authentication failure, request that AM redirect the user to the specified location. Values must be URL-encoded. See Section 8.1.3, "Constraining Post-Login Redirects" for more information.

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 AM 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 AM, and so on.

module

Request that AM 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 AM authenticate the user to the specified realm.

resource

Set this parameter to true to request resource-based authentication.

For resource-based authentication, also set the resourceURL parameter.

resourceURL

Set this parameter to the URL of the resource for resource-based authentication.

Resource-based authentication applies when an authorization policy has an environment setting of type Authentication by Module Chain or Authentication by Module Instance. When the specified resource URL matches a policy resource, AM finds the chain or module configured in the policy environment settings. AM then uses the specified chain or module to perform authentication.

For example, if you configure a policy with the resource https://www.example.com:443/index.html and the environment Authentication by Module Chain: DataStore, then the following login URL causes AM to use the DataStore chain to authenticate the user:

https://openam.example.com:8443/openam/XUI/?resource=true&resourceURL=https://www.example.com:443/index.html&goto=https://www.example.com/

On successful authentication, AM redirects the user-agent to https://www.example.com/.

As shown in the example, when setting the resourceURL parameter, also set resource=true.

service

Request that AM 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 AM 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 > Identities > UserName.

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 AM include this object class and attribute. See Section 1.4.1, "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.

8.1.3. Constraining Post-Login Redirects

By default, AM redirects the user to the URL specified in the goto and gotoOnFail query string parameters supplied to the authentication interface during login and logout. You can increase security against possible phishing attacks through open redirect by specifying a list of valid URL resources using the Validation Service.

AM 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 Section 2.1.1.4, "Specifying Resource Patterns with Wildcards" in the Authorization Guide.

Here are some general examples of URL pattern matching:

  • If no port is specified, http://www.example.com canonicalizes to http://www.example.com:80 and https://www.example.com canonicalizes to http://www.example.com:443.

  • A wildcard before "://" only matches up to "://"

    For example, http*://*.com/* matches http://www.example.com/hello/world and https://www.example.com/hello.

  • A wildcard between "://" and ":" matches up to ":"

    For example, http://*:85 matches http://www.example.com:85.

  • A wildcard between ":" and "/" only matches up to the first "/"

    For example, http://www.*:*/ matches http://www.example.com:80. In another example, http://www.example.com:* matches http://www.example.com:[any port] and http://www.example.com:[any port]/, but nothing more.

  • A wildcard after "/" matches anything, depending on whether it is single-level or a wildcard appropriately.

    For example, https://www.example.com/* matches https://www.example.com:443/foo/bar/baz/me

  • If you do not use any wildcards, AM 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, AM 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/.

Procedure 8.1. To Configure the Validation Service
  1. In the AM console, navigate to Realms > Realm Name > Services.

  2. Click Add a Service.

  3. From the Choose a service type drop-down list, select Validation Service.

  4. In the Valid goto URL Resources field, enter a valid URL pattern to whitelist.

    For example, http://app.example.com:80/*?*

  5. Click Create to save your settings.

8.2. Authenticating by Using the REST API

For information about how to authenticate to AM using the REST API, see Section A.6, "Authentication and Logout".

For information about how to use the session token returned from the REST API when authentication is successful, see Section A.7, "Using the Session Token After Authentication".

8.2.1. Sample Mobile Authentication Applications

Source code for sample mobile applications is available in sample repositories in the ForgeRock commons project. Get local clones of one or more of the following repositories so that you can try these sample applications on your system:

Chapter 9. Using Sessions

This chapter covers how to use the REST API to work with AM sessions.

AM provides REST APIs under /json/sessions for validating SSO tokens and getting information about active sessions.

9.1. Obtaining Information About Sessions

To obtain information about a session, perform an HTTP POST to the /json/sessions/ endpoint, using the getSessionInfo action. The endpoint will return information about the session token provided in the iPlanetDirectoryPro header by default. To get information about a different session token, include it as the value of the tokenId query parameter.

For example, the following shows an administrative user passing their session token in the iPlanetDirectoryPro header, and the session token of the demo user as the tokenId query parameter:

$ curl \
--request POST \
--header "iplanetDirectoryPro: AQIC4Dm...NTcy*" \
--header "Accept-API-Version: resource=3.1, protocol=1.0" \
http://openam.example.com:8080/openam/json/realms/root/sessions/?_action=getSessionInfo&tokenId=AQIC5...QAA*
{
    "username": "demo",
    "universalId": "id=demo,ou=user,dc=openam,dc=forgerock,dc=org",
    "realm": "/",
    "sessionHandle": "shandle:AQIC5wM2LY4SfcwbAHB6MVwCq-0Yvy9j0vjlbjLrT-797oE.*AAJTSQACMDEAAlNLABQtMzQ2OTAwMTU3MTg5MTUzNDUzOAACUzEAAA..*",
    "latestAccessTime": "2017-01-16T13:37:44Z",
    "maxIdleExpirationTime": "2017-01-16T14:07:44Z",
    "maxSessionExpirationTime": "2017-01-16T15:34:41Z"
}

9.2. Validating Sessions

To check over REST whether a session token is valid, perform an HTTP POST to the /json/sessions/ endpoint using the validate action. The endpoint validates the session token provided in the iPlanetDirectoryPro header by default. To validate a different session token, include it as the value of the tokenId query parameter.

If the session token is valid, the user ID and its realm is returned, as shown below:

$ curl \
--request POST \
--header "Accept-API-Version: resource=2.1, protocol=1.0" \
--data '{ "tokenId": "S9DSqBvhwaDcKkeIadQmbITQF_A.*AAJTSQACMDEAAlNLABxxbnVoK25yOVJJREd2c2ZxeDdxeUhqNmtrYkE9AAR0eXBlAANDVFMAAlMxAAA.*" }'
http://openam.example.com:8080/openam/json/realms/root/sessions?_action=validate
{
  "valid":true,
  "sessionUid":"209331b0-6d31-4740-8d5f-740286f6e69f-326295",
  "uid":"demo",
  "realm":"/"
}

By default, validating a session resets the session's idle time, which triggers a write operation to the Core Token Service token store. To avoid this write, perform a call using the validate&refresh=false action.

9.3. Refreshing CTS-Based Sessions

To reset the idle time of a CTS-based session using REST, perform an HTTP POST to the /json/sessions/ endpoint, using the refresh action. The endpoint will refresh the session token provided in the iPlanetDirectoryPro header by default. To refresh a different session token, include it as the value of the tokenId query parameter.

The following example shows an administrative user passing their session token in the iPlanetDirectoryPro header, and the session token of the demo user as the tokenId query parameter:

$ curl \
--request POST \
--header "iplanetDirectoryPro: AQIC5w...NTcy*" \
--header "Accept-API-Version: resource=3.1, protocol=1.0" \
http://openam.example.com:8080/openam/json/realms/root/sessions/?_action=refresh&tokenId=BXCCq...NX*1*

On success, AM resets the idle time for the CTS-based session, and returns timeout details of the session.

Resetting a CTS-based session's idle time triggers a write operation to the Core Token Service token store. Therefore, to avoid the overhead of write operations to the token store, be careful to use the refresh action only if you want to reset a CTS-based session's idle time.

Because AM does not monitor idle time for client-based sessions, do not use the tokenId of a client-based session when refreshing a session's idle time.

9.4. Invalidating Sessions

To invalidate a session, perform an HTTP POST to the /json/sessions/ endpoint using the logout action. The endpoint will invalidate the session token provided in the iPlanetDirectoryPro header by default. To refresh a different session token, include it as the value of the tokenId query parameter.

For example, the following command shows an administrative user passing their session token in the iPlanetDirectoryPro header, and the session token of the demo user as the tokenId query parameter:

$ curl \
--request POST \
--header "iplanetDirectoryPro: AQIC5w...NTcy*" \
--header "Accept-API-Version: resource=3.1, protocol=1.0" \
"http://openam.example.com:8080/openam/json/realms/root/sessions/?_action=logout&tokenId=BXCCq...NX*1*"

On success, AM invalidates the session and returns a success message.

If the token is not valid and cannot be invalidated an error message is returned, as follows:

{
    "result": "Token has expired"
}

Note

When passing in the user's session token as a tokenId query parameter, make sure the logout URL is properly enclosed in double quotes, so that AM does not inadvertently terminate the administrative user's session.

$ curl \
--request POST \
--header "iplanetDirectoryPro: $admin_token" \
"http://openam.example.com:8080/openam/json/realms/root/sessions/?_action=logout&tokenId=$user_token"

An alternate method to terminate the user session using the /json/sessions endpoint is to pass the user token in the header. With this method, you can omit the tokenId query parameter and the double quotes as follows:

$ curl \
--request POST \
--header "iplanetDirectoryPro: AQIC5w...NTcy*" \
--header "Accept-API-Version: resource=3.1, protocol=1.0" \
"http://openam.example.com:8080/openam/json/realms/root/sessions/?_action=logout&tokenId=BXCCq...NX*1*"

9.5. Getting and Setting Session Properties

AM lets you read and update properties on users' sessions using REST API calls.

Before you can perform operations on session properties using the REST API, you must first define the properties you want to set in the Session Property Whitelist Service configuration. For information on whitelisting session properties, see Section 2.2.27, "Session Property Whitelist Service" in the Reference.

You can use REST API calls for the following purposes:

  • To retrieve the names of the properties that you can read or update. This is the same set of properties configured in the Session Property Whitelist Service.

  • To read property values.

  • To update property values.

Session state affects the ability to set and delete properties as follows:

  • You can set and delete properties on a CTS-based session at any time during the session's lifetime.

  • You can only set and update properties on a client-based session during the authentication process, before the user receives the session token from AM. For example, you could set or delete properties on a client-based session from within a post-authentication plugin.

Differentiate the user who performs the operation on session properties from the session affected by the operation as follows:

  • Specify the session token of the user performing the operation on session properties in the iPlanetDirectoryPro header.

  • Specify the session token of the user whose session is to be read or modified as the tokenId parameter to the REST API call.

  • Omit the tokenId parameter from the REST API call if the session of the user performing the operation is the session that you want to read or modify.

The following examples assume that you configured a property named LoginLocation in the Session Property Whitelist Service configuration.

To retrieve the names of the properties you can get or set, and their values, perform an an HTTP POST to the resource URL, /json/sessions/, using the getSessionProperties action as shown in the following example:

$ curl \
--request POST \
--header "iplanetDirectoryPro: AQIC5w...NTcy*" \
--header "Accept-API-Version: resource=3.1, protocol=1.0" \
http://openam.example.com:8080/openam/json/realms/root/sessions/?_action=getSessionProperties&tokenId=BXCCq...NX*1*
{
    "LoginLocation": ""
}

To set the value of a session property, perform an HTTP POST to the resource URL, /json/sessions/, using the updateSessionProperties action. If no tokenId parameter is present in the REST API call, the session affected by the operation is the session specified in the iPlanetDirectoryPro header, as follows:

$ curl \
--request POST \
--header "Content-Type: application/json" \
--header "iplanetDirectoryPro: BXCCq...NX*1*" \
--header "Accept-API-Version: resource=3.1, protocol=1.0" \
--data '{"LoginLocation":"40.748440, -73.984559"}' \
http://openam.example.com:8080/openam/realms/root/json/sessions/?_action=updateSessionProperties
{
    "LoginLocation": "40.748440, -73.984559"
}

You can set multiple properties in a single REST API call by specifying a set of fields and their values in the JSON data. For example:

--data '{"property1":"value1", "property2":"value2"}'

To set the value of a session property on another user's session, specify the session token of the user performing the updateSessionProperties action in the iPlanetDirectoryPro, and specify the session token to be modified as the value of the tokenId parameter:

$ curl \
--request POST \
--header "Content-Type: application/json" \
--header "iplanetDirectoryPro: AQIC5w...NTcy*" \
--header "Accept-API-Version: resource=3.1, protocol=1.0" \
--data '{"LoginLocation":"40.748440, -73.984559"}' \
http://openam.example.com:8080/openam/json/realms/root/sessions/?_action=updateSessionProperties&a;tokenId=BXCCq...NX*1*
{
    "LoginLocation": "40.748440, -73.984559"
}

If the user attempting to modify the session does not have sufficient access privileges, the preceding examples result in a 403 Forbidden error.

You cannot set properties internal to AM sessions. If you try to modify an internal property in a REST API call, a 403 Forbidden error is returned. For example:

$ curl \
--request POST \
--header "Content-Type: application/json" \
--header "iplanetDirectoryPro: AQIC5w...NTcy*" \
--header "Accept-API-Version: resource=3.1, protocol=1.0" \
--data '{"AuthLevel":"5"}' \
http://openam.example.com:8080/openam/json/realms/root/sessions/?_action=updateSessionProperties&tokenId=BXCCq...NX*1*
{
    "code": 403,
    "reason": "Forbidden",
    "message": "Forbidden"
}

9.6. Performing Session Upgrade

This section demonstrates how to set up AM to allow users to upgrade their sessions during policy evaluation. For general information information about session upgrade, see Section 1.9.4, "Session Upgrade".

9.6.1. Session Upgrade Prerequisites

Before attempting to upgrade sessions, perform the following prerequisite tasks:

  • Configure a policy enforcement point (PEP), for example, a web or Java agent, that enforces AM policies on a website or application.

    AM web and Java agents handle session upgrade without additional configuration because the agents are built to handle AM's advices. If you build your own PEPs, however, you must take advices and session upgrade into consideration.

  • Configure an authorization policy to protect a resource protected by the Java or web agent, or a RESTful PEP. The following example of authorization policy allows GET and POST access to the *://*:*/sample/* resource to any authenticated user:

    Figure 9.1. Authorization Policy Example
    Authorization Policy Example

Once you have set up your environment, ensure that you are required to log in to access your protected resource.

Tip

To configure your environment quickly with a web agent to test session upgrade, see Section 1.3, "Setting Up the Software" in the Quick Start Guide.

9.6.2. Configuring the Environment for Session Upgrade

To configure your environment to attempt a session upgrade, perform the steps in the following procedure:

Procedure 9.1. To Configure the Environment for Session Upgrade
  1. Configure an authentication tree or chain to validate users' credentials during session upgrade.

    Authentication trees and chains do not require additional configuration to perform session upgrade. However, because session upgrade is a mechanism which may be used to grant users access to sensitive information, you should consider configuring a strong authentication method such as multi-factor authentication. Also, you may want to consider how long-lived sessions in your environment are. For example, if users should only have access to the protected resource to perform an operation, such as check the balance of an account, you may want to consider implementing transactional authorization instead. For more information, see Chapter 3, "Implementing Transactional Authorization" in the Authorization Guide.

  2. Configure at least one of the following environment conditions in the authentication policy reated as part of the prerequisites:

    Note

    The following examples feature simple policy conditions. For more information about configuring policies and environment conditions, see Section 2.1.1.3, "Configuring Policies" in the Authorization Guide.

    Authentication Level (greater than or equal to)

    Use this condition to present a list of authentication services (trees or chains) which provide a greater or equal authentication level to the one specified in the condition. The user selects their service of choice if multiple services are able to meet the criteria of the condition. For example, the following policy requires a chain or tree that provides authentication level 3 or greater:

    Figure 9.2. Session Upgrade by Authentication Level (greater than or equal to)
    Session Upgrade by Authentication Level (greater than or equal to)

    Tip

    Configure the authentication level by authentication module or as an authentication tree node. For more information, see Section 1.5, "About Authentication Levels" and Section 2.2.1.3, "Auth Level Decision Node".

    Authentication by Module Instance (Authentication modules only)

    Use this condition to enforce that a user has gone through a specific authentication module. For example, the following policy requires the user to log in with the DataStore module:

    Figure 9.3. Session Upgrade by Module Instance
    Session Upgrade by Module Instance

    Authentication by Service

    Use this condition to specify the chains or authentication trees to which the user needs to use to authenticate. For example, the following policy requires the user to log in with the Example tree:

    Figure 9.4. Session Upgrade by Service
    Session Upgrade by Service

    Note that the names of the authentication trees and chains are case-sensitive.

  3. Test session upgrade:

9.6.3. Performing Session Upgrade Using a Browser

The following procedure demonstrates how to upgrade a session when using a browser:

Procedure 9.2. To Perform Session Upgrade Using a Browser

To upgrade a session using a browser, perform the following steps:

  1. Ensure you have performed the tasks in Section 9.6.1, "Session Upgrade Prerequisites" and Procedure 9.1, "To Configure the Environment for Session Upgrade".

  2. In a browser, navigate to your protected resource. For example, http://www.example.com:9090/sample.

    The agent redirects the browser to the AM login screen.

  3. Authenticate to AM as the demo user.

    AM requires additional credentials to grant access to the resource. For example, if you set the policy environment condition to Authentication by Service and Example, you will be required to log in again as the demo user.

  4. Authenticate as the demo user. Note that providing credentials for a different user will fail.

    You can now access the protected resource.

9.6.4. Performing Session Upgrade Using REST

The following procedure demonstrates the REST flow to upgrade a session:

Procedure 9.3. To Perform Session Upgrade Using REST

To upgrade a session using REST, perform the following steps:

  1. Ensure you have performed the tasks in Section 9.6.1, "Session Upgrade Prerequisites" and Procedure 9.1, "To Configure the Environment for Session Upgrade".

  2. Log in with an administrative user that has permission to evaluate policies, such as amAdmin. For example:

    $ curl \
    --request POST \
    --header "Content-Type: application/json" \
    --header "X-OpenAM-Username: amadmin" \
    --header "X-OpenAM-Password: password" \
    --header "Accept-API-Version: resource=2.0, protocol=1.0" \
    --data "{}" \
    https://openam.example.com:8443/openam/json/realms/root/authenticate
    {
        "tokenId":"AQIC5wM2...",
        "successUrl":"/openam/console",
        "realm":"/"
    }

    Tip

    You can also assign privileges to a user to evaluate policies. For more information, see Procedure 4.3, "To Allow a User to Evaluate Policies" in the Authorization Guide.

  3. Log in with the user that should access the resources. For example, log in as the demo user:

    $ curl \
    --request POST \
    --header "Content-Type: application/json" \
    --header "X-OpenAM-Username: demo" \
    --header "X-OpenAM-Password: changeit" \
    --header "Accept-API-Version: resource=2.0, protocol=1.0" \
    --data "{}" \
    https://openam.example.com:8443/openam/json/realms/root/authenticate
    {
        "tokenId":"AQIC5wM...TU3OQ*",
        "successUrl":"/openam/console",
        "realm":"/"
    }
  4. Request a policy decision from AM for a protected resource, in this case, http://openam.example.com:9090/sample. The iPlanetDirectoryPro header sets the SSO token for the administrative user, and the subject element of the payload sets the SSO token for the demo user:

    $ curl --request POST \
     --header "Content-Type: application/json" \
     --header "iPlanetDirectoryPro: AQIC5wM2..." \
     --header "Accept-API-Version:protocol=1.0,resource=2.1" \
     --data '{
     "resources": [
         "http://www.example.com:9090/sample"
     ],
     "application": "iPlanetAMWebAgentService",
     "subject": { "ssoToken": "AQIC5wM...TU3OQ*"}
    }' \
    "https://openam.example.com:8443/openam/json/policies?_action=evaluate"
    [
       {
          "resource":"http://www.example.com:9090/sample",
          "actions":{
    
          },
          "attributes":{
    
          },
          "advices":{
             "AuthLevelConditionAdvice":[
                "3"
             ]
          },
          "ttl":9223372036854775807
       }
    ]

    AM returns with advice, which means the user must present additional credentials to access that resource.

    For more information about requesting policy decision, see Section 2.2.2, "Requesting Policy Decisions" in the Authorization Guide.

  5. Format the advice as XML, without spaces or line breaks. The following example is spaced and tabulated for readability purposes only:

    <Advices>
        <AttributeValuePair>
           <Attribute name="AuthLevelConditionAdvice"/>
           <Value>3</Value>
        </AttributeValuePair>
    </Advices>

    Note

    The example shows the XML render of a single advice. Depending on the conditions configured in the policy, the advice may contain several lines. For more information about advices, see Section 2.2.2.2, "Policy Decision Advice" in the Authorization Guide.

  6. URL-encode the XML advice. For example: %3CAdvices%3E%3CAttributeValuePair%3E%3CAttribute%20name%3D%22AuthLevelConditionAdvice%22%2F%3E%3CValue%3E3%3C%2FValue%3E%3C%2FAttributeValuePair%3E%3C%2FAdvices%3E.

    Ensure there are no spaces between tags when URL-encoding the advice.

  7. Call AM's authenticate endpoint to request information about the advice. Use the following details:

    • Add the following URL parameters:

      • authIndexType=COMPOSITE

      • authIndexValue=URL-encoded_Advice

    • Set the iPlanetDirectoryPro cookie as the SSO token for the demo user.

    For example:

    $ curl --request POST \
    --header "Content-Type: application/json" \
    --cookie "iPlanetDirectoryPro=AQIC5wM...TU3OQ*" \
    --header "Accept-API-Version: protocol=1.0,resource=2.1" \
    "https://openam.example.com:8443/openam/json/realms/root/authenticate?authIndexType=COMPOSITE&amp;authIndexValue=%3CAdvices%3E%3CAttributeValuePair%3E..."
    {
       "authId":"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJhdXRoSW5kZ...",
       "template":"",
       "stage":"DataStore1",
       "header":"Sign in",
       "callbacks":[
          {
             "type":"NameCallback",
             "output":[
                {
                   "name":"prompt",
                   "value":"User Name:"
                }
             ],
             "input":[
                {
                   "name":"IDToken1",
                   "value":""
                }
             ]
          },
          {
             "type":"PasswordCallback",
             "output":[
                {
                   "name":"prompt",
                   "value":"Password:"
                }
             ],
             "input":[
                {
                   "name":"IDToken2",
                   "value":""
                }
             ]
          }
       ]
    }

    AM returns information about how the user can authenticate in a callback; in this case, providing a username and password. For a list of possible callbacks, and more information about the /json/authenticate endpoint, see Section A.6, "Authentication and Logout".

  8. Call AM's authenticate endpoint to provide the required callback information. Use the following details:

    • Add the following URL query parameters:

      • authIndexType=COMPOSITE

      • authIndexValue=URL-encoded_Advice

    • Set the iPlanetDirectoryPro cookie as the SSO token for the demo user.

    • Send as data the complete payload AM returned in the previous step, ensuring you provide the requested callback information.

    In this example, provide the username and password for the demo user in the input objects, as follows:

    $ curl --request POST \
         --header 'Content-Type: application/json' \
         --header "Accept-API-Version: protocol=1.0,resource=2.1" \
         --cookie "iPlanetDirectoryPro=AQIC5wM...TU3OQ*" \
         --data '{
                    "authId":"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJhdXRoSW5kZ...",
                    "template":"",
                    "stage":"DataStore1",
                    "header":"Sign in",
                    "callbacks":[
                       {
                          "type":"NameCallback",
                          "output":[
                             {
                                "name":"prompt",
                                "value":"User Name:"
                             }
                          ],
                          "input":[
                             {
                                "name":"IDToken1",
                                "value":"demo"
                             }
                          ]
                       },
                       {
                          "type":"PasswordCallback",
                          "output":[
                             {
                                "name":"prompt",
                                "value":"Password:"
                             }
                          ],
                          "input":[
                             {
                                "name":"IDToken2",
                                "value":"changeit"
                             }
                          ]
                       }
                    ]
                 }
               }' \
         "https://openam.example.com:8443/openam/json/realms/root/authenticate?authIndexType=COMPOSITE&amp;authIndexValue=%3CAdvices%3E%3CAttributeValuePair%3E..."
    {
       "tokenId":"wpU01SaTq4X2x...NDVFMAAlMxAAA.*",
       "successUrl":"/openam/console",
       "realm":"/"
    }

    Note that AM returns a new SSO token for the demo user.

  9. Request a new policy decision from AM for the protected resource. The iPlanetDirectoryPro header sets the SSO token for the administrative user, and the subject element of the payload sets the new SSO token for the demo user:

    $ curl --request POST \
    --header "Content-Type: application/json" \
    --header "iPlanetDirectoryPro: AQIC5wM2..." \
    --header "Accept-API-Version:protocol=1.0,resource=2.1" \
    --data '{
       "resources":[
          "http://www.example.com:9090/sample"
       ],
       "application":"iPlanetAMWebAgentService",
       "subject":{
          "ssoToken":"wpU01SaTq4X2x...NDVFMAAlMxAAA.*"
       }
    }' \
    "https://openam.example.com:8443/openam/json/policies?_action=evaluate"
    [
       {
          "resource":"http://www.example.com:9090/sample",
          "actions":{
             "POST":true,
             "GET":true
          },
          "attributes":{
    
          },
          "advices":{
    
          },
          "ttl":9223372036854775807
       }
    ]

    AM returns that demo can perform POST and GET operations on the resource.

Chapter 10. Customizing Authentication

This chapter describes how to extend AM authentication features by developing custom modules, nodes, and plugins.

10.1. Customizing Authentication Trees

Your deployment might require customizing standard authentication tree features. See the following sections for customization examples:

10.1.1. Creating or Modifying an Authentication Node

This section shows how to customize authentication trees by creating a new node, or modifying one of the sample authentication nodes. For deployments with particular requirements not met by existing AM authentication nodes, determine whether you can adapt one of the built-in or extension nodes for your needs. If not, build the functionality into a custom authentication node.

For information on creating or modifying authentication nodes, see the following sections:

10.1.1.1. Preparing to Customize Authentication Nodes

This section explains the prerequisites for customizing authentication nodes, and how to use a Maven archetype or the samples provided with AM to set up a project for building nodes.

To prepare for creating or modifying authentication nodes, complete the following procedures:

Procedure 10.1. To Prepare an Environment For Building Custom Authentication Nodes

Complete the following steps to set up your environment for building custom authentication nodes:

  1. Ensure your BackStage account is part of a subscription:

    1. In a browser, navigate to the ForgeRock BackStage website and log in or register for an account.

    2. Confirm or request that your account is added to a subscription. For more details, see "Getting access to product support" in the ForgeRock Knowledge Base.

  2. Install Apache Maven 3.2.5 or later, and Oracle JDK or OpenJDK 1.8.

    Tip

    To verify the installed versions, run the mvn --version command:

    $ mvn --version
    Apache Maven 3.2.5 (12a6b3acb947671f09b81f49094c53f426d8cea1; 2014-12-14T17:29:23+00:00)
    Maven home: /usr/local/apache-maven/apache-maven-3.2.5 Java version: 1.8.0_121, vendor: Oracle Corporation
    Java home: /Library/Java/JavaVirtualMachines/jdk1.8.0_121.jdk/Contents/Home/jre Default locale: en_US,
    platform encoding: UTF-8 OS name: "mac os x", version: "10.11.6", arch: "x86_64", family: "mac"
              
  3. Configure Maven to be able to access the ForgeRock repositories by adding your BackStage credentials to the Maven settings.xml file. For details, see "How do I access the ForgeRock protected Maven repositories?" in the ForgeRock Knowledge Base.

    As well as access to the authentication node source code, if you want to use the archetype to create a project for custom authentication nodes, you need access to the forgerock-private-releases repository. Ensure your settings.xml file contains a profile similar to the following:

    <profiles>
      <profile>
      <id>forgerock</id>
      <repositories>
          <repository>
              <id>forgerock-private-releases</id>
              <url>https://maven.forgerock.org:443/repo/private-releases</url>
              <releases>
                  <enabled>true</enabled>
                  <checksumPolicy>fail</checksumPolicy>
              </releases>
              <snapshots>
                  <enabled>false</enabled>
                  <checksumPolicy>warn</checksumPolicy>
              </snapshots>
          </repository>
      </repositories>
      </profile>
    </profiles>
    <activeProfiles>
      <activeProfile>forgerock</activeProfile>
    </activeProfiles>
Procedure 10.2. To Set Up a Maven Project For Building Custom Authentication Nodes

ForgeRock provides a Maven archetype for creating a starter project suitable for building an authentication node. You can also download the projects used to build the authentication nodes included with AM and modify those to match your requirements.

Note

Ensure you have completed the steps in Procedure 10.1, "To Prepare an Environment For Building Custom Authentication Nodes" before proceeding.

Complete either of the following steps to set up or download a Maven project for building custom authentication nodes:

  1. To use the ForgeRock auth-tree-node-archetype archetype to generate a starter Maven project:

    1. In a terminal window, navigate to a folder in which to create the new Maven project. For example:

      $ cd ~/Repositories
    2. Run the mvn archetype:generate command, providing the following information:

      groupId

      A domain name that you control, used for identifying the project.

      artifactId

      The name of the JAR created by the project, without version information. Also the name of the folder created to store the project.

      version

      The version assigned to the project.

      package

      The package name in which your custom authentication node classes are generated.

      authNodeName

      The name of the custom authentication node, also used in the generated README.md file and for class file names.

      For example:

      $ mvn archetype:generate \
      -DgroupId=com.example \
      -DartifactId=customAuthNode \
      -Dversion=1.0.0-SNAPSHOT \
      -Dpackage=com.example.customAuthNode \
      -DauthNodeName=myCustomAuthNode \
      -DarchetypeGroupId=org.forgerock.am \
      -DarchetypeArtifactId=auth-tree-node-archetype \
      -DarchetypeVersion=6.0.0 \
      -DinteractiveMode=false
      [INFO] Project created from Archetype in dir: /Users/ForgeRock/Repositories/customAuthNode
      [INFO] ------------------------------------------------------------------------
      [INFO] BUILD SUCCESS
      [INFO] ------------------------------------------------------------------------
      [INFO] Total time: 1.397 s
      [INFO] Finished at: 2018-01-18T15:45:06+00:00
      [INFO] Final Memory: 16M/491M
      [INFO] ------------------------------------------------------------------------

      A new custom authentication node project is created, for example in the /Users/ForgeRock/Repositories/customAuthNode folder.

      The project resembles the following:

      Figure 10.1. Node Project Created by Using the Archetype
      An example project as viewed in an IDE.

  2. To download the project containing the default AM authentication nodes from the am-external repository:

    1. If you do not already have a ForgeRock BackStage account, get one from https://backstage.forgerock.com. You cannot clone the am-external repository without a BackStage account.

    2. Clone the am-external repository:

      $ git clone https://myBackStageID@stash.forgerock.org/scm/openam/am-external.git

      Tip

      URL encode your BackStage ID if it contains special characters. For example : becomes %3A and @ becomes %40.

      Enter your BackStage password when prompted to do so.

    3. Check out the release/6.0.0.5 branch:

      $ cd am-external
      $ git checkout releases/6.0.0.5

      The AM authentication nodes project is located in the am-external/openam-auth-trees/auth-nodes/ folder.

      The project resembles the following:

      Figure 10.2. Node Project Cloned from ForgeRock
      An example project as viewed in an IDE.

10.1.1.2. The Maven Project for an Authentication Node

The Maven project for an authentication node contains the following files:

pom.xml

Apache Maven project file for the custom authentication node.

This file specifies how to build the custom authentication node, and also specifies its dependencies on AM components.

authModuleName.java

Core class for the custom authentication node. See Section 10.1.1.3, "The Core Class of an Authentication Node".

authModuleNamePlugin.java

Plugin class for the custom authentication node. See Section 10.1.1.4, "The Plugin Class of an Authentication Node".

authModuleName.properties

Properties file containing the localized strings displayed by the custom authentication node. See Section 10.1.1.5, "Localizing an Authentication Node".

org.forgerock.openam.plugins.AmPlugin

Specifies the name of the plugin class AM uses to import the custom authentication node. See Section 10.1.1.4, "The Plugin Class of an Authentication Node".

For example:

com.example.customAuthNode.myCustomAuthNodePlugin

10.1.1.3. The Core Class of an Authentication Node

The core class may access and modify the persisted state that is shared between the nodes within a tree, and may request input by using callbacks. The class also defines the possible exit paths from the node.

The following example is the SetSessionPropertiesNode class, taken from the Set Session Properties Node:

/*
 * CCPL HEADER START
 *
 * This work is licensed under the Creative Commons
 * Attribution-NonCommercial-NoDerivs 3.0 Unported License.
 * To view a copy of this license, visit
 * https://creativecommons.org/licenses/by-nc-nd/3.0/
 * or send a letter to Creative Commons, 444 Castro Street,
 * Suite 900, Mountain View, California, 94041, USA.
 *
 * You can also obtain a copy of the license at legal-notices/CC-BY-NC-ND.txt.
 * See the License for the specific language governing permissions
 * and limitations under the License.
 *
 * If applicable, add the following below this CCPL HEADER, with the fields
 * enclosed by brackets "[]" replaced with your own identifying information:
 *      Portions Copyright [yyyy] [name of copyright owner]
 *
 * CCPL HEADER END
 *
 *      Copyright 2018 ForgeRock AS.
 *
 */

package org.forgerock.openam.auth.nodes;

import com.google.inject.assistedinject.Assisted;
import org.forgerock.openam.annotations.sm.Attribute;
import org.forgerock.openam.auth.node.api.Action;
import org.forgerock.openam.auth.node.api.Node;
import org.forgerock.openam.auth.node.api.SingleOutcomeNode;
import org.forgerock.openam.auth.node.api.TreeContext;
import org.forgerock.openam.auth.nodes.validators.SessionPropertyValidator;

import javax.inject.Inject;
import java.util.Map;

/**
 * A node which contributes a configurable set of properties to be added to the user's session, if/when it is created.
 */
@Node.Metadata(outcomeProvider = SingleOutcomeNode.OutcomeProvider.class,
        configClass = org.forgerock.openam.auth.nodes.SetSessionPropertiesNode.Config.class)  (1)
public class SetSessionPropertiesNode extends SingleOutcomeNode {  (2)

    /**
     * Configuration for the node.
     */
    public interface Config {  (3)
        /**
         * A map of property name to value.
         * @return a map of properties.
         */
        @Attribute(order = 100, validators = SessionPropertyValidator.class)
        Map<String, String> properties();
    }

    private final Config config;

    /**
     * Constructs a new SetSessionPropertiesNode instance.
     * @param config Node configuration.
     */
    @Inject  (4)
    public SetSessionPropertiesNode(@Assisted Config config) {
        this.config = config;
    }

    @Override
    public Action process(TreeContext context) {  (5)
        Action.ActionBuilder actionBuilder = goToNext();
        config.properties().forEach(actionBuilder::putSessionProperty);
        return actionBuilder.build();
    }
}
Key:

1

The @Node.Metadata annotation. See Section 10.1.1.3.1, "The Meta Data Annotation".

2

Implementing the Node interface. See Section 10.1.1.3.2, "The Node Interface".

3

Implementing the Config interface. See Section 10.1.1.3.3, "The Config Interface".

4

Injecting the Node instance. See Section 10.1.1.3.4, "Injecting the Node Instance".

5

Creating an Action instance. See Section 10.1.1.3.5, "Performing the Node Logic".

10.1.1.3.1. The Meta Data Annotation

Before defining the class, use a Java @Node.Metadata annotation to specify the classes the node uses for various functions. The supported properties are as follows:

outcomeProvider

The class name that the node uses to set up the possible outcomes.

The SingleOutcomeNode and AbstractDecisionNode base classes provide suitable outcome provider classes for those node types. You can create a custom outcome provider for other circumstances.

For example, the following is the custom outcome provider from the LDAP Decision node, which has True, False, Locked and Expired exit paths:

/**
 * Defines the possible outcomes from this Ldap node.
 */
public static class LdapOutcomeProvider implements OutcomeProvider {
    @Override
    public List<Outcome> getOutcomes(PreferredLocales locales, JsonValue nodeAttributes) {
        ResourceBundle bundle = locales.getBundleInPreferredLocale(LdapDecisionNode.BUNDLE,
                LdapOutcomeProvider.class.getClassLoader());
        return ImmutableList.of(
                new Outcome(LdapOutcome.TRUE.name(), bundle.getString("trueOutcome")),
                new Outcome(LdapOutcome.FALSE.name(), bundle.getString("falseOutcome")),
                new Outcome(LdapOutcome.LOCKED.name(), bundle.getString("lockedOutcome")),
                new Outcome(LdapOutcome.EXPIRED.name(), bundle.getString("expiredOutcome")));
    }
}
configClass

The class name that contains the configuration of any attributes requested by the node.

configValidator

An optional class name used to validate the provided configuration.

For example, the following is the @Node.Metadata annotation from the Set Session Properties Node:

@Node.Metadata(outcomeProvider = SingleOutcomeNode.OutcomeProvider.class,
             configClass = SetSessionPropertiesNode.Config.class)

For more information on the @Node.Metadata annotation, see the Node.Metadata annotation type in the AM 6.0.0.5 Public API Javadoc.

10.1.1.3.2. The Node Interface

The core class must implement the Node interface. For more information, see the Node interface in the AM 6.0.0.5 Public API Javadoc.

AM provides base classes you can extend to implement the Node interface, depending on the type of custom authentication node you are creating. The available base classes are as follows:

SingleOutcomeNode

Used in nodes that only have a single exit path.

The Modify Auth Level Node is an example of a node that uses the SingleOutcomeNode base class.

For more information, see the SingleOutcomeNode class in the AM 6.0.0.5 Public API Javadoc.

AbstractDecisionNode

Used in nodes that have a boolean-type exit path, for example true or false, yes or no, or allow or deny.

The Data Store Decision Node is an example of a node that uses the AbstractDecisionNode base class.

For more information, see the AbstractDecisionNode class in the AM 6.0.0.5 Public API Javadoc.

Implement the Node interface yourself if your custom node exit paths do not match the scenarios outlined above.

10.1.1.3.3. The Config Interface

Within the Node interface implementation, define the properties the node will use in the Config interface, by using the @Attribute annotation.

The defined properties appear as configurable options in the tree designer view when adding a node of the relevant type.

For example, the following is the Config interface from the Set Session Properties Node, defining a property named properties that displays when configuring the node in the AM administration console:

public interface Config {
    /**
    * A map of property name to value.
    * @return a map of properties.
    */
    @Attribute(order = 100, validators = SessionPropertyValidator.class)
    Map<String, String> properties();
}

private final Config config;

The example above defines an attribute named properties as a map of property names and the value to set.

Use the default keyword to assign a default value to an attribute. For example:

public interface Config {
    /**
     * The number of times to allow a retry.
     * @return The number of retries.
     */
    @Attribute(order = 100, validators = GreaterThanZeroValidator.class)
    default int retryLimit() {
        return 3;
    }
}

private final Config config;

Note that attribute names are used when localizing the node's text, see Section 10.1.1.5, "Localizing an Authentication Node".

For more information, see the Config annotation type and the Attribute annotation type in the AM 6.0.0.5 Public API Javadoc.

10.1.1.3.4. Injecting the Node Instance

AM uses Google's Guice dependency injection framework for authentication nodes. Use the @Inject annotation to construct a new instance of the custom authentication node, specifying the configuration interface set up earlier.

For example, the following is the injection used by the Modify Auth Level Node:

/**
 * Constructs a new SetSessionPropertiesNode instance.
 * @param config Node configuration.
 */
@Inject
public SetSessionPropertiesNode(@Assisted Config config) {
    this.config = config;
}

For more information, see the Inject annotation type and the Assisted annotation type in the Google Guice Javadoc.

10.1.1.3.5. Performing the Node Logic

The main logic of a node is handled by the Action class.

The Action class uses the following fields:

callbacks

A list of the callbacks that have been requested by the node. This list may be null.

outcome

The result of the node.

sessionProperties

A map of properties that will be added to the final session if the authentication tree completes successfully.

Use the putSessionProperty(String key, String value) and removeSessionProperty(String key) methods to add or remove entries from the map.

sharedState

A JSON representation of the properties set so far by nodes in the tree.

For example, if a Username Collector Node has been completed earlier in the authentication tree, the USERNAME value collected will be available in the sharedState JSON. Access the value as follows:

String username = context.sharedState.get(USERNAME).asString();
transientState

A JSON representation of any transient properties set by the previous node in the tree. Transient state is not persisted to the authentication session, and is only available until the authentication flow reaches the next node requiring user interaction.

For example, if a Password Collector Node has been completed in the previous node in the authentication tree, the PASSWORD value collected will be available in the transientState JSON. Access the value as follows:

String password = context.transientState.get(PASSWORD).asString();

The methods provided within the Action class are as follows:

goTo()

Specify the exit path to take, and move on to the next node in the tree.

For example:

return goTo(false).build();

See the goTo method in the AM 6.0.0.5 Public API Javadoc.

send()

Send the specified callbacks to the user for them to interact with.

For example, the Username Collector Node uses the following code to send the NameCallback callback to the user to request the USERNAME value:

return send(new NameCallback(bundle.getString("callback.username"))).build();

See the send methods in the AM 6.0.0.5 Public API Javadoc.

sendingCallbacks()

Returns true if the action is a request for input from the user.

See the sendingCallbacks method in the AM 6.0.0.5 Public API Javadoc.

For example, the following is the Action class from the Auth Level Decision Node:

@Override
public Action process(TreeContext context) throws NodeProcessException {
    JsonValue authLevel = context.sharedState.get(AUTH_LEVEL);
    boolean authLevelSufficient = !authLevel.isNull()
                                  && authLevel.asInteger()
                                  >= config.authLevelRequirement();
    return goTo(authLevelSufficient).build();
}

For more information, see the Action class in the AM 6.0.0.5 Public API Javadoc.

10.1.1.4. The Plugin Class of an Authentication Node

The plugin class is responsible for informing AM about the details of the customized authentication node. There is little variation between the plugin class for each authentication node, other than the version number and class names within.

The following example is from the plugin class taken from a project generated by the auth-tree-node-archetype archetype:

public class myCustomAuthNodePlugin extends AbstractNodeAmPlugin {  (1)

    private final AnnotatedServiceRegistry serviceRegistry;

    /**
     * DI-enabled constructor.
     * @param serviceRegistry A service registry instance.
     */
    @Inject
    public myCustomAuthNodePlugin(AnnotatedServiceRegistry serviceRegistry) {  (2)
        this.serviceRegistry = serviceRegistry;
    }

    @Override
    public String getPluginVersion() {
        return "1.0.0";  (3)
    }

    @Override
    public void onStartup() throws PluginException {
        for (Class<? extends Node> nodeClass : getNodes()) {
            pluginTools.registerAuthNode(nodeClass);  (4)
        }
    }

    @Override
    protected Iterable<? extends Class<? extends Node>> getNodes() {
        return asList(
                myCustomAuthNode.class  (5)
        );
    }
}
Key:

1

Name the plugin class after the core class, and append Plugin, for example myCustomAuthNodePlugin.

2

Use the @Inject annotation to inject an instance of the plugin class.

3

Provide a version number for the authentication node.

4

Loop through the available nodes and register them with AM.

For more information, see the PluginTools interface in the AM 6.0.0.5 Public API Javadoc.

5

Ensure a call to the getNodes() function returns the core classes of the authentication nodes to register, as a list.

10.1.1.5. Localizing an Authentication Node

Use Java resource bundles containing translations to localize the text that a node displays.

Procedure 10.3. To Localize Node UI Text for Display to Users
  1. Create a Java resource bundle under the resources folder in the Maven project for your node.

    The path and filename must match that of the core class that will use the translated text.

    For example, the resource bundle for the Section 2.2.1.39, "Username Collector Node" is located in the following path: src/main/resources/org/forgerock/openam/auth/nodes/UsernameCollectorNode

    Figure 10.3. Example Resource Bundle
    The resource bundle for the Username Collector Node.

  2. Add the properties and strings that the node will display to the user. For example:

    callback.username=User Name
  3. Create a .properties file in the resource bundle for each language your node will display. The filename must include the language identifier, as per rfc5646 - Tags for Identifying Languages.

    For example, for French translations your .properties file could be called UsernameCollectorNode_fr.properties.

  4. Replicate the properties and translate the values in each .properties files. For example:

    callback.username=Nom d'utilisateur
  5. In the core class for the node, specify the path to the resource bundle the node will retrieve the translated strings from:

    private static final String BUNDLE = "org/forgerock/openam/auth/nodes/UsernameCollectorNode"
  6. Define a reference to the bundle using the getBundleInPreferredLocale function to enable retrieval of translated strings:

    ResourceBundle bundle = context.request.locales.getBundleInPreferredLocale(BUNDLE, getClass().getClassLoader());
  7. Use the getString function whenever you need to retrieve a translation from the resource bundle:

    return send(new NameCallback(bundle.getString("callback.username"))).build();

10.1.1.6. Building and Installing Authentication Nodes

This section explains how to build and install authentication nodes for use in authentication trees.

Procedure 10.4. To Build and Install Custom Authentication Nodes
  1. Change to the root directory of the Maven project of the custom nodes. For example:

    $ cd /Users/Forgerock/Repositories/am-external/openam-auth-trees/auth-nodes
  2. Run the mvn package command.

    The project will generate a .jar file containing your custom nodes. For example, auth-nodes-6.0.0.5.jar.

  3. Copy the .jar file to the WEB-INF/lib/ folder where AM is deployed:

    $ cp auth-nodes-6.0.0.5.jar /path/to/tomcat/webapps/openam/WEB-INF/lib/

    Note

    Delete or overwrite older versions of the nodes .jar file from the WEB-INF/lib/ folder, to avoid clashes.

  4. Restart AM for the new nodes to become available.

    The custom authentication node is now available in the tree designer to add to authentication trees:

    Figure 10.4. Custom Node within a Tree
    A custom authentication node being used in a new tree.

    For more information on using the tree designer to manage authentication trees, see Section 2.2, "Configuring Authentication Trees".

10.1.2. Creating Post-Authentication Hooks for Trees

This section explains how to create a hook used by a node within an authentication tree. These tree hooks can perform custom processing after an authentication tree has successfully completed and a session created.

AM includes the following authentication tree hooks:

CreatePersistentCookieJwt

Used by the SetPersistentCookieNode authentication node.

UpdatePersistentCookieJwt

Used by the PersistentCookieDecisionNode authentication node.

10.1.2.1. The Core Class of an Authentication Tree Hook

The following example shows the UpdatePersistentCookieTreehook class, as used by the the Persistent Cookie Decision node:

/*
 * CCPL HEADER START
 *
 * This work is licensed under the Creative Commons
 * Attribution-NonCommercial-NoDerivs 3.0 Unported License.
 * To view a copy of this license, visit
 * https://creativecommons.org/licenses/by-nc-nd/3.0/
 * or send a letter to Creative Commons, 444 Castro Street,
 * Suite 900, Mountain View, California, 94041, USA.
 *
 * You can also obtain a copy of the license at legal-notices/CC-BY-NC-ND.txt.
 * See the License for the specific language governing permissions
 * and limitations under the License.
 *
 * If applicable, add the following below this CCPL HEADER, with the fields
 * enclosed by brackets "[]" replaced with your own identifying information:
 *      Portions Copyright [yyyy] [name of copyright owner]
 *
 * CCPL HEADER END
 *
 *      Copyright 2018 ForgeRock AS.
 *
 */

package org.forgerock.openam.auth.nodes.treehook;

import java.util.List;
import java.util.concurrent.TimeUnit;

import javax.inject.Inject;

import org.forgerock.guice.core.InjectorHolder;
import org.forgerock.http.protocol.Cookie;
import org.forgerock.http.protocol.Request;
import org.forgerock.http.protocol.Response;
import org.forgerock.openam.auth.node.api.TreeHook;
import org.forgerock.openam.auth.node.api.TreeHookException;
import org.forgerock.openam.auth.nodes.PersistentCookieDecisionNode;
import org.forgerock.openam.auth.nodes.jwt.InvalidPersistentJwtException;
import org.forgerock.openam.auth.nodes.jwt.PersistentJwtStringSupplier;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

import com.google.inject.assistedinject.Assisted;

/**
 * A TreeHook for updating a persistent cookie.
 */
@TreeHook.Metadata(configClass = PersistentCookieDecisionNode.Config.class)  (1)
public class UpdatePersistentCookieTreeHook implements TreeHook {  (2)

    private final Request request;
    private final Response response;
    private final PersistentCookieDecisionNode.Config config;
    private final PersistentJwtStringSupplier persistentJwtStringSupplier;
    private final PersistentCookieResponseHandler persistentCookieResponseHandler;
    private final Logger logger = LoggerFactory.getLogger("amAuth");

    /**
     * The UpdatePersistentCookieTreeHook Constructor.
     *
     * @param request The request.
     * @param response The response.
     * @param config the config for updating the cookie.
     */
    @Inject  (3)
    public UpdatePersistentCookieTreeHook(@Assisted Request request, @Assisted Response response,
                                          @Assisted PersistentCookieDecisionNode.Config config) {
        this.request = request;
        this.response = response;
        this.config = config;
        this.persistentJwtStringSupplier = InjectorHolder.getInstance(PersistentJwtStringSupplier.class);
        this.persistentCookieResponseHandler = InjectorHolder.getInstance(PersistentCookieResponseHandler.class);
    }

    @Override
    public void accept() throws TreeHookException {  (4)
        logger.debug("UpdatePersistentCookieTreeHook.accept");
        String orgName = PersistentCookieResponseHandler.getOrgName(response);
        Cookie originalJwt = getJwtCookie(request, config.persistentCookieName());
        if (originalJwt != null) {
            String jwtString;
            try {
                jwtString = persistentJwtStringSupplier.getUpdatedJwt(originalJwt.getValue(), orgName,
                        String.valueOf(config.hmacSigningKey()), config.idleTimeout().to(TimeUnit.HOURS));
            } catch (InvalidPersistentJwtException e) {
                logger.error("Invalid jwt", e);
                throw new TreeHookException(e);
            }

            if (jwtString != null && !jwtString.isEmpty()) {
                persistentCookieResponseHandler.setCookieOnResponse(response, request, config.persistentCookieName(),
                        jwtString, originalJwt.getExpires(), config.useSecureCookie(), config.useHttpOnlyCookie());
            }
        }
    }

    private Cookie getJwtCookie(Request request, String cookieName) {
        if (request.getCookies().containsKey(cookieName)) {
            List<Cookie> cookies = request.getCookies().get(cookieName);
            for (Cookie cookie : cookies) {
                if (cookie.getName().equals(cookieName)) {
                    return cookie;
                }
            }
        }
        return null;
    }
}
Key:

1

The @TreeHook.Metadata annotation.

Before defining the core class, use a Java @TreeHook.Metadata annotation to specify the class the tree hook uses for its configuration. Use the configClass property to specify the configuration class of the node that will be using the tree hook.

2

The core class must implement the TreeHook interface. For more information, see the TreeHook interface in the AM 6.0.0.5 Public API Javadoc.

3

AM uses Google's Guice dependency injection framework for authentication nodes and tree hooks. Use the @Inject annotation to construct a new instance of the tree hook, specifying the configuration interface set up earlier and any other required parameters.

For more information, see the Inject annotation type and the Assisted annotation type in the Google Guice Javadoc.

4

Creating an Accept instance. The main logic of a tree hook is handled by the Accept function.

10.2. Customizing Authentication Chains

Your deployment might require customizing standard authentication chain features. See the following sections for customization examples:

10.2.1. Creating a Custom Authentication Module

This section shows how to customize authentication with a sample custom authentication module. For deployments with particular requirements not met by existing AM authentication modules, determine whether you can adapt one of the built-in or extension modules for your needs. If not, build the functionality into a custom authentication module.

10.2.1.1. About the Sample Authentication Module

The sample authentication module prompts for a user name and password to authenticate the user, and handles error conditions. The sample shows how you integrate an authentication module into AM such that you can configure the module through the AM console, and also localize the user interface.

For information on downloading and building AM sample source code, see How do I access and build the sample code provided for OpenAM 12.x, 13.x and AM (All versions)? in the Knowledge Base.

Get a local clone so that you can try the sample on your system. In the sources, you find the following files under the /path/to/openam-samples-external/custom-authentication-module directory:

pom.xml

Apache Maven project file for the module

This file specifies how to build the sample authentication module, and also specifies its dependencies on AM components and on the Java Servlet API.

src/main/java/org/forgerock/openam/examples/SampleAuth.java

Core class for the sample authentication module

This class is called by AM to initialize the module and to process authentication. See Section 10.2.1.4, "The Sample Authentication Logic" for details.

src/main/java/org/forgerock/openam/examples/SampleAuthPrincipal.java

Class implementing java.security.Principal interface that defines how to map credentials to identities

This class is used to process authentication. See Section 10.2.1.5, "The Sample Auth Principal" for details.

src/main/resources/amAuthSampleAuth.properties

Properties file mapping UI strings to property values

This file makes it easier to localize the UI. See Section 10.2.1.2, "Sample Auth Properties" for details.

src/main/resources/amAuthSampleAuth.xml

Configuration file for the sample authentication service

This file is used when registering the authentication module with AM. See Section 10.2.1.6, "The Sample Auth Service Configuration" for details.

src/main/resources/config/auth/default/SampleAuth.xml

Callback file for deprecated AM classic UI authentication pages

The sample authentication module does not include localized versions of this file. See Section 10.2.1.3, "Sample Auth Callbacks" for details.

src/main/java/org/forgerock/openam/examples/SampleAuthPlugin.java, src/main/resources/META-INF/services/org.forgerock.openam.plugins.AmPlugin

These files serve to register the plugin with AM.

The Java class, SampleAuthPlugin, implements the org.forgerock.openam.plugins.AmPlugin interface. In the sample, this class registers the SampleAuth implementation, and the amAuthSampleAuth service schema for configuration.

The services file, org.forgerock.openam.plugins.AmPlugin, holds the fully qualified class name of the AmPlugin that registers the custom implementations. In this case, org.forgerock.openam.examples.SampleAuthPlugin.

For an explanation of service loading, see the ServiceLoader API specification.

10.2.1.2. Sample Auth Properties

AM uses a Java properties file per locale to retrieve the appropriate, localized strings for the authentication module.

The following is the Sample Authentication Module properties file, amAuthSampleAuth.properties.

sampleauth-service-description=Sample Authentication Module
a500=Authentication Level
a501=Service Specific Attribute

sampleauth-ui-login-header=Login
sampleauth-ui-username-prompt=User Name:
sampleauth-ui-password-prompt=Password:

sampleauth-error-1=Error 1 occurred during the authentication
sampleauth-error-2=Error 2 occurred during the authentication

10.2.1.3. Sample Auth Callbacks

AM callbacks XML files are used to build the deprecated classic UI to prompt the user for identity information needed to process the authentication. The document type for a callback XML file is described in WEB-INF/Auth_Module_Properties.dtd where AM is deployed.

The value of the moduleName property in the callbacks file must match your custom authentication module's class name. Observe that the module name SampleAuth, shown in the example below, matches the class name in Section 10.2.1.4, "The Sample Authentication Logic".

The following is the SampleAuth.xml callbacks file.

<!DOCTYPE ModuleProperties PUBLIC
 "=//iPlanet//Authentication Module Properties XML Interface 1.0 DTD//EN"
        "jar://com/sun/identity/authentication/Auth_Module_Properties.dtd">

<ModuleProperties moduleName="SampleAuth" version="1.0" >
    <Callbacks length="0" order="1" timeout="600" header="#NOT SHOWN#" />
    <Callbacks length="2" order="2" timeout="600" header="#TO BE SUBSTITUTED#">
        <NameCallback isRequired="true">
            <Prompt>#USERNAME#</Prompt>
        </NameCallback>
        <PasswordCallback echoPassword="false" >
            <Prompt>#PASSWORD#</Prompt>
        </PasswordCallback>
    </Callbacks>
    <Callbacks length="1" order="3" timeout="600" header="#TO BE SUBSTITUTED#"
        error="true" >
        <NameCallback>
            <Prompt>#THE DUMMY WILL NEVER BE SHOWN#</Prompt>
        </NameCallback>
    </Callbacks>
</ModuleProperties>

This file specifies three states.

  1. The initial state (order="1") is used dynamically to replace the dummy strings shown between hashes (for example, #USERNAME#) by the substituteUIStrings() method in SampleAuth.java.

  2. The next state (order="2") handles prompting the user for authentication information.

  3. The last state (order="3") has the attribute error="true". If the authentication module state machine reaches this order then the authentication has failed. The NameCallback is not used and not displayed to user. AM requires that the callbacks array have at least one element. Otherwise AM does not permit header substitution.

10.2.1.4. The Sample Authentication Logic

An AM authentication module must extend the com.sun.identity.authentication.spi.AMLoginModule abstract class, and must implement the methods shown below.

See the ForgeRock Access Management Java SDK API Specification for reference.

public void init(Subject subject, Map sharedState, Map options)

// OpenAM calls the process() method when the user submits authentication
// information. The process() method determines what happens next:
// success, failure, or the next state specified by the order
// attribute in the callbacks XML file.
public int process(Callback[] callbacks, int state) throws LoginException

// OpenAM expects the getPrincipal() method to return an implementation of
// the java.security.Principal interface.
public Principal getPrincipal()

AM does not reuse authentication module instances. This means that you can store information specific to the authentication process in the instance.

The implementation, SampleAuth.java, is shown below.

/**
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
 *
 * Copyright (c) 2011-2016 ForgeRock AS. All Rights Reserved
 *
 * The contents of this file are subject to the terms
 * of the Common Development and Distribution License
 * (the License). You may not use this file except in
 * compliance with the License.
 *
 * You can obtain a copy of the License at legal/CDDLv1.0.txt.
 * See the License for the specific language governing
 * permission and limitations under the License.
 *
 * When distributing Covered Code, include this CDDL
 * Header Notice in each file and include the License file at legal/CDDLv1.0.txt.
 * If applicable, add the following below the CDDL Header,
 * with the fields enclosed by brackets [] replaced by
 * your own identifying information:
 * "Portions Copyrighted [year] [name of copyright owner]"
 *
 */

package org.forgerock.openam.examples;

import java.security.Principal;
import java.util.Map;
import java.util.ResourceBundle;

import javax.security.auth.Subject;
import javax.security.auth.callback.Callback;
import javax.security.auth.callback.NameCallback;
import javax.security.auth.callback.PasswordCallback;
import javax.security.auth.login.LoginException;

import com.sun.identity.authentication.spi.AMLoginModule;
import com.sun.identity.authentication.spi.AuthLoginException;
import com.sun.identity.authentication.spi.InvalidPasswordException;
import com.sun.identity.authentication.util.ISAuthConstants;
import com.sun.identity.shared.datastruct.CollectionHelper;
import com.sun.identity.shared.debug.Debug;

/**
 * SampleAuth authentication module example.
 *
 * If you create your own module based on this example, you must modify all
 * occurrences of "SampleAuth" in addition to changing the name of the class.
 *
 * Please refer to OpenAM documentation for further information.
 *
 * Feel free to look at the code for authentication modules delivered with
 * OpenAM, as they implement this same API.
 */
public class SampleAuth extends AMLoginModule {

    // Name for the debug-log
    private final static String DEBUG_NAME = "SampleAuth";
    private final static Debug debug = Debug.getInstance(DEBUG_NAME);

    // Name of the resource bundle
    private final static String amAuthSampleAuth = "amAuthSampleAuth";

    // User names for authentication logic
    private final static String USERNAME = "demo";
    private final static String PASSWORD = "changeit";

    private final static String ERROR_1_USERNAME = "test1";
    private final static String ERROR_2_USERNAME = "test2";

    // Orders defined in the callbacks file
    private final static int STATE_BEGIN = 1;
    private final static int STATE_AUTH = 2;
    private final static int STATE_ERROR = 3;

    // Errors properties
    private final static String SAMPLE_AUTH_ERROR_1 = "sampleauth-error-1";
    private final static String SAMPLE_AUTH_ERROR_2 = "sampleauth-error-2";

    private Map<String, String> options;
    private ResourceBundle bundle;
    private Map<String, String> sharedState;

    public SampleAuth() {
        super();
    }


    /**
     * This method stores service attributes and localized properties for later
     * use.
     * @param subject
     * @param sharedState
     * @param options
     */
    @Override
    public void init(Subject subject, Map sharedState, Map options) {

        debug.message("SampleAuth::init");

        this.options = options;
        this.sharedState = sharedState;
        this.bundle = amCache.getResBundle(amAuthSampleAuth, getLoginLocale());
    }

    @Override
    public int process(Callback[] callbacks, int state) throws LoginException {

        debug.message("SampleAuth::process state: {}", state);

        switch (state) {

            case STATE_BEGIN:
                // No time wasted here - simply modify the UI and
                // proceed to next state
                substituteUIStrings();
                return STATE_AUTH;

            case STATE_AUTH:
                // Get data from callbacks. Refer to callbacks XML file.
                NameCallback nc = (NameCallback) callbacks[0];
                PasswordCallback pc = (PasswordCallback) callbacks[1];
                String username = nc.getName();
                String password = String.valueOf(pc.getPassword());

                //First errorstring is stored in "sampleauth-error-1" property.
                if (ERROR_1_USERNAME.equals(username)) {
                    setErrorText(SAMPLE_AUTH_ERROR_1);
                    return STATE_ERROR;
                }

                //Second errorstring is stored in "sampleauth-error-2" property.
                if (ERROR_2_USERNAME.equals(username)) {
                    setErrorText(SAMPLE_AUTH_ERROR_2);
                    return STATE_ERROR;
                }

                if (USERNAME.equals(username) && PASSWORD.equals(password)) {
                    debug.message("SampleAuth::process User '{}' " +
                            "authenticated with success.", username);
                    return ISAuthConstants.LOGIN_SUCCEED;
                }

                throw new InvalidPasswordException("password is wrong",
                        USERNAME);

            case STATE_ERROR:
                return STATE_ERROR;
            default:
                throw new AuthLoginException("invalid state");
        }
    }

    @Override
    public Principal getPrincipal() {
        return new SampleAuthPrincipal(USERNAME);
    }

    private void setErrorText(String err) throws AuthLoginException {
        // Receive correct string from properties and substitute the
        // header in callbacks order 3.
        substituteHeader(STATE_ERROR, bundle.getString(err));
    }

    private void substituteUIStrings() throws AuthLoginException {
        // Get service specific attribute configured in OpenAM
        String ssa = CollectionHelper.getMapAttr(options, "specificAttribute");

        // Get property from bundle
        String new_hdr = ssa + " " +
                bundle.getString("sampleauth-ui-login-header");
        substituteHeader(STATE_AUTH, new_hdr);

        replaceCallback(STATE_AUTH, 0, new NameCallback(
                bundle.getString("sampleauth-ui-username-prompt")));
        replaceCallback(STATE_AUTH, 1, new PasswordCallback(
                bundle.getString("sampleauth-ui-password-prompt"), false));
    }
}

10.2.1.5. The Sample Auth Principal

The implementation, SampleAuthPrincipal.java, is shown below.

/**
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
 *
 * Copyright (c) 2011-2016 ForgeRock AS. All Rights Reserved
 *
 * The contents of this file are subject to the terms
 * of the Common Development and Distribution License
 * (the License). You may not use this file except in
 * compliance with the License.
 *
 * You can obtain a copy of the License at legal/CDDLv1.0.txt.
 * See the License for the specific language governing
 * permission and limitations under the License.
 *
 * When distributing Covered Code, include this CDDL
 * Header Notice in each file and include the License file at legal/CDDLv1.0.txt.
 * If applicable, add the following below the CDDL Header,
 * with the fields enclosed by brackets [] replaced by
 * your own identifying information:
 * "Portions Copyrighted [year] [name of copyright owner]"
 *
 */

package org.forgerock.openam.examples;

import java.io.Serializable;
import java.security.Principal;

/**
 * SampleAuthPrincipal represents the user entity.
 */
public class SampleAuthPrincipal implements Principal, Serializable {
    private final static String COLON = " : ";

    private final String name;

    public SampleAuthPrincipal(String name) {

        if (name == null) {
            throw new NullPointerException("illegal null input");
        }

        this.name = name;
    }

    /**
     * Return the LDAP username for this SampleAuthPrincipal.
     *
     * @return the LDAP username for this SampleAuthPrincipal
     */
    @Override
    public String getName() {
        return name;
    }

    /**
     * Return a string representation of this SampleAuthPrincipal.
     *
     * @return a string representation of this
     *         TestAuthModulePrincipal.
     */
    @Override
    public String toString() {
        return new StringBuilder().append(this.getClass().getName())
                .append(COLON).append(name).toString();
    }

    /**
     * Compares the specified Object with this SampleAuthPrincipal
     * for equality. Returns true if the given object is also a
     *  SampleAuthPrincipal  and the two SampleAuthPrincipal have
     * the same username.
     *
     * @param o Object to be compared for equality with this
     *          SampleAuthPrincipal.
     * @return true if the specified Object is equal equal to this
     *         SampleAuthPrincipal.
     */
    @Override
    public boolean equals(Object o) {
        if (o == null) {
            return false;
        }

        if (this == o) {
            return true;
        }

        if (!(o instanceof SampleAuthPrincipal)) {
            return false;
        }
        SampleAuthPrincipal that = (SampleAuthPrincipal) o;

        if (this.getName().equals(that.getName())) {
            return true;
        }
        return false;
    }

    /**
     * Return a hash code for this SampleAuthPrincipal.
     *
     * @return a hash code for this SampleAuthPrincipal.
     */
    @Override
    public int hashCode() {
        return name.hashCode();
    }
}

10.2.1.6. The Sample Auth Service Configuration

AM requires that all authentication modules be configured by means of an AM service. At minimum, the service must include an authentication level attribute. Your module can access these configuration attributes in the options parameter passed to the init() method.

Some observations about the service configuration file follow in the list below.

  • The document type for a service configuration file is described in WEB-INF/sms.dtd where AM is deployed.

  • The service name is derived from the module name. The service name must have the following format:

    • It must start with either iPlanetAMAuth or sunAMAuth.

    • The module name must follow. The case of the module name must match the case of the class that implements the custom authentication module.

    • It must end with Service.

    In the Sample Auth service configuration, the module name is SampleAuth and the service name is iPlanetAMAuthSampleAuthService.

  • The service must have a localized description, retrieved from a properties file.

  • The i18nFileName attribute in the service configuration holds the default (non-localized) base name of the Java properties file. The i18nKey attributes indicate properties keys to string values in the Java properties file.

  • The authentication level attribute name must have the following format:

    • It must start with iplanet-am-auth-, sun-am-auth-, or forgerock-am-auth-.

    • The module name must follow, and must appear in lower case if the attribute name starts with iplanet-am-auth- or forgerock-am-auth-. If the attribute name starts with sun-am-auth-, it must exactly match the case of the module name as it appears in the service name.

    • It must end with -auth-level.

    In the Sample Auth service configuration, the authentication level attribute name is iplanet-am-auth-sampleauth-auth-level.

  • The Sample Auth service configuration includes an example sampleauth-service-specific-attribute, which can be configured through the AM console.

The service configuration file, amAuthSampleAuth.xml, is shown below. Save a local copy of this file, which you use when registering the module.

<?xml version="1.0" encoding="UTF-8"?>
<!--
   DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.

   Copyright (c) 2011-2016 ForgeRock AS.

   The contents of this file are subject to the terms
   of the Common Development and Distribution License
   (the License). You may not use this file except in
   compliance with the License.

   You can obtain a copy of the License at legal/CDDLv1.0.txt.
   See the License for the specific language governing
   permission and limitations under the License.

   When distributing Covered Code, include this CDDL
   Header Notice in each file and include the License file at legal/CDDLv1.0.txt.
   If applicable, add the following below the CDDL Header,
   with the fields enclosed by brackets [] replaced by
   your own identifying information:
   "Portions Copyrighted [year] [name of copyright owner]"
-->
<!DOCTYPE ServicesConfiguration
    PUBLIC "=//iPlanet//Service Management Services (SMS) 1.0 DTD//EN"
    "jar://com/sun/identity/sm/sms.dtd">

<ServicesConfiguration>
 <Service name="iPlanetAMAuthSampleAuthService" version="1.0">
  <Schema
   serviceHierarchy="/DSAMEConfig/authentication/iPlanetAMAuthSampleAuthService"
   i18nFileName="amAuthSampleAuth" revisionNumber="10"
   i18nKey="sampleauth-service-description" resourceName="sample">
   <Organization>
    <!-- Specify resourceName for a JSON-friendly property in the REST SMS -->
    <AttributeSchema name="iplanet-am-auth-sampleauth-auth-level" resourceName="authLevel"
     type="single" syntax="number_range" rangeStart="0" rangeEnd="2147483647"
     i18nKey="a500">
     <DefaultValues>
      <Value>1</Value>
     </DefaultValues>
    </AttributeSchema>

    <!-- No need for resourceName when the name is JSON-compatible -->
    <AttributeSchema name="specificAttribute"
     type="single" syntax="string" validator="no" i18nKey="a501" />

    <!--
     For Auth Modules, the parent Schema element specifies the REST SMS resourceName,
     and the nested SubSchema must have resourceName="USE-PARENT"
    -->
    <SubSchema name="serverconfig" inheritance="multiple" resourceName="USE-PARENT">
     <AttributeSchema name="iplanet-am-auth-sampleauth-auth-level" resourceName="authLevel"
      type="single" syntax="number_range" rangeStart="0" rangeEnd="2147483647"
      i18nKey="a500">
      <DefaultValues>
       <Value>1</Value>
      </DefaultValues>
     </AttributeSchema>

     <!-- No need for a DefaultValues element when the default is blank -->
     <AttributeSchema name="specificAttribute"
      type="single" syntax="string" validator="no" i18nKey="a501" />

    </SubSchema>
   </Organization>
  </Schema>
 </Service>
</ServicesConfiguration>

10.2.1.7. Building and Installing the Sample Auth Module

Build the module with Apache Maven, and install the module in AM.

For information on downloading and building AM sample source code, see How do I access and build the sample code provided for OpenAM 12.x, 13.x and AM (All versions)? in the Knowledge Base.

10.2.1.7.1. Installing the Module

Installing the sample authentication module consists of copying the .jar file to AM's WEB-INF/lib/ directory, registering the module with AM, and then restarting AM or the web application container where it runs.

  1. Copy the sample authentication module .jar file to WEB-INF/lib/ where AM is deployed.

    $ cp target/custom*.jar /path/to/tomcat/webapps/openam/WEB-INF/lib/
  2. Restart AM or the container in which it runs.

    For example if you deployed AM in Apache Tomcat, then you shut down Tomcat and start it again.

    $ /path/to/tomcat/bin/shutdown.sh
    $ /path/to/tomcat/bin/startup.sh
    $ tail -1 /path/to/tomcat/logs/catalina.out
    INFO: Server startup in 14736 ms

10.2.1.8. Configuring & Testing the Sample Auth Module

Authentication modules are registered as services with AM globally, and then set up for use in a particular realm. In this example, you set up the sample authentication module for use in the realm / (Top Level Realm).

Log in to the AM console as an administrator, such as amadmin, and browse to Realms > Top Level Realm > Authentication > Modules. Click Add Module to create an instance of the Sample Authentication Module. Name the module Sample.

Sample authentication module registration

Click Create, and then configure the authentication module as appropriate.

Sample authentication module configuration

Now that the module is configured, log out of the AM console.

Finally, try the module by specifying the Sample module. Browse to the login URL such as http://openam.example.com:8080/openam/XUI/?realm=/#login/&module=Sample, and then authenticate with user name demo and password changeit.

Sample authentication module login page

After authentication you are redirected to the end user page for the demo user. You can logout of the AM console, and then try to authenticate as the non-existent user test123 to see what the error handling looks like to the user.

10.2.2. Using Server-side Authentication Scripts in Authentication Modules

This section demonstrates how to use the default server-side authentication script. An authentication script can be called from a Scripted authentication module.

The default server-side authentication script only authenticates a subject when the current time on the AM server is between 09:00 and 17:00. The script also uses the logger and httpClient functionality provided in the scripting API.

To examine the contents of the default server-side authentication script in the AM console browse to Realms > Top Level Realm > Scripts, and then click Scripted Module - Server Side.

For general information about scripting in AM, see Appendix B, "About Scripting".

For information about APIs available for use when scripting authentication, see the following sections:

10.2.2.1. Preparing

AM requires a small amount of configuration before trying the example server-side authentication script. You must create an authentication module of the Scripted type, and then include it in an authentication chain, which can then be used when logging in to AM. You must also ensure the demo user has an associated postal address.

The procedures in this section are:

Procedure 10.5. To Create a Scripted Authentication Module that Uses the Default Server-side Authentication Script

In this procedure, create a Scripted Authentication module, and link it to the default server-side authentication script.

  1. Log in as an AM administrator, for example amadmin.

  2. Navigate to Realms > Top Level Realm > Authentication > Modules.

  3. On the Authentication Modules page, click Add Module.

  4. On the New Module page, enter a module name, such as myScriptedAuthModule, from the Type drop-down list, select Scripted Module, and then click Create.

  5. On the module configuration page:

    1. Uncheck the Client-side Script Enabled checkbox.

    2. From the Server-side Script drop-down list, select Scripted Module - Server Side.

    3. Click Save Changes.

Procedure 10.6. To Create an Authentication Chain that Uses a Scripted Authentication Module

In this procedure, create an authentication chain that uses a Data Store authentication module and the Scripted authentication module created in the previous procedure.

  1. Log in as an AM administrator, for example amadmin.

  2. Navigate to Realms > Top Level Realm > Authentication > Chains.

  3. On the Authentication Chains page, click Add Chain.

  4. On the Add Chain page, enter a name, such as myScriptedChain, and then click Create.

  5. On the Edit Chain tab, click Add a Module.

  6. In the New Module dialog box:

    1. From the Select Module drop-down list, select DataStore.

    2. From the Select Criteria drop-down list, select Required.

    3. Click OK.

    Note

    The Data Store authentication module checks the user credentials, whereas the Scripted authentication module does not check credentials, but instead only checks that the authentication request is processed during working hours. Without the Data Store module, the username in the Scripted authentication module cannot be determined. Therefore, do not configure the Scripted authentication module (server-side script) as the first module in an authentication chain, because it needs a username.

  7. On the Edit Chain tab, click Add Module.

  8. In the New Module dialog box:

    1. From the Select Module drop-down list, select the Scripted Module from the previous procedure, for example myScriptedAuthModule.

    2. From the Select Criteria drop-down list, select Required.

    3. Click OK.

    The resulting chain resembles the following:

    An example chain that uses the default server-side authentication script.
  9. On the Edit Chain tab, click Save Changes.

Procedure 10.7. To Add a Postal Address to the Demo User
  1. Log in as an AM administrator, for example amadmin.

  2. Navigate to Realms > Top Level Realm > Identities.

  3. On the Identities tab, click the demo user.

  4. In the Home Address field, enter a valid postal address, with lines separated by commas.

    For example:

    ForgeRock Inc., 201 Mission St #2900, San Francisco, CA 94105, USA

  5. Save your changes.

10.2.2.2. Trying the Default Server-side Authentication Script

This section shows how to log in using an authentication chain that contains a Scripted authentication module, which in turn uses the default server-side authentication script.

The default server-side authentication script gets the postal address of a user after they authenticate using a Data Store authentication module, and then makes an HTTP call to an external web service to determine the longitude and latitude of the address. Using these details, a second HTTP call is performed to get the local time at those coordinates. If that time is between two preset limits, authentication is allowed, and the user is given a session and redirected to the profile page.

Procedure 10.8. To Log in Using a Chain Containing a Scripted Authentication Module
  1. Log out of AM.

  2. In a browser, navigate to the AM login URL, and specify the authentication chain created in the previous procedure as the value of the service parameter.

    For example:

    https://openam.example.com:8443/openam/XUI/#login/&service=myScriptedChain
  3. Log in as user demo with password changeit.

    If login is successful, the user profile page appears. The script will also output messages, such as the following in the debug/Authentication log file:

    Starting scripted authentication
    amScript:02/27/2017 03:22:42:881 PM GMT: Thread[ScriptEvaluator-5,5,main]: TransactionId[7635cd7c-ea97-4be6-8694-9e2be8642d56-8581]
    User: demo
    amScript:02/27/2017 03:22:42:882 PM GMT: Thread[ScriptEvaluator-5,5,main]: TransactionId[7635cd7c-ea97-4be6-8694-9e2be8642d56-8581]
    User address: ForgeRock Inc., 201 Mission St #2900, San Francisco, CA 94105, USA
    amScript:02/27/2017 03:22:42:929 PM GMT: Thread[ScriptEvaluator-5,5,main]: TransactionId[7635cd7c-ea97-4be6-8694-9e2be8642d56-8581]
    User REST Call. Status: [Status: 200 OK]
    amScript:02/27/2017 03:27:31:646 PM GMT: Thread[ScriptEvaluator-7,5,main]: TransactionId[7635cd7c-ea97-4be6-8694-9e2be8642d56-8581]
    latitude:37.7914374 longitude:-122.3950694
    amScript:02/27/2017 03:27:31:676 PM GMT: Thread[ScriptEvaluator-7,5,main]: TransactionId[7635cd7c-ea97-4be6-8694-9e2be8642d56-8581]
    User REST Call. Status: [Status: 200 OK]
    amScript:02/27/2017 03:27:31:676 PM GMT: Thread[ScriptEvaluator-7,5,main]: TransactionId[7635cd7c-ea97-4be6-8694-9e2be8642d56-8581]
    Current time at the users location: 10
    amScript:02/27/2017 03:27:31:676 PM GMT: Thread[ScriptEvaluator-7,5,main]: TransactionId[7635cd7c-ea97-4be6-8694-9e2be8642d56-8581]
    Authentication allowed!
    amLoginModule:02/27/2017 03:27:31:676 PM GMT: Thread[http-nio-8080-exec-4,5,main]: TransactionId[7635cd7c-ea97-4be6-8694-9e2be8642d56-8581]
    Login NEXT State : -1
    amLoginModule:02/27/2017 03:27:31:676 PM GMT: Thread[http-nio-8080-exec-4,5,main]: TransactionId[7635cd7c-ea97-4be6-8694-9e2be8642d56-8581]
    SETTING Module name.... :myScriptedAuthModule
    amAuth:02/27/2017 03:27:31:676 PM GMT: Thread[http-nio-8080-exec-4,5,main]: TransactionId[7635cd7c-ea97-4be6-8694-9e2be8642d56-8581]
    Module name is .. myScriptedAuthModule
    amAuth:02/27/2017 03:27:31:676 PM GMT: Thread[http-nio-8080-exec-4,5,main]: TransactionId[7635cd7c-ea97-4be6-8694-9e2be8642d56-8581]
    successModuleSet is : [DataStore, myScriptedAuthModule]
    amJAAS:02/27/2017 03:27:31:676 PM GMT: Thread[http-nio-8080-exec-4,5,main]: TransactionId[7635cd7c-ea97-4be6-8694-9e2be8642d56-8581]
    login success

    Tip

    The default server-side authentication script outputs log messages at the message and error level.

    AM does not log debug messages from scripts by default. You can configure AM to log such messages by setting the debug log level for the amScript service. For details, see Section 9.2.3, "Debug Logging By Service" in the Setup and Maintenance Guide.

  4. (Optional) To test that the script is being used as part of the login process, edit the script to alter the times when authentication is allowed:

    1. Log out the demo user.

    2. Log in as an AM administrator, for example amadmin.

    3. Navigate to Realms > Top Level Realm > Scripts > Scripted Module - Server Side.

    4. In the script, swap the values for START_TIME and END_TIME, for example:

      var START_TIME = 17;
      var END_TIME   = 9; //
    5. Click Save.

    6. Repeat steps 1, 2, and 3 above, logging into the module as the demo user as before. The authentication result will be the opposite of the previous result, as the allowed times have inverted.

10.2.3. Creating Post-Authentication Plugins for Chains

Post-authentication plugins (PAP) let you include custom processing at the following places in the authentication cycle:

  • At the end of the authentication process, immediately before a user is authenticated

  • When a user logs out of an AM session

A common use of post-authentication plugins is to set state information in the session object in conjunction with web or Java agents. The post-authentication plugin sets custom session properties, and then the web or Java agent injects the custom properties into the header sent to the protected application.

Two issues should be considered when writing a post-authentication plugin for an AM deployment that uses client-based sessions:

Cookie size

You can set an unlimited number of session properties in a post authentication plugin. When AM creates a client-based session, it writes the session properties into the session cookie, increasing the size of the cookie. Very large session cookies can exceed browser limitations. Therefore, when implementing a post-authentication plugin in a deployment with client-based sessions, be sure to monitor the session cookie size and verify that you have not exceeded browser cookie size limits.

For more information about client-based session cookies, see Section 1.9.2, "Session Cookies".

Cookie security

The AM administrator secures custom session properties in sessions residing in the CTS token store by using firewalls and other typical security techniques.

However, when using client-based sessions, custom session properties are written in cookies and reside on end users' systems. Cookies can be long-lasting and might represent a security issue if any session properties are of a sensitive nature. When developing a post authentication plugin for a deployment that uses client-based sessions, be sure that you are aware of the measures securing the session contained within the cookie.

For more information about client-based session cookie security, see Section 6.2.3, "Configuring Client-Based Session and Authentication Session Security".

This section explains how to create a post-authentication plugin.

10.2.3.1. Designing Your Post-Authentication Plugin

Your post-authentication plugin class implements the AMPostAuthProcessInterface interface, and in particular the following three methods.

public void onLoginSuccess(
  Map requestParamsMap,
  HttpServletRequest request,
  HttpServletResponse response,
  SSOToken token
) throws AuthenticationException

public void onLoginFailure(
  Map requestParamsMap,
  HttpServletRequest request,
  HttpServletResponse response
) throws AuthenticationException

public void onLogout(
  HttpServletRequest request,
  HttpServletResponse response,
  SSOToken token
) throws AuthenticationException

AM calls the onLoginSuccess() and onLoginFailure() methods immediately before informing the user of login success or failure, respectively. AM calls the onLogout() method only when the user actively logs out, not when a user's session times out. See the ForgeRock Access Management Java SDK API Specification for reference.

These methods can perform whatever processing you require. Yet, know that AM calls your methods synchronously as part of the authentication process. Therefore, if your methods take a long time to complete, you will keep users waiting. Minimize the processing done in your post-authentication methods.

Important

Implementing a post-authentication processing plugin in the top level realm can have unexpected effects. OpenAM invokes a post-authentication plugin when the plugin is configured in the top level realm, which will then run for all types of authentication during startup, including user logins and internal administrative logins. The best practice first and foremost is to configure end-users to only log into subrealms, while administrators only log into the top level realm. If you need to execute the post-authentication plugin for administrative logins, make sure that the plugin can also handle internal authentications.

An alternate solution is to configure the post-authentication plugin on a per authentication chain basis, which can be configured separately for user logins or internal administrative logins.

Post-authentication plugins must be stateless: they do not maintain state between login and logout. Store any information that you want to save between login and logout in a session property. AM stores session properties in the CTS token store after login, and retrieves them from the token store as part of the logout process.

10.2.3.2. Building Your Sample Post-Authentication Plugin

The following example post-authentication plugin sets a session property during successful login, writing to its debug log if the operation fails.

package com.forgerock.openam.examples;

import java.util.Map;

import com.iplanet.sso.SSOException;
import com.iplanet.sso.SSOToken;

import com.sun.identity.authentication.spi.AMPostAuthProcessInterface;
import com.sun.identity.authentication.spi.AuthenticationException;
import com.sun.identity.shared.debug.Debug;

import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;

public class SamplePAP implements AMPostAuthProcessInterface {
    private final static String PROP_NAME = "MyProperty";
    private final static String PROP_VALUE = "MyValue";
    private final static String DEBUG_FILE = "SamplePAP";

    protected Debug debug = Debug.getInstance(DEBUG_FILE);

    public void onLoginSuccess(
            Map requestParamsMap,
            HttpServletRequest request,
            HttpServletResponse response,
            SSOToken token
    ) throws AuthenticationException {
        try {
            token.setProperty(PROP_NAME, PROP_VALUE);
        } catch (SSOException e) {
            debug.error("Unable to set property");
        }
    }

    public void onLoginFailure(
            Map requestParamsMap,
            HttpServletRequest request,
            HttpServletResponse response
    ) throws AuthenticationException {
        // Not used
    }

    public void onLogout(
            HttpServletRequest request,
            HttpServletResponse response,
            SSOToken token
    ) throws AuthenticationException {
        // Not used
    }
}

If you have not already done so, download and build the sample code.

For information on downloading and building AM sample source code, see How do I access and build the sample code provided for OpenAM 12.x, 13.x and AM (All versions)? in the Knowledge Base.

In the sources, you find the following files:

pom.xml

Apache Maven project file for the module

This file specifies how to build the sample post-authentication plugin, and also specifies its dependencies on AM components and on the Servlet API.

src/main/java/com/forgerock/openam/examples/SamplePAP.java

Core class for the sample post-authentication plugin

Once built, copy the .jar to the WEB-INF/lib directory where you deployed AM.

$ cp target/*.jar /path/to/tomcat/webapps/openam/WEB-INF/lib/

Restart AM or the container in which it runs.

10.2.3.3. Configuring Your Post-Authentication Plugin

You can associate post-authentication plugins with realms or services (authentication chains). Where you configure the plugin depends on the scope to which the plugin should apply:

  • Plugins configured at the realm level are executed when authenticating to any authentication chain in the realm, provided the authentication chain does not have an associated plugin.

  • Plugins configured at the service level are executed if that authentication chain is used for authentication. Any plugins configured at the realm level will not execute.

In OpenAM Console, navigate to Realms > Realm Name > Authentication > Settings > Post Authentication Processing. In the Authentication Post Processing Classes list, add the sample plugin class, com.forgerock.openam.examples.SamplePAP, and then click Save.

Alternatively, you can configure sample plugin for the realm by using the ssoadm command.

$ ssoadm set-svc-attrs \
 --adminid amadmin \
 --password-file /tmp/pwd.txt \
 --servicename iPlanetAMAuthService \
 --realm /myRealm \
 --attributevalues iplanet-am-auth-post-login-process-class=
 com.forgerock.openam.examples.SamplePAP
iPlanetAMAuthService under /myRealm was
 modified.

10.2.3.4. Testing Your Post-Authentication Plugin

To test the sample post-authentication plugin, login successfully to AM in the scope where the plugin is configured. For example, if you configured your plugin for the realm, /myRealm, specify the realm in the login URL.

http://openam.example.com:8080/openam/XUI/?realm=/myRealm#login

Although you will not notice anywhere in the user interface that AM calls your plugin, a web or Java agent or custom client code could retrieve the session property that your plugin added to the user session.

10.3. Customizing CTS-Based Session Quota Exhaustion Actions

This section demonstrates a custom session quota exhaustion action plugin. AM calls a session quota exhaustion action plugin when a user tries to open more CTS-based sessions than their quota allows. Note that session quotas are not available for client-based sessions.

You only need a custom session quota exhaustion action plugin if the built-in actions are not flexible enough for your deployment. See Section 6.1.1, "Implementing Session Quotas".

10.3.1. Creating & Installing a Custom Session Quota Exhaustion Action

You build custom session quota exhaustion actions into a .jar that you then plug in to AM. You must also add your new action to the Session service configuration, and restart AM in order to be able to configure it for your use.

Your custom session quota exhaustion action implements the com.iplanet.dpro.session.service.QuotaExhaustionAction interface, overriding the action method. The action method performs the action when the session quota is met, and returns true only if the request for a new session should not be granted.

The example in this section simply removes the first session it finds as the session quota exhaustion action.

package org.forgerock.openam.examples.quotaexhaustionaction;

import static org.forgerock.openam.session.SessionConstants.SESSION_DEBUG;
import com.google.inject.Key;
import com.google.inject.name.Names;
import com.iplanet.dpro.session.SessionException;
import com.iplanet.dpro.session.SessionID;
import com.iplanet.dpro.session.service.InternalSession;
import com.iplanet.dpro.session.service.QuotaExhaustionAction;
import com.sun.identity.shared.debug.Debug;
import org.forgerock.guice.core.InjectorHolder;
import org.forgerock.openam.session.Session;
import org.forgerock.openam.session.clientsdk.SessionCache;

import javax.inject.Inject;
import java.util.Map;

/**
 * This is a sample {@link QuotaExhaustionAction} implementation,
 * which randomly kills the first session it finds.
 */
public class SampleQuotaExhaustionAction implements QuotaExhaustionAction {

    private static Debug debug = InjectorHolder.getInstance(Key.get(Debug.class, Names.named(SESSION_DEBUG)));

    private final SessionCache sessionCache;

    public SampleQuotaExhaustionAction() {
        this.sessionCache = InjectorHolder.getInstance(SessionCache.class);
    }

    @Inject
    public SampleQuotaExhaustionAction(SessionCache sessionCache) {
        this.sessionCache = sessionCache;
    }

    /**
     * Check if the session quota for a given user has been exhausted and
     * if so perform the necessary actions. This implementation randomly
     * destroys the first session it finds.
     *
     * @param is               The InternalSession to be activated.
     * @param existingSessions All existing sessions that belong to the same
     *                         uuid (Map:sid->expiration_time).
     * @return true If the session activation request should be rejected,
     *              otherwise false.
     */
    @Override
    public boolean action(
            InternalSession is,
            Map<String, Long> existingSessions) {
        for (Map.Entry<String, Long> entry : existingSessions.entrySet()) {
            try {
                // Get a Session from the cache based on the session ID, and destroy it.
                SessionID sessionId = new SessionID(entry.getKey());
                Session session = sessionCache.getSession(sessionId);
                session.destroySession(sessionId);
                // Only destroy the first session.
                break;
            } catch (SessionException se) {
                if (debug.messageEnabled()) {
                    debug.message("Failed to destroy existing session.", se);
                }
                // In this case, deny the session activation request.
                return true;
            }
        }
        return false;
    }
}

If you have not already done so, download and build the sample code.

For information on downloading and building AM sample source code, see How do I access and build the sample code provided for OpenAM 12.x, 13.x and AM (All versions)? in the Knowledge Base.

In the sources, you find the following files:

pom.xml

Apache Maven project file for the module

This file specifies how to build the sample plugin, and also specifies its dependencies on AM components and on the Servlet API.

src/main/java/org/forgerock/openam/examples/quotaexhaustionaction/SampleQuotaExhaustionAction.java

Core class for the sample quota exhaustion action plugin

Once built, copy the .jar to WEB-INF/lib/ where AM is deployed.

$ cp target/*.jar /path/to/tomcat/webapps/openam/WEB-INF/lib/

Using the ssoadm command, update the Session Service configuration:

$ ssoadm \
 set-attr-choicevals \
 --adminid amadmin \
 --password-file /tmp/pwd.txt \
 --servicename iPlanetAMSessionService \
 --schematype Global \
 --attributename iplanet-am-session-constraint-handler \
 --add \
 --choicevalues myKey=\
org.forgerock.openam.examples.quotaexhaustionaction.SampleQuotaExhaustionAction
Choice Values were set.

Extract amSession.properties and if necessary the localized versions of this file from openam-core-6.0.0.5.jar to WEB-INF/classes/ where AM is deployed. For example, if AM is deployed under /path/to/tomcat/webapps/openam, then you could run the following commands.

$ cd /path/to/tomcat/webapps/openam/WEB-INF/classes/
$ jar -xvf ../lib/openam-core-6.0.0.5.jar amSession.properties
inflated: amSession.properties

Add the following line to amSession.properties.

myKey=Randomly Destroy Session

Restart AM or the container in which it runs.

You can now use the new session quota exhaustion action. In the AM console, navigate to Configure > Global Services, click Session, scroll to Resulting behavior if session quota exhausted, and then choose an option.

Before moving to your test and production environments, be sure to add your .jar file and updates to amSession.properties into a custom .war file that you can then deploy. You must still update the Session service configuration in order to use your custom session quota exhaustion action.

10.3.2. Listing Session Quota Exhaustion Actions

List session quota exhaustion actions by using the ssoadm command:

$ ssoadm \
 get-attr-choicevals \
 --adminid amadmin \
 --password-file /tmp/pwd.txt \
 --servicename iPlanetAMSessionService \
 --schematype Global \
 --attributename iplanet-am-session-constraint-handler

I18n Key                  Choice Value
------------------------- ---...-----------------------------------------
choiceDestroyOldSession   org...session.service.DestroyOldestAction
choiceDenyAccess          org...session.service.DenyAccessAction
choiceDestroyNextExpiring org...session.service.DestroyNextExpiringAction
choiceDestroyAll          org...session.service.DestroyAllAction
myKey                     org...examples...SampleQuotaExhaustionAction

10.3.3. Removing a Session Quota Exhaustion Action

Remove a session quota exhaustion action by using the ssoadm command:

$ ssoadm \
 remove-attr-choicevals \
 --adminid amadmin \
 --password-file /tmp/pwd.txt \
 --servicename iPlanetAMSessionService \
 --schematype Global \
 --attributename iplanet-am-session-constraint-handler \
 --choicevalues \
 org.forgerock.openam.examples.quotaexhaustionaction.SampleQuotaExhaustionAction
Choice Values were removed.

Chapter 11. Reference

This reference section covers settings and the scripting API relating to authentication in AM.

11.1. Core Authentication Attributes

Every AM realm has a set of authentication properties that applies to all authentication performed to that realm. The settings are referred to as core authentication attributes.

To configure core authentication attributes for an entire AM deployment, navigate to Configure > Authentication in the AM console, and then click Core Attributes.

To override the global core authentication configuration in a realm, navigate to Realms > Realm Name > Authentication > Settings in the AM console. Note that when you configure core authentication attributes in a realm, the Global Attributes tab does not appear.

ssoadm service name: iPlanetAMAuthService

11.1.1. Global Attributes

The following properties are available under the Global Attributes tab:

Pluggable Authentication Module Classes

Lists the authentication modules classes available to AM. If you have custom authentication modules, add classes to this list that extend from the com.sun.identity.authentication.spi.AMLoginModule class.

For more information about custom authentication modules, see Section 10.2.1, "Creating a Custom Authentication Module".

ssoadm attribute: iplanet-am-auth-authenticators

LDAP Connection Pool Size

Sets a minimum and a maximum number of LDAP connections to be used by any authentication module that connects to a specific directory server. This connection pool is different than the SDK connection pool configured in serverconfig.xml file.

Format is host:port:minimum:maximum.

This attribute is for LDAP and Membership authentication modules only.

ssoadm attributes: iplanet-am-auth-ldap-connection-pool-size

Default LDAP Connection Pool Size

Sets the default minimum and maximum number of LDAP connections to be used by any authentication module that connects to any directory server. This connection pool is different than the SDK connection pool configured in serverconfig.xml file.

Format is minimum:maximum.

When tuning for production, start with 10 minimum, 65 maximum. For example, 10:65.

This attribute is for LDAP and Membership authentication modules only.

ssoadm attributes: iplanet-am-auth-ldap-connection-pool-default-size

Remote Auth Security

When enabled, AM requires the authenticating application to send its SSO token. This allows AM to obtain the username and password associated with the application.

ssoadm attribute: sunRemoteAuthSecurityEnabled

Keep Post Process Objects for Logout Processing

When enabled, AM stores instances of post-processing classes into the user session. When the user logs out, the original post-processing classes are called instead of new instances. This may be required for special logout processing.

Enabling this setting increases the memory usage of AM.

ssoadm attribute: sunAMAuthKeepPostProcessInstances

11.1.2. Core

The following properties are available under the Core tab:

Administrator Authentication Configuration

Specifies the default authentication chain used when an administrative user, such as amAdmin, logs in to the AM console.

ssoadm attribute:iplanet-am-auth-admin-auth-module

Organization Authentication Configuration

Specifies the default authentication chain used when a non-administrative user logs in to AM.

ssoadm attribute:iplanet-am-auth-org-config

11.1.3. User Profile

The following properties are available under the User Profile tab:

User Profile

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

true. Dynamic.

After successful authentication, AM creates a user profile if one does not already exist. AM then issues the SSO token. AM creates the user profile in the user data store configured for the realm.

createAlias. Dynamic with User Alias.

After successful authentication, AM creates a user profile that contains the User Alias List attribute, which defines one or more aliases for mapping a user's multiple profiles.

ignore. Ignored.

After successful authentication, AM issues an SSO token regardless of whether a user profile exists in the data store. The presence of a user profile is not checked.

Warning

Any functionality which needs to map values to profile attributes, such as SAML or OAuth 2.0, will not operate correctly if the User Profile property is set to ignore.

false. Required.

After successful authentication, the user must have a user profile in the user data store configured for the realm in order for AM to issue an SSO token.

ssoadm attribute: iplanet-am-auth-dynamic-profile-creation. Set this attribute's value to one of the following: true, createAlias, ignore, or false.

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 AM 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 in the Release Notes.

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

Alias Search Attribute Name

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

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

Note

If the Alias Search Attribute Name property is empty, AM 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 AM 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

11.1.4. Account Lockout

The following properties are available under the Account Lockout tab:

Login Failure Lockout Mode

When enabled, AM deactivates the LDAP attribute defined in the Lockout Attribute Name property in the user's profile upon login failure. 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

Specifies 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 AM 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 AM 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 AM 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. Although the field appears empty in the AM console, AM stores this data in the sunAMAuthInvalidAttemptsDataAttrName attribute defined in the sunAMAuthAccountLockout objectclass by default.

ssoadm attribute: sunAMAuthInvalidAttemptsDataAttrName

Store Invalid Attempts in Data Store

When enabled, AM stores the 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 AM.

Enable this property to track invalid log in attempts when using CTS-based or client-based authentication sessions.

ssoadm attribute: sunStoreInvalidAttemptsInDS

11.1.5. General

The following properties are available under the General tab:

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 AM to conduct a second lookup if the first lookup fails. The possible values are:

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.

Default: Agent and User.

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. AM supports account lockout and password changes. AM 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 AM instance. If you do not build a .jar file, add the class files under WEB-INF/classes.

ssoadm attribute: sunAMUserStatusCallbackPlugins

Use Client-Based Sessions

When enabled, AM assigns client-based sessions to users authenticating to this realm. Otherwise, AM users authenticating to this realm are assigned CTS-based sessions.

For more information about sessions, see Section 1.9, "About Sessions".

ssoadm attribute: openam-auth-stateless-sessions

Two Factor Authentication Mandatory

When enabled, users authenticating to a chain that includes a ForgeRock Authenticator (OATH) module are always required to perform authentication using a registered device before they can access AM. 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.

Note

The Two Factor Authentication Mandatory property only applies to modules within authentication chains, and does not affect nodes within authentication trees.

ssoadm attribute: forgerockTwoFactorAuthMandatory

Default Authentication Level

Specifies the default authentication level for authentication modules.

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

11.1.6. Trees

The following properties are available under the Trees tab:

Authentication session state management scheme

Specifies the location where AM stores authentication sessions.

Possible values are:

  • CTS. AM stores authentication sessions in the CTS token store.

  • JWT. AM sends the authentication session to the client as a JWT.

  • In-Memory. AM stores authentication sessions in its memory.

Default: JWT (new installations), In-Memory (after upgrade)

ssoadm attribute: openam-auth-authentication-sessions-state-management-scheme

Max duration (minutes)

Specifies the duration of the authentication session in minutes.

Default: 5

ssoadm attribute: openam-auth-authentication-sessions-max-duration

Enable whitelisting

When enabled, AM whitelists authentication sessions to protect them against replay attacks.

Default: Disabled

ssoadm attribute: openam-auth-authentication-sessions-whitelist

11.1.7. Security

The following properties are available under the Security tab:

Module Based Authentication

When enabled, users can 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 key pair alias in the AM keystore to use for encrypting persistent cookies.

Default: test

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

Zero Page Login

When enabled, AM allows users to authenticate using only GET request parameters without showing a login screen.

Caution

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

AM 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

Lists the HTTP referer URLs for which AM 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.

When zero page login is enabled, including the URLs for the pages from which to allow zero page login will provide some mitigation against Login Cross-Site Request Forgery (CSRF) attacks. 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?

When enabled, allows zero page login for requests without an HTTP Referer request header. Zero page login must also be enabled.

Enabling this setting reduces the risk of login CSRF attacks with zero page login enabled, but may potentially deny legitimate requests.

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

Organization Authentication Signing Secret

Specifies a cryptographically-secure random-generated HMAC shared secret for signing RESTful authentication requests. When users attempt to authenticate to the XUI, AM signs a JSON Web Token (JWT) containing this shared secret. The JWT contains the authentication session ID, realm, and authentication index type value, but does not contain the user's credentials.

When modifying this value, ensure the new shared secret is Base-64 encoded and at least 128 bits in length.

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

11.1.8. Post Authentication Processing

The following properties are available under the Post Authentication Processing tab:

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

A .jar file containing the post processing class belongs in the WEB-INF/lib directory of the deployed AM 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 AM .war file.

For information on creating post-authentication plugins, see Section 10.2.3, "Creating Post-Authentication Plugins for Chains".

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

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 configured for client-based 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 client-based session cookies, see Section 1.9.2, "Session Cookies".

ssoadm attribute: sunAMUserAttributesSessionMapping

11.2. Authentication Module Properties

This section provides a reference to configuration properties for AM authentication modules.

11.2.1. Active Directory Module Properties

ssoadm service name: sunAMAuthADService

Primary Active Directory Server, Secondary Active Directory Server

Specify the primary and secondary Active Directory server(s). AM attempts to contact the primary server(s) first, If no primary server is available, then AM attempts to contact the secondary server(s).

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

To allow users to change passwords through AM, Active Directory requires that you connect over SSL. The default port for LDAP is 389. If you are connecting to Active Directory over SSL, the default port for LDAP/SSL is 636.

For SSL or TLS security, enable the SSL/TLS Access to Active Directory Server property. Make sure that AM can trust the Active Directory certificate when using this option.

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

Both properties may take a single value in the form of server:port, or more than one value in the form of openam_full_server_name | server:port; thus, allowing more than one primary or secondary remote server, respectively.

Assuming a multi-data center environment, AM determines priority within the primary and secondary remote servers as follows:

  • Every LDAP server that is mapped to the current AM instance has highest priority.

    For example, if you are connected to openam1.example.com and ldap1.example.com is mapped to that AM instance, then AM uses ldap1.example.com.

  • Every LDAP server that was not specifically mapped to a given AM instance has the next highest priority.

    For example, if you have another LDAP server, ldap2.example.com, that is not connected to a specific AM server and if ldap1.example.com is unavailable, AM connects to the next highest priority LDAP server, ldap2.example.com.

  • LDAP servers that are mapped to different AM 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

Specifies the base DN from which AM searches for users to authenticate.

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

Specify the user and password to authenticate to Active Directory.

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

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,AM-deploy-base, where AM-deploy-base was set during AM 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 AM 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, AM 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 AM 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 AM 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

Maps internal attribute names used by AM to external attribute names from Active Directory for dynamic profile creation. Values are of the format internal_attr1|external_attr1.

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

Trust All Server Certificates

When enabled, the module trusts all server certificates, including self-signed certificates.

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

LDAP Connection Heartbeat Interval

Specifies how often AM 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. Possible values are SECONDS, MINUTES, and HOURS.

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

LDAP operations timeout

Defines the timeout in milliseconds that AM 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

11.2.2. Adaptive Risk Authentication Module Properties

ssoadm service name: sunAMAuthAdaptiveService

11.2.2.1. General

The following properties are available under the General tab:

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

Sets the risk threshold score. If the sum of the scores is greater than the threshold, the Adaptive Risk module fails.

Default: 1

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

11.2.2.2. Failed Authentications

The following properties are available under the Failed Authentications tab:

Failed Authentication Check

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

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

Score

Sets the 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 enabled, adds the score to the total score if the user passes the Failed Authentication Check.

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

11.2.2.3. IP Address Range

The following properties are available under the IP Address Range tab:

IP Range Check

When enabled, checks 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, (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

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

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

Invert Result

When enabled, adds the Score to the total score if the user passes the IP Range Check.

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

11.2.2.4. IP Address History

The following properties are available under the IP Address History tab:

IP History Check

When enabled, checks whether the client IP address matches one of the known values stored on the profile attribute you specify. This check therefore requires that AM 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

Specifies the name of the user profile attribute in 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 AM schema updates.

Default: iphistory

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

Save Successful IP Address

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

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

Score

Sets the 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 enabled, adds the Score to the total score if the user passes the IP History Check.

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

11.2.2.5. Known Cookie

The following properties are available under the Known Cookie tab:

Cookie Value Check

When enabled, checks 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 AM 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 AM checks. If no value is specified, AM does not check the cookie value.

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

Save Cookie Value on Successful Login

When enabled, saves 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

Sets the 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 enabled, adds the Score to the total score if the user passes the Cookie Value Check.

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

11.2.2.6. Device Cookie

The following properties are available under the Device Cookie tab:

Device Registration Cookie Check

When enabled, the cookie check passes if the client request contains the cookie specified in Cookie Name.

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, saves 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

Sets the 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 enabled, adds the Score to the total score if the user passes the Device Registration Cookie Check.

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

11.2.2.7. Time Since Last Login

The following properties are available under the Time Since Last Login tab:

Time since Last login Check

When enabled, checks 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, saves 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

Sets the 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 enabled, adds 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

11.2.2.8. Profile Attribute

The following properties are available under the Profile Attribute tab:

Profile Risk Attribute check

When enabled, checks 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

Sets the 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 enabled, adds the Score to the total score if the user passes the Profile Risk Attribute Check.

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

11.2.2.9. Geo Location

The following properties are available under the Geo Location tab:

Geolocation Country Code Check

When enabled, checks 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 AM. 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 enabled, adds the Score to the total score if the user passes the Geolocation Country Code Check.

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

11.2.2.10. Request Header

The following properties are available under the Request Header tab:

Request Header Check

When enabled, checks 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 enabled, adds the Score to the total score if the user passes the Request Header Check.

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

11.2.3. Anonymous Authentication Module Properties

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

When enabled, 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, AM 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

11.2.4. Certificate Authentication Module Properties

ssoadm service name: iPlanetAMAuthCertService

Match Certificate in LDAP

When enabled, AM 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, AM 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

Specifies parameters to be included in any HTTP CRL call to the CA that issued the certificate.

This property supports key pairs of values separated by commas, for example, param1=value1,param2=value2.

If the client or CA contains the Issuing Distribution Point Extension, AM uses this information to retrieve the CRL from the distribution point.

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

Match CA Certificate to CRL

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

ssoadm attribute: sunAMValidateCACert

Cache CRLs in memory

When enabled, AM caches CRLs.

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

Update CA CRLs from CRLDistributionPoint

When enabled, AM updates the CRLs stored in the LDAP directory store.

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

OCSP Validation

When enabled, AM checks the revocation status of certificates using the Online Certificate Status Protocol (OCSP).

You must configure OSCP for AM 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 that holds users; certificates. The property has the format ldap_server:port, for example, ldap1.example.com:636. To configure a secure connection, enable the Use SSL/TLS for LDAP Access property.

AM servers can be associated with LDAP servers by writing multiple chains with the format openam_server|ldapserver:port, for example, openam.example.com|ldap1.example.com:636.

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. To associate AM servers with§ different search base DNs, use the format openam_server|base_dn, for example, openam.example.com|dc=example,dc=com openam1.test.com|dc=test, dc=com

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

LDAP Server Authentication User, LDAP Server Authentication Password

If AM stores attributes in the LDAP directory, for example to manage account lockout, or if the LDAP directory requires that AM authenticate in order to read users' attributes, then AM 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, AM 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

Valid values: subject DN, subject CN, subject UID, email address, other, and none.

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

Specifies how to look up the user profile:

  • Let the property default to none to give preference to the Certificate Field Used to Access User Profile or Other Certificate Field Used to Access User Profile attributes when looking up the user profile.

  • Select RFC822Name if you want AM to look up the user profile from an RFC 822 style name.

  • Select UPN if you want AM to look up the user profile as the User Principal Name attribute 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 AM, such as load balancers doing SSL termination.

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

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 AM, the administrator must specify the header name in this attribute.

ssoadm attribute: sunAMHttpParamName

Use only Certificate from HTTP request header

When enabled, AM always uses the client certificate from the HTTP header rather than the certificate the servlet container receives during the SSL handshake.

Default: false

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

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

11.2.5. Data Store Authentication Module Properties

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

11.2.6. Device ID (Match) Authentication Module Properties

ssoadm service name: iPlanetAMAuthDeviceIdMatchService

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, Server-Side Script

Specify the client-side and server-side Javascript scripts to use with the Device Id (Match) module.

To view and modify the contents of the scripts, navigate to Realms > Realm Name > Scripts and select the name of the script.

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

11.2.7. Device ID (Save) Authentication Module Properties

ssoadm service name: iPlanetAMAuthDeviceIdSaveService

Automatically store new profiles

When enabled, AM assumes user consent to store new profiles. After successful HOTP confirmation, AM 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

11.2.8. Federation Authentication Module Properties

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

11.2.9. Amster Authentication Module Properties

amster service name: iPlanetAMAuthAmsterService

Authorized Keys

Specifies the location of the authorized_keys file that contains the private and public keys used to validate remote amster client connections.

The default location for the authorized_keys file is the /path/to/openam/ path. Its content is similar to an OpenSSH authorized_keys file.

amster attribute: forgerock-am-auth-amster-authorized-keys

Enabled

When enabled, allows amster clients to authenticate using PKI. When disabled, allows amster clients to authenticate using interactive login only.

amster attribute: forgerock-am-auth-amster-enabled

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.

amster attribute: forgerock-am-auth-amster-auth-level

11.2.10. ForgeRock Authenticator (OATH) Authentication Module Properties

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

One Time Password Max Retry

The number of times entry of the OTP may be attempted. Minimum is 1, maximum is 10.

Default: 3

ssoadm attribute: forgerock-oath-max-retry

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

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

11.2.11. ForgeRock Authenticator (Push) Authentication Module Properties

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

11.2.12. ForgeRock Authenticator (Push) Registration Authentication Module Properties

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

11.2.13. HOTP Authentication Module Properties

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

Specifies the class the HOTP module uses to send SMS or email messages. Specify a class that implements the com.sun.identity.authentication.modules.hotp.SMSGateway interface to customize the SMS gateway implementation.

ssoadm attribute: sunAMAuthHOTPSMSGatewayImplClassName

Mail Server Host Name

Specifies the hostname of the mail server supporting SMTP for electronic mail.

ssoadm attribute: sunAMAuthHOTPSMTPHostName

Mail Server Host Port

Specifies the outgoing mail server port. The default port is 25, 465 (when connecting over SSL), or 587 (for StartTLS).

ssoadm attribute: sunAMAuthHOTPSMTPHostPort

Mail Server Authentication Username

Specifies the username for AM to connect to the mail server.

ssoadm attribute: sunAMAuthHOTPSMTPUserName

Mail Server Authentication Password

Specifies the password for AM to connect to the mail server.

ssoadm attribute: sunAMAuthHOTPSMTPUserPassword

Mail Server Secure Connection

Specifies whether to connect to the mail server securely. If enabled, AM must be able to trust the server certificate.

The possible values for this property are:

SSL
Non SSL
Start TLS

ssoadm attribute: sunAMAuthHOTPSMTPSSLEnabled

Email From Address

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

ssoadm attribute: sunAMAuthHOTPSMTPFromAddress

One-Time Password Validity Length (in minutes)

Specifies the amount of time, in minutes, the one-time passwords are valid after they are generated. The default is 5 minutes.

ssoadm attribute: sunAMAuthHOTPPasswordValidityDuration

One-Time Password Length

Sets the length of one-time passwords.

ssoadm attribute: sunAMAuthHOTPPasswordLength

Valid values: 6 and 8.

One Time Password Max Retry

The number of times entry of the OTP may be attempted. Minimum is 1, maximum is 10.

Default: 3

ssoadm attribute: forgerock-oath-max-retry

One-Time Password Delivery

Specifies whether to send the one-time password by SMS, by mail, or both.

ssoadm attribute: sunAMAuthHOTPasswordDelivery

Valid values: SMS, E-mail, and SMS and E-mail.

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 AM user profile does not have an attribute for the mobile carrier domain. You can:

  • Customize the AM 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 AM 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

When enabled, configures the HOTP module to automatically generate an email or text message when users begin the login process.

ssoadm attribute: sunAMAuthHOTPAutoClicking

11.2.14. HTTP Basic Authentication Module Properties

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

Valid values: LDAP and DataStore.

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

11.2.15. JDBC Authentication Module Properties

ssoadm service name: sunAMAuthJDBCService

Connection Type

Determines how the module obtains the connection to the database.

ssoadm attribute: sunAMAuthJDBCConnectionType

Valid values: JNDI and JDBC.

Connection Pool JNDI Name

Specifies the URL of the connection pool for JNDI connections. Refer to your web container's documentation for instructions on setting up the connection pool.

ssoadm attribute: sunAMAuthJDBCJndiName

JDBC Driver

Specifies the JDBC driver to use for JDBC connections.

Install a suitable Oracle or MySQL driver in the container where AM is installed, for example in the /path/to/tomcat/webapps/openam/WEB-INF/lib path. You can add it to the AM .war file when you deploy AM.

ssoadm attribute: sunAMAuthJDBCDriver

JDBC URL

Specifies the URL to connect to the database when using a JDBC connection.

ssoadm attribute: sunAMAuthJDBCUrl

Database Username, Database Password

Specifies the user name and password used to authenticate to the database when using a JDBC connection.

ssoadm attribute: sunAMAuthJDBCDbuser and sunAMAuthJDBCDbpassword

Password Column Name

Specifies the database column name where passwords are stored.

ssoadm attribute: sunAMAuthJDBCPasswordColumn

Prepared Statement

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

ssoadm attribute: sunAMAuthJDBCStatement

Class to Transform Password Syntax

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

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

ssoadm attribute: sunAMAuthJDBCPasswordSyntaxTransformPlugin

Authentication Level

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

ssoadm attribute: sunAMAuthJDBCAuthLevel

Note

AM provides two properties, iplanet-am-admin-console-invalid-chars and iplanet-am-auth-ldap-invalid-chars, that store LDAP-related 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.

11.2.16. LDAP Authentication Module Properties

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 AM 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 AM server. For the current AM server, specify each directory server as a host:port combination. For other AM servers in the deployment, you can specify each directory server as server-name|host:port, where server-name is the FQDN portion of the AM 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 AM, 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, AM determines priority within the primary and secondary remote servers, respectively, as follows:

  • Every LDAP server that is mapped to the current AM instance has highest priority.

    For example, if you are connected to openam1.example.com and ldap1.example.com is mapped to that AM instance, then AM uses ldap1.example.com.

  • Every LDAP server that was not specifically mapped to a given AM instance has the next highest priority.

    For example, if you have another LDAP server, ldap2.example.com, that is not connected to a specific AM server and if ldap1.example.com is unavailable, AM connects to the next highest priority LDAP server, ldap2.example.com.

  • LDAP servers that are mapped to different AM 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 AM 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 AM stores attributes in the directory, for example to manage account lockout, or if the directory requires that AM authenticate in order to read users' attributes, then AM 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,AM-deploy-base, where AM-deploy-base is the value you set during AM 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 AM 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, AM 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 AM 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 AM uses the directory service as the user store, the module returns the DN, rather than the User ID. From the DN value, AM 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, AM 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 AM.

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

Minimum Password Length

Specifies 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 AM, 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, AM binds to the directory server as an administrator, such as Directory Manager. When AM 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 AM 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 AM 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

11.2.17. Legacy OAuth 2.0/OpenID Connect Authentication Module Properties

Important

Usage of this authentication module is deprecated. Equivalent functionality is provided by the following authentication modules:

The Legacy OAuth 2.0/OpenID Connect Authentication Module will only be available in AM 6 when upgrading from a previous version that was making use of the module in a chain. It is not available in new, clean installations since $[am.abbr} 5.5.

The default settings are for Facebook.

ssoadm service name: sunAMAuthOAuthService

Client id

Specifies the OAuth 2.0 client_id parameter as described in section 2.2 of RFC 6749.

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

Client Secret

Specifies the OAuth 2.0 client_secret parameter as described in section 2.3 of RFC 6749.

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

Authentication Endpoint URL

Specifies the URL to the endpoint handling OAuth 2.0 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

Specifies the URL to the endpoint 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

Specifies the 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

Specifies a space-delimited list of user profile attributes that the client application requires, according to The OAuth 2.0 Authorization Framework. 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

Specifies the name of the parameter that contains the access token value when accessing the profile service.

Default: access_token.

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

Proxy URL

Sets the URL to the /oauth2c/OAuthProxy.jsp file, which provides AM with GET to POST proxying capabilities. Change this URL only if an external server performs the GET to POST proxying.

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

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

Account Provider

Specifies the name of the class that implements the account provider.

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

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

Account Mapper

Specifies the name of the class that implements the attribute mapping for the account search.

Default: Depends on how the module is created:

  • If the OAuth 2.0 authentication module is created from the AM console authentication tab of a realm, the default is: org.forgerock.openam.authentication.modules.common.mapping.JsonAttributeMapper.

  • If the OAuth 2.0 authentication module is created from the AM console Facebook authentication wizard, the default is: org.forgerock.openam.authentication.modules.common.mapping.JsonAttributeMapper|*|facebook-.

  • If the OAuth 2.0 authentication module is created from the AM 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

Specifies the attribute configuration used to map the account of the user authenticated in the OAuth 2.0 provider to the local data store in AM. Valid values are 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 AM profile attributes.

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

Provided implementations are:

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

Tip

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

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

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

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

Attribute Mapper Configuration

Map of OAuth 2.0 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, saves the attributes in the Attribute Mapper Configuration field to the AM session.

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

Email attribute in OAuth2 Response

Specifies the attribute identifying the authenticated user's email address in the response from the profile service in the OAuth 2.0 provider. This setting is used to send an email message 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, AM creates an account for the user if the user profile does not exist. If the Prompt for password setting and activation code attribute is enabled, AM prompts the user for a password and activation code before creating the account.

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, AM uses the SMTP settings you provide here in the OAuth 2.0/OpenID Connect client configuration.

When disabled, a user without a profile may still log into AM if the Ignore Profile attribute is set in the authentication service of the realm, or if the account is mapped to an anonymous account.

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

Prompt for password setting and activation code

When enabled, the user must set a password before AM creates an account dynamically. An activation code is also sent to the user's email address. Both the password and the code are required before the account is created.

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

Map to anonymous user

When enabled, maps the OAuth 2.0 authenticated user to the specified anonymous user. If the Create account if it does not exist property is enabled, AM creates an account for the authenticated user instead of mapping the account to the anonymous user.

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

Anonymous User

Specifies an anonymous user that exists in the current realm. The Map to anonymous user property maps authorized users without a profile to this anonyomus user, if enabled.

Default: anonymous.

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

OAuth 2.0 Provider logout service

Specifies the optional URL of the OAuth 2.0 provider's logout service, if required.

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

Logout options

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

Valid values are:

  • prompt, to ask the user whether or not to log out from the OAuth 2.0 provider.

  • logout, to log the user out of the OAuth 2.0 provider without prompting.

  • donotlogout, to keep the user logged in to the OAuth 2.0 provider. There is no prompt to the user.

Default: prompt.

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

Mail Server Gateway implementation class

Specifies the class used by the module to send email. A custom subclass of org.forgerock.openam.authentication.modules.oauth2.EmailGateway class can be provided.

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

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

SMTP host

Specifies the host name of the mail server.

Default: localhost.

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

SMTP port

Specifies the SMTP port number for the mail server.

Default: 25.

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

SMTP User Name, SMTP User Password

Specifies the username and password AM uses to authenticate to the mail server.

ssoadm attribute: org-forgerock-auth-oauth-smtp-username and org-forgerock-auth-oauth-smtp-password.

SMTP SSL Enabled

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

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

SMTP From address

Specifies the address of the email sender, 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/realms/root/.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 in the OpenId Connect validation configuration type field.

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 Section 11.2.17.1, "OAuth 2.0 Mix-Up Mitigation".

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

Note

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

The following table shows endpoint URLs for AM when configured as an OAuth 2.0 provider. For details, see the OAuth 2.0 Guide. 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:

Table 11.1. Endpoint URLs
AM FieldDetails
Authorization Endpoint URL

/oauth2/authorize under the deployment URL.[a]

Example: https://openam.example.com:8443/openam/oauth2/realms/root/authorize.

Access Token Endpoint URL

/oauth2/access_token under the deployment URL.[a]

Example: https://openam.example.com:8443/openam/oauth2/realms/root/access_token.

User Profile Service URL

/oauth2/tokeninfo under the deployment URL.

Example: https://openam.example.com:8443/openam/oauth2/realms/root/tokeninfo.

[a] This AM endpoint can take additional parameters. In particular, you must specify the realm if the AM OAuth 2.0 provider is configured for a subrealm rather than the top-level realm.

When making a REST API call, specify the realm in the path component of the endpoint. You must specify the entire hierarchy of the realm, starting at the top-level realm. Prefix each realm in the hierarchy with the realms/ keyword. For example /realms/root/realms/customers/realms/europe.

For example, if the OAuth 2.0 provider is configured for the subrealm customers within the top-level realm, then the authentication endpoint URL is as follows: https://openam.example.com:8443/openam/oauth2/realms/root/realms/customers/authorize

The /oauth2/authorize endpoint can also take module and service parameters. Use either as described in Section 8.1, " Authenticating From a Browser", where module specifies the authentication module instance to use or service specifies the authentication chain to use when authenticating the resource owner.


11.2.17.1. OAuth 2.0 Mix-Up Mitigation

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

OAuth 2.0 Mix-Up Mitigation Enabled

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

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

Note

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

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

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

Note

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

11.2.18. MSISDN Authentication Module Properties

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

Specifies the LDAP server FQDN and its port in the format ldap_server:port. AM servers can be paired with LDAP servers and ports by adding entries with the format AM_server|ldap_server:port, for example, openam.example.com|ldap1.example.com:649.

To use SSL or TLS for security, enable the SSL/TLS Access to LDAP property. Make sure that AM can trust the servers' certificates when using this option.

ssoadm attribute: sunAMAuthMSISDNLdapProviderUrl

LDAP Start Search DN

Specifies the DN of the entry where the search for the user's MSISDN number should start. AM servers can be paired with search base DNs by adding entries with the format AM_server|base_dn. For example, openam.example.com|dc=openam,dc=forgerock,dc=com .

ssoadm attribute: sunAMAuthMSISDNBaseDn

Attribute To Use To Search LDAP

Specifies 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, LDAP Server Authentication Password

Specifies the bind DN and password to authenticate to the directory server. The default is cn=Directory Manager.

ssoadm attribute: sunAMAuthMSISDNPrincipalUser and sunAMAuthMSISDNPrincipalPasswd.

SSL/TLS for LDAP Access

When enabled, AM uses LDAPS or StartTLS to connect to the directory server. If you choose to enable SSL or TLS, then make sure that AM can trust the servers' certificates.

ssoadm attribute: sunAMAuthMSISDNUseSsl

MSISDN Header Search Attribute

Specifies which elements are searched for the MSISDN number.The possible values are:

searchCookie

To search the cookie.

searchRequest

To search the request header.

searchParam

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

When enabled, this option allows the authentication module to return the DN instead of the User ID. AM thus does not need to perform an additional search with the user ID to find the user's entry.

Enable this option only when the AM directory is the same as the directory configured for MSISDN searches.

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

11.2.19. OATH Authentication Module Properties

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

Note

For information on resetting the HOTP counter, see Section 4.4.7, "Resetting Registered Devices by using REST".

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

One Time Password Max Retry

The number of times entry of the OTP may be attempted. Minimum is 1, maximum is 10.

Default: 3

ssoadm attribute: forgerock-oath-max-retry

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

11.2.20. OpenID Connect id_token bearer Authentication Module Properties

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

Specifies the discovery URL, JWK or the client secret corresponding to the configuration type selected in the OpenID Connect validation configuration type property.

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

Name of header referencing the ID Token

Specifies the name of the HTTP request header to search for the ID token.

Default: oidc_id_token

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

Name of OpenID Connect ID Token Issuer

Corresponds to the expected issue identifier value in the iss field of the ID token.

Default: accounts.google.com

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

Mapping of jwt attributes to local LDAP attributes

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

Specifies a case-sensitive 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

Specifies 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

Specifies the class that implements the mapping of the OpenID Connect end user to an AM 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

11.2.22. RADIUS Authentication Module Properties

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 AM, 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, AM determines priority within the primary and secondary remote servers, respectively, as follows:

  • Every RADIUS server that is mapped to the current AM instance has highest priority.

  • Every RADIUS server that was not specifically mapped to a given AM instance has the next highest priority.

  • RADIUS servers that are mapped to different AM 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 AM 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

11.2.23. SAE Authentication Module Properties

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

11.2.24. SAML2 Authentication Module Properties

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

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

To find the local aliases for entity providers in the AM console, navigate to Realms > Realm Name > Applications > Federation > Entity Providers > 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 Realms > Realm Name > Applications > 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 Realms > Realm Name > Applications > 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 AM 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 Section 2.4.2.4, "Configuring Single Logout in an Integrated Mode Implementation" in the SAML v2.0 Guide.

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

11.2.25. Scripted Authentication Module Properties

ssoadm service name: iPlanetAMAuthScriptedService

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

Client-Side Script Enabled

When enabled, the module includes 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

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

To create, view, or modify the content of the scripts, navigate to Realms > Realm Name > Scripts.

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

Server Side Script

Specifies the ID of the script to run in AM after the client-side script has completed.

To create, view, or modify the content of the scripts, navigate to Realms > Realm Name > Scripts.

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 AM console, navigate to Configure > Global Services > Scripting > Secondary Configurations > Server-Side Script Type,> Secondary Configurations > EngineConfiguration.

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

Server-side Script Timeout

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

ssoadm attribute: serverTimeout

Core thread pool size

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

ssoadm attribute: coreThreads

Maximum thread pool size

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

ssoadm attribute: maxThreads

Thread pool queue size

Specifies 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)

Specifies the length of time (in seconds) for a thread to be idle before AM 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

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

Note

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

ssoadm attribute: useSecurityManager

11.2.26. SecurID Authentication Module Properties

Important

To use the SecurID authentication module, you must first build an AM .war file that includes the supporting library. For more information, see Section 1.1.4, "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 AM configuration directory, such as $HOME/openam/openam/auth/ace/data. The directory must exist before AM 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

11.2.27. Social Authentication Module Properties - Instagram

amster service name: authSocialInstagram

11.2.27.1. Core

The following properties are available under the Core tab:

Authentication Level

Specifies 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

amster data attribute: authenticationLevel

Social Provider

Specifies the name of the social provider for which this module is being set up.

Default: Instagram

amster data attribute: provider

Client Id

Specifies the client_id parameter as described in section 2.2 of The OAuth 2.0 Authorization Framework (RFC 6749).

Tip

To register an application with Instagram and obtain an OAuth 2.0 client_id and client_secret, visit https://www.instagram.com/developer/.

amster attribute: clientId

Client Secret

Specifies the client_secret parameter as described in section 2.3 of The OAuth 2.0 Authorization Framework (RFC 6749).

amster attribute: clientSecret

Authentication Endpoint URL

Specifies the URL to the social provider's endpoint handling authentication as described in section 3.1 of The OAuth 2.0 Authorization Framework (RFC 6749).

Default: https://api.instagram.com/oauth/authorize

amster attribute: authorizeEndpoint

Access Token Endpoint URL

Specifies the URL to the endpoint handling access tokens as described in section 3.2 of The OAuth 2.0 Authorization Framework (RFC 6749).

Default: https://api.instagram.com/oauth/access_token

amster attribute: tokenEndpoint

User Profile Service URL

Specifies the user profile URL that returns profile information in JSON format.

Default:https://api.instagram.com/v1/users/self

amster attribute: userInfoEndpoint

Scope

Specifies a list of user profile attributes that the client application requires, according to The OAuth 2.0 Authorization Framework (RFC 6749). The list depends on the permissions that the resource owner, such as the end user, grants to the client application.

Default: basic

amster attribute: scope

Scope Delimiter

Specifies the delimiter used to separate scope values.

Some authorization servers use non-standard separators for scopes. Facebook, for example, uses commas.

Default: space character

amster attribute: scopeDelimiter

Subject Property

Specifies the attribute the social provider uses to identify a user.

Default: id

amster attribute: subjectProperty

Use Basic Auth

Specifies that the client uses HTTP Basic authentication when authenticating to the social provider.

Valid values are:

  • true

  • false

Default: false

amster attribute: usesBasicAuth

Proxy URL

Specifies the URL to the /oauth2c/OAuthProxy.jsp file, which provides AM with GET to POST proxying capabilities. Change this URL only if an external server performs the GET to POST proxying.

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

Example: https://openam.example.com:8443/openam/oauth2c/OAuthProxy.jsp

amster attribute: ssoProxyUrl

OAuth 2.0 Provider Logout Service

Specifies the URL of the social provider's logout service.

To enable logout of the social authentication provider when logging out of AM, you must add org.forgerock.openam.authentication.modules.oauth2.OAuth2PostAuthnPlugin to the Authentication Post Processing Classes property. To add the class, navigate to Authentication > Settings > Post Authentication Processing.

Default: https://instagram.com/accounts/logout

amster attribute: logoutServiceUrl

Logout Options

Specifies the social provider logout actions to take when logging out of AM.

Valid options are:

prompt

Asks the user whether or not to log out from the social provider.

logout

Logs the user out of the social provider without prompting.

donotlogout

Keeps the user logged in to the social provider. There is no prompt to the user.

Default: prompt

amster attribute: logoutBehaviour

11.2.27.2. Account Provisioning

The following properties are available under the Account Provisioning tab:

Use IDM as Registration Service

Whether to use IDM as an external registration service to complete registration for new users. You must configure and enable the IDM Provisioning service to use this option. See Section 11.3.3, "IDM Provisioning".

AM passes IDM these parameters:

  • clientToken: Signed, encrypted JWT of the OAuth 2.0 authentication state.

  • returnParams: Encoded URL parameters, required to be returned to AM to resume authentication after registration in IDM is complete.

Default: False

amster attribute: enableRegistrationService

Create account if it does not exist

When enabled, AM creates an account for the user if the user profile does not exist.

When disabled, a user without a profile may still log into AM if the Ignore Profile attribute is set in the authentication service of the realm, or if the account is mapped to an anonymous account.

Valid values are:

  • true

  • false

Default: true

amster attribute: createAccount

Account Provider

Specifies the name of the class that implements the account provider.

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

amster attribute: accountProviderClass

Account Mapper

Specifies the name of the class that implements the attribute mapping for the account search.

Tip

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

Default: org.forgerock.openam.authentication.modules.common.mapping.JsonAttributeMapper|*|instagram-

amster attribute: accountMapperClass

Account Mapper Configuration

Specifies the attribute configuration used to map the account of the user authenticated in the social provider to the local data store in AM. Valid values take the form provider-attr=local-attr.

Default: id=uid

amster attribute: accountMapperConfiguration

Attribute Mapper

Specifies the list of fully qualified class names for implementations that map attributes from the social provider to AM profile attributes.

You can provide a custom attribute mapper. A custom attribute mapper must implement the org.forgerock.openam.authentication.modules.common.mapping.AttributeMapper interface.

Provided implementations are:

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

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

Tip

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

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

org.forgerock.openam.authentication.modules.oidc.JsonAttributeMapper|uid|instagram-

Default: org.forgerock.openam.authentication.modules.common.mapping.JsonAttributeMapper|uid|instagram-

amster attribute: attributeMappingClasses

Attribute Mapper Configuration

Specifies a map of social provider user account attributes to local user profile attributes with values in the form provider-attr=local-attr.

Default:

id=uid
full_name=sn
username=cn
username=givenName

amster attribute: attributeMapperConfiguration

Map to anonymous user

When enabled, maps the social provider authenticated user to a specified anonymous user. If the Create account if it does not exist property is enabled, AM creates an account for the authenticated user instead of mapping the account to an anonymous user.

Valid values are:

  • true

  • false

Default: false

amster attribute: mapToAnonymousUser

Anonymous User

Specifies an anonymous user that exists in the current realm. The Map to anonymous user property maps authorized users without a profile to this anonyomus user, if enabled.

Default: anonymous

amster attribute: anonymousUserName

Save attributes in the session

When enabled, saves the values of attributes specified in the Attribute Mapper Configuration property in the AM session.

Valid values are:

  • true

  • false

Default: true

amster attribute: saveAttributesInSession

11.2.28. Social Authentication Module Properties - OAuth 2.0

amster service name: authSocialOAuth2

11.2.28.1. Core

The following properties are available under the Core tab:

Authentication Level

Specifies 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

amster data attribute: authenticationLevel

Social Provider

Specifies the name of the social provider for which this module is being set up.

Example: Google

amster data attribute: provider

Client Id

Specifies the client_id parameter as described in section 2.2 of The OAuth 2.0 Authorization Framework (RFC 6749).

amster attribute: clientId

Client Secret

Specifies the client_secret parameter as described in section 2.3 of The OAuth 2.0 Authorization Framework (RFC 6749).

amster attribute: clientSecret

Authentication Endpoint URL

Specifies the URL to the social provider's endpoint handling authentication as described in section 3.1 of The OAuth 2.0 Authorization Framework (RFC 6749).

Example: https://accounts.google.com/o/oauth2/v2/auth

amster attribute: authorizeEndpoint

Access Token Endpoint URL

Specifies the URL to the endpoint handling access tokens as described in section 3.2 of The OAuth 2.0 Authorization Framework (RFC 6749).

Example: https://www.googleapis.com/oauth2/v4/token

amster attribute: tokenEndpoint

User Profile Service URL

Specifies the user profile URL that returns profile information in JSON format.

Exaple: https://www.googleapis.com/oauth2/v3/userinfo

amster attribute: userInfoEndpoint

Scope

Specifies a list of user profile attributes that the client application requires, according to The OAuth 2.0 Authorization Framework (RFC 6749). The list depends on the permissions that the resource owner, such as the end user, grants to the client application.

amster attribute: scope

Scope Delimiter

Specifies the delimiter used to separate scope values.

Some authorization servers use non-standard separators for scopes. Facebook, for example, uses commas.

amster attribute: scopeDelimiter

Subject Property

Specifies the attribute the social provider uses to identify a user.

Example: sub

amster attribute: subjectProperty

Use Basic Auth

Specifies that the client uses HTTP Basic authentication when authenticating to the social provider.

Valid values are:

  • true

  • false

Default: true

amster attribute: usesBasicAuth

Proxy URL

Specifies the URL to the /oauth2c/OAuthProxy.jsp file, which provides AM with GET to POST proxying capabilities. Change this URL only if an external server performs the GET to POST proxying.

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

Example: https://openam.example.com:8443/openam/oauth2c/OAuthProxy.jsp

amster attribute: ssoProxyUrl

OAuth 2.0 Provider Logout Service

Specifies the URL of the social provider's logout service.

To enable logout of the social authentication provider when logging out of AM, you must add org.forgerock.openam.authentication.modules.oauth2.OAuth2PostAuthnPlugin to the Authentication Post Processing Classes property. To add the class, navigate to Authentication > Settings > Post Authentication Processing.

amster attribute: logoutServiceUrl

Logout Options

Specifies the social provider logout actions to take when logging out of AM.

Valid options are:

prompt

Asks the user whether or not to log out from the social provider.

logout

Logs the user out of the social provider without prompting.

donotlogout

Keeps the user logged in to the social provider. There is no prompt to the user.

Default: prompt

amster attribute: logoutBehaviour

Token Issuer

Corresponds to the expected issue identifier value in the iss field of the ID token.

Example: https://accounts.google.com

amster attribute: issuerName

OAuth 2.0 Mix-Up Mitigation Enabled

Controls whether the OAuth 2.0 authentication module carries out additional verification steps when it receives the authorization code from the authorization server.

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.

The Token Issuer property must be entered when the OAuth 2.0 Mix-Up Mitigation feature is enabled, so that the validation can succeed. The authorization code response will contain an issuer value (iss) that will be validated by the client.

Note

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

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

amster attribute: mixUpMitigation

11.2.28.2. Account Provisioning

The following properties are available under the Account Provisioning tab:

Use IDM as Registration Service

Whether to use IDM as an external registration service to complete registration for new users. You must configure and enable the IDM Provisioning service to use this option. See Section 11.3.3, "IDM Provisioning".

AM passes IDM these parameters:

  • clientToken: Signed, encrypted JWT of the OAuth 2.0 authentication state.

  • returnParams: Encoded URL parameters, required to be returned to AM to resume authentication after registration in IDM is complete.

Default: False

amster attribute: enableRegistrationService

Create account if it does not exist

When enabled, AM creates an account for the user if the user profile does not exist. If the Prompt for password setting and activation code attribute is enabled, AM prompts the user for a password and activation code before creating the account.

Important

When configured to create new accounts, the SMTP settings must also be valid. As part of account creation, the authentication module sends the resource owner an email with an account activation code. To send the mail, AM uses the SMTP settings you provide in the module configuration.

When disabled, a user without a profile may still log into AM if the Ignore Profile attribute is set in the authentication service of the realm, or if the account is mapped to an anonymous account.

Valid values are:

  • true

  • false

Default: true

amster attribute: createAccount

Account Provider

Specifies the name of the class that implements the account provider.

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

amster attribute: accountProviderClass

Account Mapper

Specifies the name of the class that implements the attribute mapping for the account search.

Example: org.forgerock.openam.authentication.modules.common.mapping.JsonAttributeMapper|*|google-

amster attribute: accountMapperClass

Account Mapper Configuration

Specifies the attribute configuration used to map the account of the user authenticated in the social provider to the local data store in AM. Valid values take the form provider-attr=local-attr.

amster attribute: accountMapperConfiguration

Attribute Mapper

Specifies the list of fully qualified class names for implementations that map attributes from the social provider to AM profile attributes.

You can provide a custom attribute mapper. A custom attribute mapper must implement the org.forgerock.openam.authentication.modules.common.mapping.AttributeMapper interface.

Provided implementations are:

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

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

Tip

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

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

org.forgerock.openam.authentication.modules.oidc.JwtAttributeMapper|*|google-

amster attribute: attributeMappingClasses

Attribute Mapper Configuration

Specifies a map of social provider user account attributes to local user profile attributes with values in the form provider-attr=local-attr.

amster attribute: attributeMapperConfiguration

Prompt for password setting and activation code

When enabled, the user must set a password before AM creates an account dynamically. An activation code is also sent to the user's email address. Both the password and the code are required before the account is created.

Valid values are:

  • true

  • false

Default: false

amster attribute: promptPasswordFlag

Map to anonymous user

When enabled, maps the social provider authenticated user to a specified anonymous user. If the Create account if it does not exist property is enabled, AM creates an account for the authenticated user instead of mapping the account to an anonymous user.

Valid values are:

  • true

  • false

Default: false

amster attribute: mapToAnonymousUser

Anonymous User

Specifies an anonymous user that exists in the current realm. The Map to anonymous user property maps authorized users without a profile to this anonyomus user, if enabled.

Default: anonymous

amster attribute: anonymousUserName

Save attributes in the session

When enabled, saves the values of attributes specified in the Attribute Mapper Configuration property in the AM session.

Valid values are:

  • true

  • false

Default: true

amster attribute: saveAttributesInSession

11.2.28.3. Email

The following properties are available under the Email tab:

Email attribute in the Response

Specifies the attribute identifying the authenticated user's email address in the response from the profile service in the social provider. This setting is used to send an email message with an activation code for accounts created dynamically.

amster attribute: emailAttribute

Mail Server Gateway implementation class

Specifies the class used by the module to send email. A custom subclass of org.forgerock.openam.authentication.modules.oauth2.EmailGateway class can be provided.

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

amster attribute: emailGateway

SMTP host

Specifies the host name of the mail server.

Default: localh