Untitled :: ForgeRock Identity Cloud Docs

Authentication and SSO

These topics cover concepts, implementation, and customization of the authentication and single sign-on (SSO) features of ForgeRock Access Management.

Configure AM for authentication

Learn about AM’s authentication mechanisms.

Multi-factor authentication

Require that users provide multiple forms of identification when logging in to services.

Single sign-On

Enable single sign-on (SSO) so that users can log in once with a single set of credentials.

Social authentication

Allow users to authenticate to your services by using third-party identity providers.

ForgeRock® Identity Platform serves as the basis for our simple and comprehensive Identity and Access Management solution. We help our customers deepen their relationships with their customers, and improve the productivity and connectivity of their employees and partners. For more information about ForgeRock and about the platform, see https://www.forgerock.com.

Introduction to authentication

Authentication is the act of confirming a user’s identity, for example, by providing a set of credentials.

In access management, authentication is tightly couple with authorization; usually, not only is important to confirm that a user is who they say they are, but also to ensure that they can only access a subset of information.

Consider a user who wants to access an online shop. As the owner of the shop, you want to ensure the user identity is confirmed (since it is tied to their shipping and email addresses and payment information) and you also want to ensure that they can only access their own information.

With AM, you can deploy a ForgeRock Web Agent on the web server hosting the online shop. 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.

In the same way, you can also 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.

AM supports authentication nodes and trees to implement authentication.

AM creates an authentication session to track the user’s authentication progress through an authentication tree. Once the user has authenticated, AM creates a session to manage the user’s access to resources. To learn more about sessions, see Sessions.

Multi-factor authentication

Multi-factor authentication (MFA) is an authentication technique that requires users to provide multiple forms of identification when logging in to 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:

An AM administrator configures an authentication tree to capture the user’s username and password and to create one-time passwords.
An end user authenticates to AM using that authentication tree.
AM prompts the user to enter the username and password—the first factor in multi-factor authentication.
If the user ID and password were correct, AM sends the user an email with a one-time password.
The user provides the one-time password to AM to successfully complete authentication—the second factor in multi-factor authentication.

AM supports the following multi-factor authentication protocols:

MFA: Open AuTHentication (OATH) to enable one-time password authentication.
MFA: Push authentication to receive push notifications in a device as part of the authentication process.
MFA: Web authentication (WebAuthn) to enable authentication using an authenticator device, such as a fingerprint scanner.

Configure AM for authentication

AM provides the following features to authenticate users:

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.

AM leaves the authentication process flexible so that you can adapt how it works to your situation. Although the number of choices can seem daunting, once you understand the basic process you will see how AM lets you protect access to a wide range of applications used in your organization.

Authentication happens at realm level in AM. Each realm has its own authentication configuration that is copied from the parent realm at creation time, which may save you some time if you are configuring subrealms.

The following table summarizes the high-level tasks required to configure authentication in a realm:

Task	Resources
Configure the required authentication mechanisms You need to decide how your users are going to log in. For example, you may require your users to provide multiple credentials, or to log in using third-party identity providers, such as Facebook or Google.	Authentication nodes and trees
Configure the success and failure URLs for the realm By default, AM redirects users to the UI after successful authentication. No failure URL is defined by default.	Configure success and failure redirection URLs

Task

Resources

Configure the required authentication mechanisms

You need to decide how your users are going to log in. For example, you may require your users to provide multiple credentials, or to log in using third-party identity providers, such as Facebook or Google.

Authentication nodes and trees

Configure the success and failure URLs for the realm

By default, AM redirects users to the UI after successful authentication. No failure URL is defined by default.

Configure success and failure redirection URLs

Authentication nodes and trees

Authentication trees (also referred to as Intelligent Authentication) provide fine-grained authentication by allowing multiple paths and decision points throughout the authentication flow. Use them to build complex authorization scenarios, while offering a streamlined login experience to users.

Authentication trees are made up of authentication nodes, which define actions taken during authentication. Each node performs a single task during authentication, for example, collecting a username or making a simple decision based on a cookie.

Nodes can have multiple outcomes rather than just success or failure. This allows you to create complex yet customer-friendly authentication experiences by linking nodes together, creating loops, branching the tree for different authentication scenarios, and nesting nodes within a tree:

Create multiple paths for authentication by linking nodes within trees.

Figure 1. Example Authentication Tree

To further control the authentication process, you can assign authentication levels to branches on a tree, with higher levels being used typically to allow access to more restricted resources.

Authentication levels for trees

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. The authentication level is often used as a measure of the strength of the authentication performed. For example, simple username and password may be assigned a low authentication level, whereas multi-factor with push and webAuthn, a high one.

Authorization policies may require a particular authentication level to access protected resources. When an authenticated user tries to access a protected resource without satisfying the authentication level requirement, AM 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 Session upgrade

AM provides the following nodes to manage authentication levels:

The Auth Level Decision node node, that checks that the current authentication level is equal or greater than the one specified in the node.
The Modify Auth Level node node, that can raise or lower the authentication level.

Position these nodes to alter the authentication level depending on the route take through the authentication tree.

Account lockout for trees

It is recommended to limit the number of attempts a user can make at authenticating with credentials. Limiting the number of attempts helps to prevent password-guessing and brute-force attacks.

Authentication trees in AM have built-in support for account lockout, and provide nodes for checking the status of a user, and changing their status:

Account Active Decision node

Use this node to determine if an account is marked as active, or inactive (locked).

Account Lockout node

Use this node to alter the user’s status, to either active, or inactive (locked).

When setting an account to active, the node will also reset the failed attempts and lockout duration counters.

In addition to the lockout-specific nodes above, the Success and Failure nodes include account lockout functionality, when lockout is enabled in a realm, as follows:

Success node

Checks the User Status property of the user profile, when reached, and fails the authentication with an error message, if the account is marked as Inactive:

The error message is returned in the JSON response if authenticating to the tree by using REST:
```
{
    "code":401,
    "reason":"Unauthorized",
    "message":"User Locked Out.",
    "detail":
    {
        "failureUrl":""
    }
}
```
Resets the failure count in the user profile, when reached, if the User Status property is set to Active.

Failure node

Checks the invalid attempts property of the user profile, and returns a warning message if the number of failed attempts is equal to or greater than the configured Warn User After N Failures value in the realm:

The error message is returned in the JSON response if authenticating to the tree by using REST:
```
{
    "code":401,
    "reason":"Unauthorized",
    "message":"Warning: You will be locked out after 1 more failure(s).",
    "detail":
    {
        "failureUrl":""
    }
}
```
Increments the failure count in the user profile, when reached.
Returns an error message if the account is marked as Inactive:

The error message is returned in the JSON response if authenticating to the tree by using REST:
```
{
    "code":401,
    "reason":"Unauthorized",
    "message":"User Locked Out.",
    "detail":
    {
        "failureUrl":""
    }
}
```

Specify IDM identity resources in trees

When running AM as part of an integrated platform with IDM, trees configured to use the platform need to identify the type of identity resource or object the tree is working with. To do this, use the identityResource configuration property. If the property is not included in the tree configuration, it will default to managed/user.

To update identityResource on a tree, use the REST API to update the tree:

$ curl \
 --request PUT \
 --header 'Accept-API-Version: protocol=2.1,resource=1.0' \
 --header 'Accept: application/json' \
 --header 'If-None-Match: *' \
 --header 'Content-Type: application/json' \
 --header 'Cookie: <omitted for length>' \
 --data '{
   "entryNodeId":"e301438c-0bd0-429c-ab0c-66126501069a",
   "nodes":{},
   "staticNodes":{},
   "description":"Example tree description",
   "identityResource":"managed/newObjectType"
 }' \
 "https://default.iam.example.com/am/json/realms/root/realm-config/authentication/authenticationtrees/trees/ExampleTree"

In the above example, the tree ExampleTree has no nodes added to it yet. It includes the identityResource property, set to use a managed object in IDM called newObjectType.

Since this is a PUT request, you need to include the entire tree as part of the request. For more information about using REST with AM, see Introduction to REST in AM.

Configure authentication trees

The following table summarizes the high-level tasks required to configure authentication trees:

Task Resources

Task	Resources
Design your user authentication journey Authentication trees are very flexible. For example, the same tree can branch for different use cases, or users can be forced to loop though branches until they are able to present the required credentials. It is easy to create a massive tree that is difficult to understand, read, and maintain in the UI. For this reason, AM allows you to nest trees within trees. The best way to tackle the design decision is to write down a list of required steps users would need to take to log in to your environment, and then check the list of nodes available in AM.	Authentication nodes configuration reference, for a list of nodes delivered with AM. Multi-factor authentication, to understand how multi-factor authentication works with trees. Social authentication, to understand how social authentication works with trees.
Configure your authentication trees Use the authentication tree designer to put together your trees quickly.	Create an authentication tree.
Configure webhooks, if required If you have configured the `Register Logout Webhook` node, configure its webhook.	Configuring Authentication Webhooks.

Design your user authentication journey

Authentication trees are very flexible. For example, the same tree can branch for different use cases, or users can be forced to loop though branches until they are able to present the required credentials.

It is easy to create a massive tree that is difficult to understand, read, and maintain in the UI. For this reason, AM allows you to nest trees within trees.

The best way to tackle the design decision is to write down a list of required steps users would need to take to log in to your environment, and then check the list of nodes available in AM.

Authentication nodes configuration reference, for a list of nodes delivered with AM.
Multi-factor authentication, to understand how multi-factor authentication works with trees.
Social authentication, to understand how social authentication works with trees.

Configure your authentication trees

Use the authentication tree designer to put together your trees quickly.

Create an authentication tree.

Configure webhooks, if required

If you have configured the Register Logout Webhook node, configure its webhook.

Configuring Authentication Webhooks.

Create an authentication tree

On the Realms page of the AM admin UI, select the realm in which to create the authentication tree.
On the Realm Overview page, select Authentication > Trees.

Click Create Tree. Enter a tree name, for example myAuthTree, and click 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 1. Authentication Tree Designer Toolbar
Button	Usage
	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.

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.

The list of authentication nodes is split into a number of categories, which you can expand and collapse by clicking the category title.

You can use the filter text field to restrict the list of authentication nodes, which will match on the nodes' name, and any tags applied to the node:
Configure the node properties by using the right-hand panel.

For more information on the available properties for each node, see Authentication nodes configuration reference.
Connect the node to the tree as follows:
1. Select and drag the output connector from an existing node and drop it onto the new node.
2. 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.

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.
Alter a connection by selecting and dragging the green connector in the connection and dropping it onto the new location.
Continue adding, connecting and removing nodes until the tree is complete, and then select Save.
Test your authentication tree by navigating to a URL similar to the following: https://<tenant-name>.forgeblocks.com/am/XUI/?realm=/alpha&service=myAuthTree#login

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

To Create an Authentication Webhook

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

In the AM admin UI, go to Realms > Realm Name > Authentication > Webhooks.
1. To create a new webhook, select Create Webhook, specify a Webhook Name, and then select Create.
2. To edit an existing webhook, select the name of the webhook.
A screen similar to the following appears:

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 default session properties:

Table 2. Default Session Properties
Property	Example value	Description
`AMCtxId`	22e73c81-708e-4849-b064-db29b68ef943-105372	The audit ID for the session. This is logged as the `trackingIds` field in AM access audit logs.
`amlbcookie`	01	The cookie that identifies the AM server that generated the session. For environments with multiple AM servers, this can be used for load balancer stickiness.
`authInstant`	2022-02-28T14:06:31Z	The exact time that authentication completed.
`AuthLevel`	5	The authentication level of the session, determined by the login mechanism used to create the session. For example, a tree can have an authentication level of 10. Step-up authentication is triggered if an authentication level specified by an agent or policy that is designed to protect a resource, is greater than or equal to the value of the `AuthLevel` session property. For more information, see Session upgrade.
`CharSet`	UTF-8	The character set for the session, set to `UTF-8`.
`clientType`	genericHTML	The type of client, set to `genericHTML`.
`FullLoginURL`	/openam/UI/Login?realm=%2Falpha	The full login URL, including query parameters.
`Host`	192.0.2.1	The originating IP address of the authentication request.
`HostName`	192.0.2.1	The host name that was used when the session was authenticated.
`IndexType`	service	Based on the value of the `authIndexValue` query parameter during authentication. Typically, this is set to `service`.
`Locale`	en_US	The session locale.
`loginURL`	/openam/UI/Login	The base login URL. A subset of `FullLoginURL`.
`OidcSid`	g0wmSpoAIwH6HAwCnurvRcfYqh4	Unique session ID used by AM to determine whether OIDC ID tokens granted for the same client relate to the same session. This appears when `Enable Session Management` (`storeOpsToken`) is set to true in the OAuth 2.0 provider settings.
`Organization`	o=alpha,ou=services,dc=openam,dc=forgerock,dc=org	The DN of the realm where authentication took place.
`Principal`	id=demo,ou=user,o=alpha,ou=services,dc=openam,dc=forgerock,dc=org	The value of `sun.am.UniversalIdentifier`.
`Principals`	demo	The username for the session.
`Service`	Example	The name of the tree that was used to authenticate this session.
`successURL`	/openam/console	The URL that was redirected to, upon a successful login request.
`sun.am.UniversalIdentifier`	id=demo,ou=user,o=alpha,ou=services,dc=openam,dc=forgerock,dc=org	The DN of the user (username is lowercase).
`UserId`	demo	The `id` value from the `Principal` property.
`UserProfile`	Required	Can be one of: `Required`, `Create`, `Ignore`, or `CreateWithAlias`. Based on the value of the `dynamicProfileCreation` authentication configuration. Values other than `Ignore` indicates that user profile attributes were mapped based on the `User Attribute Mapping to Session Attribute` setting. See authentication configuration for details. Default: `Required`.
`UserToken`	demo	The username, as defined in the `Principal` property.

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

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

Customize authentication trees

Your deployment might require customizing standard authentication tree features.

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

The core class of an authentication tree hook

The following example shows the UpdatePersistentCookieTreehook class, as used by the Persistent Cookie Decision node:

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;
    }
}

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.

The node class must invoke method to specify the treehook class to be run after a successful login.

For example, in the PersistentCookieDecisionNode.class:

@Override
public Action process(TreeContext context) throws NodeProcessException {
    ...
    actionBuilder = actionBuilder
        .addSessionHook(UpdatePersistentCookieTreeHook.class, nodeId, getClass().getSimpleName());
}

2 The core class must implement the TreeHook interface.

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.

Configure success and failure redirection URLs

AM determines the redirection URL based on authentication success or failure. During success, AM redirects the user to the URL specified in the goto parameter and, during failure, AM redirects the user to the URL specified in the gotoOnFail parameter.

AM provides a number of places where you can configure success or failure URLs:

Successful authentication URL precedence, and where to configure success URLs

Upon a successful authentication, AM determines the redirection URL in the following order:

The URL set in the authentication tree.

To specify a URL in an authentication tree, add a Success URL node to the tree and specify the Success URL in the node properties.

The URL set in the goto login URL parameter. For example:

https://<tenant-name>.forgeblocks.com/am/XUI/?realm=/alpha&goto=http%3A%2F%2Fwww.example.com#login

The URL set in the Success URL attribute in the user’s profile.

In the AM admin UI, you can set the Success URL parameter by going to Realm Name > Identities > identity. In Success URL, enter a URL, and save your changes.

You can also specify the client type by entering ClientType|URL as the property value. If the client type is specified, it will have precedence over a regular URL in the user’s profile.
The URL set in the Default Success Login URL attribute in the realm.

You can set this property on the AM admin UI by navigating to Authentication > Settings > Post Authentication Processing.

You can also specify the client type by entering ClientType|URL as the property value. If the client type is specified, it will have precedence over a Default Success Login URL in the realm.

Failed authentication URL precedence, and where to configure failure URLs

Upon a failed authentication, AM determines the redirection URL in the following order:

The URL set in the authentication tree.

To specify a URL in an authentication tree, add a Failure URL node to the tree and specify the failure URL in the node properties.

The URL set in the gotoOnFail parameter. For example:

https://<tenant-name>.forgeblocks.com/am/XUI/?realm=/alpha&gotoOnFail=http%3A%2F%2Fwww.example.com#login

The URL set in the Failure URL attribute in the user’s profile.

In the AM admin UI, you can set the Failure URL parameter by navigating to Realm Name > Identities > identity. Under Failure URL, enter a URL, and click Save Changes.

You can also specify the client type by entering ClientType|URL as the property value. If the client type is specified, it will have precedence over a regular URL in the user’s profile.
The URL set in the Default Failure Login URL attribute in the realm.

You can set this property on the AM admin UI by navigating to Authentication > Settings > Post Authentication Processing.

You can also specify the client type by entering ClientType|URL as the property value. If the client type is specified, it will have precedence over a Default Failure Login URL in the realm.

URLs can be relative to AM’s URL, or absolute.

By default, AM trusts all relative URLs and those absolute URLs that are in the same scheme, FQDN, and port as AM. This increases security against possible phishing attacks through open redirect.

To configure AM to trust other absolute URLs, add them to the Validation Service. If you do not, on login AM will redirect to the user profile or to the administrator console, and on logout to the default logout page in the UI instead.

Do I need to add my URL to the validation service?

Consider an example AM deployment configured in https://am.example.com:8443/am:

URL Needs to be configured in the validation service?

URL	Needs to be configured in the validation service?
`http://am.example.com:8080/am/XUI/#login`	Yes, the scheme and port are different.
`https://am.example.com:443/am/XUI/#login`	Yes, the port is different.
`/am/XUI/#login`	No, the paths relative to the AM URL are trusted.
`https://mypage.example.com/app/logout.jsp`	Yes, the scheme, port, and FQDN are different.

http://am.example.com:8080/am/XUI/#login

Yes, the scheme and port are different.

https://am.example.com:443/am/XUI/#login

Yes, the port is different.

/am/XUI/#login

No, the paths relative to the AM URL are trusted.

https://mypage.example.com/app/logout.jsp

Yes, the scheme, port, and FQDN are different.

Configure the validation service

In the AM admin UI, go to Realms > Realm Name > Services.
Click Add a Service.
From the Choose a service type drop-down list, select Validation Service.
In the Valid goto URL Resources field, enter one or more valid URL patterns to allow.

For example, https://app.example.com:80/*?*.

For information on pattern matching and wildcard rules, see Specify resource patterns with wildcards.
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/.
Click Create to save your settings.

To validate a goto URL over REST, use the /json/users?_action=validateGoto endpoint:

$ curl \
--request POST \
--header "Accept-API-Version: protocol=2.1,resource=3.0" \
--header "Content-Type: application/json" \
--header "<session-cookie-name>: AQIC5…ACMDE.*" \
--data '{"goto":"http://www.example.com/"}' \
'https://<tenant-name>.forgeblocks.com/am/realms/root/realms/alpha/json/users?_action=validateGoto'
{
    "successURL":"https://www.example.com/"
}

Configure realm authentication properties

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, go to Configure > Authentication in the AM admin UI, and click Core Attributes.

The core authentication attributes page is divided into seven tabs.

Figure 2. The Core Authentication Attributes Page

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

Use core authentication attributes to configure:

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 Core authentication attributes.

Authenticate with a browser

When authenticating using a browser, you can send AM a realm and also different authentication parameters that would help you customize the user’s experience.

Specify the realm in the URL

When making a request to the UI, 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. For example:

The following table demonstrates additional examples:

Table 3. Options for Specifying the Realm in UI Login URLs
Description	Example URL
Full path of the realm as a parameter of `XUI`	`https://<tenant-name>.forgeblocks.com/am/XUI/?realm=/alpha#login`
Realm alias of the realm as a parameter of `XUI`	`https://<tenant-name>.forgeblocks.com/am/XUI/?realm=alpha#login`

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.
ForceAuth: If ForceAuth=true, request that AM force the user to authenticate even if they already have a valid session.

On successful authentication, AM issues new session tokens to reauthenticating users, even if the current session already meets the security requirements.
goto: On successful authentication, or successful logout, request that AM redirect the user to the specified location. Values must be URL-encoded.

See Configure success and failure redirection URLs for more information.
gotoOnFail: On authentication failure, request that AM redirect the user to the specified location. Values must be URL-encoded.

See Configure success and failure redirection URLs for more information.
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.
realm: Request that AM authenticate the user to the specified realm.
resource: Set this parameter to true to request resource-based authentication.

Example UI login URLs

Use any of the options listed in Authentication parameters as URL parameters. Note that URL parameters must appear before any occurrences of the pound or hash character (#).

The following are example URLs with parameters:

Table 4. Example UI Login URLs
Description	Example URL
Log in to the `alpha` realm, requesting that AM display the user interface in German.	`https://<tenant-name>.forgeblocks.com/am/XUI/?realm=/alpha&locale=de#login`
Log in to the `alpha` realm using the `myTree` authentication tree, requesting that AM display the user interface in German.	`https://<tenant-name>.forgeblocks.com/am/XUI/?realm=/alpha&locale=de&service=myTree#login`

Authenticate using REST

AM provides the /json/authenticate endpoint for authentication, and the /json/sessions endpoint for managing sessions and logging out.

The following table summarizes authentication operations you can perform using REST:

Task Resources

Task	Resources
Authenticate to AM Authenticating to AM means logging in to a specific realm and receiving a session token from AM. Add parameters to the authentication request to provide AM with more information about how you want to authenticate.	Log in to AM using REST
Use the session token AM provides you with a session token after authenticating to a realm. Use this token in subsequent calls to AM. For example, when using REST calls to create, modify, or delete configuration objects.	Using the session token after authentication
Log out of AM Log out your users by sending a `logout` action to the `/json/sessions` endpoint.	Log out of AM using REST
Invalidate sessions Obtain all the sessions for a given user and invalidate them to ensure they are logged out of AM.	Invalidate all sessions for a given user

Authenticate to AM

Authenticating to AM means logging in to a specific realm and receiving a session token from AM. Add parameters to the authentication request to provide AM with more information about how you want to authenticate.

Use the session token

AM provides you with a session token after authenticating to a realm. Use this token in subsequent calls to AM. For example, when using REST calls to create, modify, or delete configuration objects.

Using the session token after authentication

Log out of AM

Log out your users by sending a logout action to the /json/sessions endpoint.

Log out of AM using REST

Invalidate sessions

Obtain all the sessions for a given user and invalidate them to ensure they are logged out of AM.

Invalidate all sessions for a given user

To authenticate to AM using REST, make an HTTP POST request to the json/authenticate endpoint. You must specify the entire hierarchy of the realm. Prefix each realm in the hierarchy with the realms/ keyword. For example, /realms/root/realms/alpha.

The /json/authenticate endpoint does not support the CRUDPAQ verbs and therefore does not technically satisfy REST architectural requirements. The term REST-like describes this endpoint better than REST.

AM uses the default authentication service configured for the realm. You can override the default by specifying authentication services and other options in the REST request.

AM provides both simple authentication methods, such as providing user name and password, and complex authentication journeys that may involve a tree with inner tree evaluation and/or multi-factor authentication.

For authentication journeys where providing a user name and password is enough, you can log in to AM using a curl command similar to the following:

$ curl \
--request POST \
--header "Content-Type: application/json" \
--header "X-OpenAM-Username: demo" \
--header "X-OpenAM-Password: Ch4ng31t" \
--header "Accept-API-Version: resource=2.0, protocol=1.0" \
'https://<tenant-name>.forgeblocks.com/am/json/realms/root/realms/alpha/authenticate'
{
    "tokenId": "AQIC5w…NTcy*",
    "successUrl": "/openam/console",
    "realm":"/alpha"
}

The user name and password are sent in headers. This zero page login mechanism works only for name/password authentication.

Note that the POST body is empty; otherwise, AM interprets the body as a continuation of an existing authentication attempt, one that uses a supported callback mechanism. AM implements callback mechanisms to support complex authentication journeys, such as those where the user needs to be redirected to a third party or interact with a device as part of multi-factor authentication.

After a successful authentication, AM returns a tokenId object that applications can present as a cookie value for other operations that require authentication. This object is known as the session token. For more information about how applications can use the session token, see Using the session token after authentication.

When a client makes a call to the /json/authenticate endpoint appending a valid SSO token, AM returns the tokenId field empty when HttpOnly cookies are enabled. For example:

{
    "tokenId":"",
    "successUrl":"/openam/console",
    "realm":"/alpha"
}

You can request AM to authenticate a user without providing them a session by using the noSession parameter. For more information, see Authenticate endpoint parameters.

Using UTF-8 usernames

To use UTF-8 usernames and passwords in calls to the /json/authenticate endpoint, base64-encode the string, and then wrap the string as described in RFC 2047:

encoded-word = "=?" charset "?" encoding "?" encoded-text "?="

For example, to authenticate using a UTF-8 username, such as ɗëɱø, perform the following steps:

Encode the string in base64 format: yZfDq8mxw7g=.
Wrap the base64-encoded string as per RFC 2047: =?UTF-8?B?yZfDq8mxw7g=?=.

Use the result in the X-OpenAM-Username header passed to the authentication endpoint as follows:

$ curl \
--request POST \
--header "Content-Type: application/json" \
--header "X-OpenAM-Username: =?UTF-8?B?yZfDq8mxw7g=?=" \
--header "X-OpenAM-Password: Ch4ng31t" \
--header "Accept-API-Version: resource=2.0, protocol=1.0" \
'https://<tenant-name>.forgeblocks.com/am/json/realms/root/realms/alpha/authenticate'
{
    "tokenId": "AQIC5w…NTcy*",
    "successUrl": "/openam/console",
    "realm":"/alpha"
}

Authenticate to specific authentication services

You can provide AM with additional information about how you are authenticating. For example, you can specify the authentication tree you want to use, or request from AM a list of the authentication services that would satisfy a particular authentication condition.

The following example shows how to specify the login tree by using the authIndexType and authIndexValue query string parameters:

$ curl \
--request POST \
--header "X-OpenAM-Username: demo" \
--header "X-OpenAM-Password: Ch4ng31t" \
--header 'Accept-API-Version: resource=2.0, protocol=1.0' \
'https://<tenant-name>.forgeblocks.com/am/json/realms/root/realms/alpha/authenticate?authIndexType=service&authIndexValue=login'

You can exchange the login tree with any other tree.

For more information about using the authIndexType parameter to authenticate to specific services, see Authenticate endpoint parameters.

The /json/authenticate endpoint supports callback mechanisms to perform complex authentication journeys. Whenever AM needs to return or request information, it will return a JSON object with the authentication step, the authentication identifier, and the related callbacks.

The following types of callbacks are available:

Read-only callbacks. AM uses read-only callbacks to provide information to the user, such as text messages or the amount of time that the user needs to wait before continuing their authentication journey.
Interactive callbacks. AM uses interactive callbacks ask the user for information. For example, to request their user name and password, or to request that the user chooses between different options.
Backchannel callbacks. AM uses backchannel callbacks when it needs to access additional information from the user’s request. For example, when it requires a particular header or a certificate.

Read-only and interactive callbacks have an array of output elements suitable for displaying to the end user. The JSON returned in interactive callbacks also contains an array of link:input elements, which must be completed and returned to AM. For example:

"output": [
    {
        "name": "prompt",
        "value": " User Name: "
    }
    ],
"input": [
    {
        "name": "IDToken1",
        "value": ""
    }
]

The value of some interactive callbacks can be returned as headers, such as the X-OpenAM-Username and X-OpenAM-Password headers, but most of them must be returned in JSON as a response to the request.

Depending on how complex the authentication journey is, AM may return several callbacks sequentially. Each must be completed and returned to AM until authentication is successful.

The following example shows a request for authentication, and AM’s response of the NameCallback and PasswordCallback callbacks:

$ curl \
--request POST \
--header "Content-Type: application/json" \
--header "Accept-API-Version: resource=2.0, protocol=1.0" \
'https://<tenant-name>.forgeblocks.com/am/json/realms/root/realms/alpha/authenticate'

{
  "authId": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJvdGsiOiJ...", (1)
  "template": "", (2)
  "stage": "DataStore1", (3)
  "callbacks": [
    {
      "type": "NameCallback", (4)
      "output": [ (5)
        {
          "name": "prompt",
          "value": " User Name: "
        }
      ],
      "input": [ (6)
        {
          "name": "IDToken1",
          "value": ""
        }
      ]
    },
    {
      "type": "PasswordCallback",
      "output": [
        {
          "name": "prompt",
          "value": " Password: "
        }
      ],
      "input": [
        {
          "name": "IDToken2",
          "value": ""
        }
      ]
    }
  ]
}

1	The JWT that uniquely identifies the authentication context to AM.
2	A template to customize the look of the authentication node, if it exists. For more information, see How do I customize the Login page? in the ForgeRock Knowledge Base.
3	The authentication node at which the authentication journey currently is.
4	The type of callback. It must be in Supported callbacks.
5	The information AM offers about this callback. Usually, this information would be displayed to the user in the UI.
6	The information AM is requesting. The user must complete the `"value": ""` object with the required information.

To respond to a callback, send back the whole JSON object, including the missing values. The following example shows how to respond to the NameCallback and PasswordCallback callbacks, with the demo and Ch4ng31t values returned:

$ curl \
--request POST \
--header "Content-Type: application/json" \
--header "Accept-API-Version: resource=2.0, protocol=1.0" \
--data '{
   "authId":""eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJvdGsiOiJ…",
   "template":"",
   "stage":"DataStore1",
   "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":"Ch4ng31t"
            }
         ]
      }
   ]
}' \
'https://<tenant-name>.forgeblocks.com/am/json/realms/root/realms/alpha/authenticate'
{
    "tokenId":"AQIC5wM2…U3MTE4NA..*",
    "successUrl": "/openam/console",
    "realm":"/"
}

On complex authentication journeys, AM may send several callbacks sequentially. Each must be completed and returned to AM until authentication is successful.

For more information about the callbacks AM can return, see Supported callbacks.

Using the session token after authentication

After a successful authentication, AM returns a tokenId object that applications can present as a cookie value for other operations that require authentication. This object is a session token—a representation of the exchange of information and credentials between AM and the user or identity.

If CTS-based sessions are enabled, the tokenId object is a reference to the session state stored in the CTS token store.

The following is a common scenario when accessing AM by using REST API calls:

Call the /json/authenticate endpoint to log a user in to AM.

This REST API call returns a tokenID value, which is used in subsequent REST API calls to identify the user:

$ curl \
--request POST \
--header "Content-Type: application/json" \
--header "X-OpenAM-Username: demo" \
--header "X-OpenAM-Password: Ch4ng31t" \
--header "Accept-API-Version: resource=2.0, protocol=1.0" \
'https://<tenant-name>.forgeblocks.com/am/json/realms/root/realms/alpha/authenticate'
{
    "tokenId":"AQIC5wM…TU3OQ*",
    "successUrl":"/openam/console",
    "realm":"/alpha"
}

The returned tokenID is known as a session token (also referred to as an SSO token). REST API calls made after successful authentication to AM must present the session token in the HTTP header as proof of authentication.

Call one or more additional REST APIs on behalf of the logged-in user.

Each REST API call passes the user’s tokenID back to AM in the HTTP header as proof of previous authentication.

The following is a partial example of a curl command that inserts the token ID returned from a prior successful AM authentication attempt into the HTTP header:
```
$ curl \
--request POST \
--header "Content-Type: application/json" \
--header "<session-cookie-name>: AQIC5w…NTcy*" \
--header "Accept-API-Version: resource=2.0, protocol=1.0" \
--data '{
  …
```
Observe that the session token is inserted into a header field named <session-cookie-name>. This header field name must correspond to the name of the tenant session cookie.

To find the name of the session cookie, see How Do I View the Tenant Session Cookie Name?

Once a user has authenticated, it is not necessary to insert login credentials in the HTTP header in subsequent REST API calls. Note the absence of X-OpenAM-Username and X-OpenAM-Password headers in the preceding example.

Users must have appropriate privileges to access AM functionality using the REST API.
Call the REST API to log the user out of AM, as described in Authenticate using REST.

As with other REST API calls made after a user has authenticated, the REST API call to log out of AM requires the user’s tokenID in the HTTP header.

Log out of AM using REST

Authenticated users can log out with the token cookie value and an HTTP POST to /json/sessions/?_action=logout:

$ curl \
--request POST \
--header "<session-cookie-name>: AQICS…NzEz*" \
--header "Accept-API-Version: resource=3.1, protocol=1.0" \
'https://<tenant-name>.forgeblocks.com/am/json/realms/root/realm/alpha/sessions/?_action=logout'
{
    "result":"Successfully logged out"
}

Invalidate all sessions for a given user

To log out all sessions for a given user, first obtain a list of session handles of their active sessions, by performing an HTTP GET on the /json/sessions/ endpoint, using the SSO token of an administrative user as the value of the <session-cookie-name> header. You must also specify a queryFilter parameter.

The queryFilter parameter requires the name of the user, and the realm to search. For example, to obtain a list of session handles for a user named demo in the alpha realm, the query filter value would be:

username eq "demo" and realm eq "/alpha"

The query filter value must be URL encoded when sent over HTTP.

For more information on query filter parameters, see Query.

In the following example, there is one active session:

$ curl \
--request GET \
--header "<session-cookie-name>: AQICS…NzEz*" \
--header "Accept-API-Version: resource=3.1, protocol=1.0" \
'https://<tenant-name>.forgeblocks.com/am/json/realms/root/realms/alpha/sessions?_queryFilter=username%20eq%20%22demo%22%20and%20realm%20eq%20%22%2F%22'
{
    "result": [
        {
            "_rev": "652365455",
            "username": "demo",
            "universalId": "id=demo,ou=user,dc=openam,dc=forgerock,dc=org",
            "realm":"/alpha",
            "sessionHandle":"shandle:cmvShY1….AA.*",
            "latestAccessTime":"2019-10-03T09:36:53.041Z",
            "maxIdleExpirationTime":"2019-10-03T10:06:53Z",
            "maxSessionExpirationTime":"2019-10-03T11:36:53Z",
        }
    ],
    "resultCount": 1,
    "pagedResultsCookie": null,
    "totalPagedResultsPolicy": "NONE",
    "totalPagedResults": -1,
    "remainingPagedResults": -1
}

To log out all sessions for the specific user, perform an HTTP POST on the /json/sessions/ endpoint, using the SSO token of an administrative user as the value of the <session-cookie-name> header. You must also specify the logoutByHandle action, and include an array of the session handles to invalidate in the POST body, in a property named sessionHandles, as shown below:

$ curl \
--request POST \
--header "Content-Type: application/json" \
--header "<session-cookie-name>: AQICS…NzEz*" \
--header "Accept-API-Version: resource=3.1, protocol=1.0" \
--data '{
    "sessionHandles": [
        "shandle:SJ80.AA….JT.",
        "shandle:H4CV.DV….FM."
    ]
}' \
'https://<tenant-name>.forgeblocks.com/am/json/realms/root/realms/alpha/sessions/?_action=logoutByHandle'
{
    "result": {
        "shandle:SJ80.AA….JT.": true,
        "shandle:H4CV.DV….FM.": true
    }
}

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 HTTP cookies for more information.)

Cross-domain single sign-on (CDSSO) is an AM-specific capability that provides SSO inside the same organization within a single domain or across domains. 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.

Since CDSSO removes the constraint of configuring SSO depending on the DNS domain, it simplifies the deployment of SSO in your environment.

When implementing CDSSO, take into account the following points:

For SSO across multiple organizations or when integrating with other access management software, use AM’s federation capabilities, such as OAuth 2.0 or SAML v2.0.
Web Agents and Java Agents both support CDSSO.

AM also supports CDSSO with IG version 6 or later. For more information, see Single Sign-On and Cross-Domain Single Sign-On in the IG documentation.

Web agents and Java agents wrap the SSO session token inside an OpenID Connect (OIDC) JSON Web Token (JWT). 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 and Java Agents:

Figure 3. Web and Java Agents CDSSO Flow

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 admin UI, 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.

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

Expires: The lifetime of a cookie can be limited, with an Expires name configured with a time, based on UTC (GMT).

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.

Implementing CDSSO

CDSSO provides SSO capabilities for AM servers and web or Java agents within a single domain or across domains in the same organization.

CDSSO is the only mode of operation of Web Agents and Java Agents and, therefore, no additional configuration is required to make it work.

IG also supports CDSSO with AM. For more information, see the ForgeRock Identity Gateway Gateway Guide.

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.

You can configure user self-registration to include social identity providers as an option for users. This lets users register and log in to AM using an account they have through another trusted service.

The high-level steps to configure social authentication are:

AM supports social identity providers that are OAuth 2.0 or OpenID Connect 1.0-compliant, and comes preconfigured with support for a number of social providers:

Table 5. Default Social Identity Provider Configurations
Amazon	Apple	Facebook
Google	Instagram	itsme⁽¹⁾
LinkedIn	Microsoft	Salesforce
Twitter	VK (Vkontakte)	WeChat
WordPress	Yahoo

⁽¹⁾ To integrate with itsme^®, you must obtain an Organization Validation (OV) or an Extended Validation (EV) SSL certificate.

How do I get a custom OV/EV SSL certificate?

The procedure to create and configure a custom SSL certificate is as follows:

Request a certificate signing request (CSR) by raising a support ticket.

Provide information in the CSR ticket according to the type of certificate you need to obtain:
- For an OV certificate, provide values for all the standard CSR fields.
- For an EV certificate, also specify values for the EV fields.
Request an OV/EV certificate.

Send the CSR to your preferred certificate authority (CA) and receive a custom certificate in return.
Supply ForgeRock support with the certificate.

ForgeRock will apply the certificate to the requisite environments for you to use to securely query endpoints supported by your social identity provider.

If you need support for a social identity provider that is not preconfigured, you can manually add new providers, as long as they have a solution implemented using either OAuth 2.0, or OpenID Connect.

Add identity providers

Registering with a provider comprises creating a client ID and adding the redirection URL to AM at the very least.

Each identity provider will have a different registration or onboarding process. Make sure you are familiar with their documentation and refer to it throughout this procedure so that you are aware of any particular requirements.

Although AM is preconfigured with many of the settings that are required by the provider, you may need to perform additional tasks.

For example, a financial-grade provider could stipulate that you connect using a high-assurance SSL certificate, so you would need to follow the steps to obtain a custom SSL certificate.

Redirection URLs

The redirection URL is a path in AM that the identity provider will redirect the user to after a successful authentication. For example, https://platform.example.com:8443/am.

Depending on the social identity provider and on your environment, you may need to make changes to the redirection URI later.

Configure the same redirection URL in the identity provider service and in the AM client.

Some providers require that you enable a specific API in their service:

Google: Enable the Gmail API in the Google Cloud Platform.
Apple: You must have access to the Apple Development Program (Enterprise program is not eligible), and you must enable Sign In With Apple in the Apple Developer site.

In the AM admin UI, go to Realms > Realm Name > Services.
Check if the Social Identity Provider Service appears in the list of services configured for the realm.

If it does not, click Add a Service to add, and select Social Identity Provider Service from the drop-down list.

The service’s Configuration page appears.
Ensure that the Enabled switch is on.
Go to the Secondary Configurations tab.

AM includes scripts and configurations for several common identity providers.
In the Add a Secondary Configuration drop-down list, select the required identity provider.

If you do not see the required provider, select one of the following to add a custom identity provider client:
- Client Configuration for providers that implement the OAuth2 specification
- Client Configuration for providers that implement the OpenID Connect specification
The new identity provider configuration page appears.
Provide the client’s required configuration details, such as the Client ID, Client Secret (for confidential clients), the Scope Delimiter (usually an empty space), and the Redirect URL.

Redirection URLs

The redirection URL is a path in AM that the identity provider will redirect the user to after a successful authentication. For example, https://platform.example.com:8443/am.

Depending on the social identity provider and on your environment, you may need to make changes to the redirection URI later.

Configure the same redirection URL in the identity provider service and in the AM client.

Do not worry if you are missing some of the details; you will be able to edit the configuration later, after saving the client profile for the first time.

Save your changes to access all the configuration fields for the client.

Provide the client’s advanced configuration details, and edit any required configuration details if needed.

Where do I find the required identity provider information?

Refer to the provider’s documentation.

Providers must specify their integration needs in their documentation, as well as their API endpoints.

For example, providers usually have different scopes that you can configure depending on your service’s needs.

Financial-grade providers usually also require additional security-related configuration, such as acr values, PKCE-related settings, and more.

Keep their documentation close while configuring the client profile.
Visit the provider’s .well-known endpoint.

OAuth 2.0/OpenID Connect-compliant providers will display much of the information you need to configure the identity provider client in their .well-known endpoint. For example, the endpoint should expose their endpoint URLs, and the signing and encryption algorithms they support.

AM is preconfigured for your convenience, but you must make sure the settings for the provider have not changed. Some of the most important preconfigured fields are:

The provider’s URLs.

For example: Authentication Endpoint URL, Access Token Endpoint URL, and User Profile Service URL.
The OAuth Scopes field.
The configuration in the UI Config Properties section.
The script selected in the Transform Script drop-down list.

Scripts named after identity providers are suitable for most use cases. However, if you need to view or edit the scripts, go to Realms > Realm Name > Scripts.

Some features require choosing algorithms from those supported by the provider, as well as creating secrets. Consider the following points before configuring the client:

Several capabilities in the identity provider client share the same secret IDs; for example, signing request objects and signing client authentication JWTs.
Every identity provider client in a realm shares the same secrets.

Therefore, ensure that you configure features requiring secrets in a way that they are compatible across clients in the same realm.

For more information, see /oauth2/connect/rp/jwk_uri.

For tips on how to configure the client, see Client configuration reference.

Save your changes.

You are ready now to Configure basic social registration trees.

There are two nodes associated with identity providers:

Select Identity Provider Node: The Select Identity Provider node prompts the user to select a social identity provider to register or log in with, or (optionally) continue on with a local registration or login flow. When a provider is selected, the flow continues on to the Social Provider Handler node.
Social Provider Handler Node: The Social Provider Handler node is used in combination with the Select Identity Provider node. It communicates with the selected provider and collects the information provided after the user has authorized the service. It then takes that information and runs a transformation script to prepare it.

AM includes a transformation script called Normalized Profile to Managed User, which this node uses to transform the identity object gathered from the identity provider into a AM object.

AM includes a transformation script called Normalized Profile to Identity, which this node uses to transform the identity object gathered from the identity provider into a user profile in AM’s identity store.

The node queries IDM to see if the user already exists. If the user exists, they are logged in. If the user does not exist, the user will need to be created.

The node queries the identity store available for the realm to see if the user already exists. If the user exists, they are logged in. If the user does not exist, the user will need to be created.

Set up a basic social registration tree

In your realm, go to Journeys.

You can create a new tree, modify an existing tree, or duplicate an existing tree.
Decide whether users can log in with their local credentials, and add the relevant nodes to the tree:
1. Social authentication trees allowing local authentication might look like the following:
2. Social authentication trees enforcing social authentication login might look like the following:
  
  To configure either option, use the Include local authentication switch in the Select Identity Provider node.
  
  Note that, to support both local and social authentication in the same page, you must use the Page node as shown in the example.
Configure the Social Provider Handler node:
- In the Transformation Script field, configure Normalized Profile to Managed User. This script will transform the normalized identity provider’s profile object into an appropriate object that AM can use.
  
  Find the script in Realms > Realm Name > Scripts.
- In Client Type , select BROWSER when using the AM UI, or the ForgeRock SDK for JavaScript.
Configure the Required Attributes Present node and the Create Object node:

In the Identity Resource field, configure the relevant managed identity resource type. For example, managed/user or managed/alpha_user.

To check for the available managed identity resource types, go to the IDM admin UI, and open the Manage drop-down list, at the upper right corner of the screen.

Identity managed object types are preceded by the icon.

Configure the Attribute Collector node adding, at least, the mail, givenName, and sn attributes.

Configure social registration with account claiming

If your users have one or more social identity provider accounts, they can link them to the same AM account.

The following example builds on the basic social registration tree shown in Set up a basic social registration tree:

Example social authentication tree with account claiming

Figure 4. Example Social Registration Tree with Account Claiming

The tree uses the Identify Existing User node to determine if the user is already registered in AM. By default, the node checks whether the email address associated with the account is already registered in AM.

Ensure that you configure the Transformation Script in the Social Provider Handler node, and the Identity Resource field in the Patch Object node.

See Set up a basic social registration tree for tips.

Enabled

Specifies whether the provider is enabled.

Required: Yes.

Auth ID Key

Specifies the attribute the social identity provider uses to identify an authenticated individual. For example, id, sub, and user_id.

Required: Yes.

Client ID

Specifies the client_id parameter as described in section 2.2 of The OAuth 2.0 Authorization Framework specification.

Required: Yes.

Client Secret

Specifies the client_secret parameter as described in section 2.3 of The OAuth 2.0 Authorization Framework specification.

Required: No.

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. For example, https://accounts.google.com/oauth2/v2/auth.

Required: Yes.

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 specification. For example, https://www.googleapis.com/oauth2/v4/token.

Required: Yes.

User Profile Service URL

Specifies the user profile URL that returns profile information. For example, https://www.googleapis.com/oauth2/v3/userinfo.

This URL should return JSON objects in its response.

Required: No.

Token Introspection Endpoint URL

Specifies the URL to the endpoint handling access token validation, as described in the OAuth 2.0 Token Introspection specification. For example, https://oauth2.googleapis.com/tokeninfo.

Required: No.

Redirect URL

The URL to which the identity provider will redirect the user after authenticating, as described in Section 3.1.2 of The OAuth 2.0 Authorization Framework specification.

This URL is usually a page or path in AM; for example, https://platform.example.com:8443/am, and it is also registered in the identity provider’s service.

You can also use a custom URI scheme as the redirect, if you are using an app built with the ForgeRock SDKs for Android or iOS. For example, com.example.sdkapp:redirect_uri_path or frauth://com.forgerock.ios.sdkapp.

When using the FORM_POST response mode, you must specify the form_post endpoint in the redirection URL. See Response Mode for more information.
If you encounter domain validation prompts when using forgeblocks.com and id.forgerock.io domains as redirect URLs in your Google OAuth 2.0 applications, you must use a custom domain, and then set up domain verification with Google.
If you encounter No provider found errors when using forgeblocks.com and id.forgerock.io domains as redirect URLs in your OAuth 2.0 applications, either modify the redirect URL to include a realm identifier, or use a custom domain:
- Wrong:
  https://<tenant-name>.forgeblocks.com/am/oauth2/client/form_post/…
- Right:
  https://<tenant-name>.forgeblocks.com/am/oauth2/<realm>/client/form_post/…
  or
  https://<custom-domain>/am/oauth2/client/form_post/…
  
  A custom domain acts as a realm DNS alias, so when it is used as a redirect URL, Identity Cloud implicitly knows which realm to use.

Required: Yes.

Redirect after form post URL

Specifies the URL of a custom login page or application. AM will send processed form post data related to social login authentication to that URL as the value of the form_post_entry query parameter.

To continue the authentication journey, the custom login page is responsible for making a call to the AM /json/authenticate endpoint with the authentication ID (authID) and the processed form data (form_post_entry).

Configure this property when the following is true:

The FORM_POST response mode is configured.
Your users log in to AM using custom login pages, such as apps using the ForgeRock SDKs, instead of the AM UI.

Required: No.

Scope Delimiter

Specifies the delimiter used to separate scope values. For example, a blank space (kbd:[ ]), or a comma character (kbd:[,]).

Most providers use a blank space.

Required: Yes.

OAuth Scopes

Specifies the list of scopes to request from the provider.

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

For example, Google exposes its supported scopes in their OAuth 2.0 Scopes for Google APIs documentation.

Required: Yes.

Client Authentication Method

Specifies how the client should authenticate to the provider. Possible values are:

CLIENT_SECRET_POST. The client sends the client ID and the secret in the client_ID and the client_secret parameters in the body of the request.
CLIENT_SECRET_BASIC. The client sends the client ID and the secret in a basic authorization header with the base64-encoded value of client-id:client-secret.
PRIVATE_KEY_JWT. The client sends its credentials to the provider in a signed JWT as specified in the JSON Web Token (JWT) Profile for OAuth 2.0 Client Authentication and Authorization Grants.
ENCRYPTED_PRIVATE_KEY_JWT. The client sends its credentials to the provider in a signed, then encrypted JWT as specified in the JSON Web Token (JWT) Profile for OAuth 2.0 Client Authentication and Authorization Grants.

Some authentication methods require additional configuration:
How do I configure JWT authentication with signed JWTs?
1. Obtain a list of supported signing algorithms from the provider’s .well-known endpoint, and decide which one you will use.
2. In the Private Key JWT Signing Algorithm field, enter the signing algorithm that AM will use to sign the JWT. For example, RSA256.
  
  This field may already be configured if the client is sending request objects.
3. Provide a JWK with the public key to the identity provider. Refer to their documentation for more information.
  
  For example, you could copy the contents of the public JWK in a field in the provider’s service configuration, or you could configure the realm’s /oauth2/connect/rp/jwk_uri endpoint, which exposes the client’s public keys.
  
  Configure the realm’s /oauth2/connect/rp/jwk_uri endpoint in the provider, which exposes the client’s public keys. Refer to the provider’s documentation for more information.
4. Change the value in the Private Key JWT Expiration Time (seconds) field, if needed. It has a sensible value preconfigured, but you may need to tune it for your provider.
How do I configure JWT authentication with signed and encrypted JWTs?
1. Follow the steps in How do I configure JWT authentication with signed JWTs? to configure AM to sign authentication JWTs.
  
  Now you are ready to configure AM to encrypted authentication JWTs.
2. Obtain a list of supported encryption algorithms and methods from the provider’s .well-known endpoint, and decide which one you will use.
3. In the JWT Encryption Algorithm field, select the encryption algorithm.
  
  If the required encryption algorithm does not appear in the drop-down, check the reference entry for the JWT Encryption Algorithm field for information on how to add it.
  
  This field may already be configured if the client is encrypting request objects.
4. In the JWT Encryption Method field, select the encryption method.
  
  This field may already be configured if the client is encrypting request objects.
5. In the JWKS URI Endpoint field, configure the URI containing the provider’s public JWK set.
  
  Obtain the URI from the provider’s .well-known endpoint, or their documentation.
  
  AM will use the JWK URI to fetch the provider’s public encryption key.
6. Perform one of the following steps depending on the encryption method you configured:
  
  If you chose Direct AES Encryption method, select NONE in the JWT Signing Algorithm field. Signing is redundant with this encryption method.
  
  If you chose an encryption method different from the Direct AES Encryption method, configure signing. For more information, see How do I configure JWT authentication with signed JWTs?.
Required: Yes.

PKCE Method

Specifies the PKCE transformation method AM uses when making requests to the provider’s authorization endpoint, as specified in Section 4.2 of the Proof Key for Code Exchange by OAuth Public Clients specification.

Select NONE to disable PKCE transformations.

Required: No.

Request Parameter JWT Option

(OpenID Connect providers only) Specifies whether AM should provide a request object JWT to the provider. Possible values are:

NONE. AM does not send a request object to the provider.

REFERENCE. The request object JWT is stored in AM’s CTS token store, and AM exposes a unique identifier for it using the oauth2/request_uri endpoint for the realm. The URL to the endpoint and the JWT’s unique identifier are passed to the provider in the request_uri parameter of the request.

Ensure that the provider can reach the endpoint.

An example of the URL is https://platform.example.com:8443/am/realms/root/realms/myRealm/oauth2/request_uri/requestobjectID

When integrating with itsme^®, ensure that the base URL of AM contains the 443 port. For example, https://platform.example.com:443/am.

To do this, configure the Base URL Source service:

In the AM admin UI, go to Realms > Realm Name > Services.
Add a Base URL Source service if one is not already configured, or select it to change its properties:

VALUE. AM appends the JWT as the value of the request parameter of the request.
How do I configure the client to send signed request objects?
1. In the Request Parameter JWT Option field, select either VALUE or REFERENCE.
  
  Refer to your identity provider’s documentation for more information.
2. Obtain a list of supported signing algorithms from the provider’s .well-known endpoint, and decide which one you will use.
3. In the JWT Signing Algorithm field, select the signing algorithm that AM will use to sign the request object. For example, RS256.
  
  This field may already be configured if the client is using JWT client authentication.
4. Provide a JWK with the public key to the identity provider. Refer to their documentation for more information.
  
  For example, you could copy the contents of the public JWK in a field in the provider’s service configuration, or you could configure the realm’s /oauth2/connect/rp/jwk_uri endpoint, which exposes the client’s public keys.
  
  Configure the realm’s /oauth2/connect/rp/jwk_uri endpoint in the provider, which exposes the client’s public keys. Refer to the provider’s documentation for more information.
How do I configure the client to send signed and encrypted request objects?
1. Follow the steps in How do I configure the client to send signed request objects? to configure AM to send signed request objects.
  
  Now you are ready to configure AM to send encrypted request objects.
2. Enable Encrypt Request Parameter JWT.
3. Obtain a list of supported encryption algorithms and methods from the provider’s .well-known endpoint, and decide which one you will use.
4. In the JWT Encryption Algorithm field, select the encryption algorithm.
  
  If the required encryption algorithm does not appear in the drop-down, check the reference entry for the JWT Encryption Algorithm field for information on how to add it.
  
  This field may already be configured if the client is encrypting authentication JTWs.
5. In the JWT Encryption Method field, select the encryption method.
  
  This field may already be configured if the client is encrypting authentication JWTs.
6. In the JWKS URI Endpoint field, configure the URI containing the provider’s public JWK set.
  
  Obtain the URI from the provider’s .well-known endpoint.
  
  AM will use the JWK URI to fetch the provider’s public encryption key.
7. Perform one of the following steps depending on the encryption method you configured:
  
  If you chose Direct AES Encryption method, select NONE in the JWT Signing Algorithm field. Signing is redundant with this encryption method.
  
  If you chose an encryption method different from the Direct AES Encryption method, configure signing. For more information, see How do I configure the client to send signed request objects?.

Encrypt Request Parameter JWT

Specifies whether the request parameter must be encrypted when Request Parameter JWT Option is set to REFERENCE or VALUE.

ACR Values

(OpenID Connect providers only) Specifies a space-separated list, in order of preference, of the client’s acr values.

Required: No.

Well Known Endpoint

(OpenID Connect providers only) Specifies the URL for retrieving information about the provider, such as endpoints, and public keys. For example, https://accounts.google.com/.well-known/openid-configuration.

Required: Yes.

Request Object Audience

(OpenID Connect providers only) Specifies the intended audience (aud) of the request object when the Request Parameter JWT Option field is set to VALUE or REFERENCE.

When not configured, the value of the Issuer field will be used as the audience of the request object.

OP Encrypts ID Tokens

(OpenID Connect providers only) Specifies whether the provider encrypts ID Tokens.

How do I configure AM to receive encrypted tokens?

Provide a JWK with the public key to the identity provider. Refer to the identity provider’s documentation for more information.

For example, you could copy the contents of the public JWK in a field in the provider’s service configuration, or you could configure the realm’s /oauth2/connect/rp/jwk_uri endpoint, which exposes the client’s public keys.

Configure the realm’s /oauth2/connect/rp/jwk_uri endpoint in the provider, which exposes the client’s public keys. Refer to the provider’s documentation for more information.

Required: No.

Issuer

(OpenID Connect providers only) Specifies the issuer of ID Tokens. Must exactly match the value returned in the ID token.

Obtain the issuer value from the provider’s .well-known endpoint.

Required: Yes.

Enable Native Nonce

(OpenID Connect providers only) When enabled, the provider native SDK must include a nonce claim in the ID token. The value of the claim must be the value of the nonce claim sent in the Authentication Request.

Required: No.

User Info Response Format

(OpenID Connect providers only) Specifies the format in which the provider’s userinfo endpoint returns data.

Some options require additional configuration:

How do I configure the client to receive signed userinfo JWTs?

In the JWKS URI Endpoint field, configure the URL containing the provider’s public JWK set. Obtain it from the provider’s .well-known endpoint, or their documentation.

AM will use this URL to fetch the provider’s public signing key.

How do I configure the client to receive signed, then encrypted userinfo JWTs?

Follow the steps in How do I configure the client to receive signed userinfo JWTs? to configure AM to receive signed JWTs.

Now you are ready to configure AM to receive encrypted JWTs.
Provide a JWK with the public key to the identity provider. Refer to the their documentation for more information.

For example, you could copy the contents of the public JWK in a field in the provider’s service configuration, or you could configure the realm’s /oauth2/connect/rp/jwk_uri endpoint, which exposes the client’s public keys.

Configure the realm’s /oauth2/connect/rp/jwk_uri endpoint in the provider, which exposes the client’s public keys. Refer to the provider’s documentation for more information.

Possible values are:

JSON. The provider’s userinfo endpoint returns a JSON object.
SIGNED_JWT. The provider’s userinfo endpoint returns a signed JWT.
SIGNED_THEN_ENCRYPTED_JWT. The provider’s userinfo endpoint returns a signed, then encrypted JWT.

JWKS URI Endpoint

Specifies the URI that contains the public keys of the identity provider. AM will use these keys to verify signatures, or to encrypt objects.

Configure this field when:

Client Authentication Method is set to ENCRYPTED_PRIVATE_KEY_JWT.
Encrypt Request Parameter JWT is enabled.
User Info Response Format is set to SIGNED_JWT or SIGNED_THEN_ENCRYPTED_JWT.

Required: No.

Claims

Any claims on the request object, in JSON format. These claims must conform to the claims request parameter, as defined in the OpenID Connect specification.

JWT Signing Algorithm

Specifies the signing algorithm supported by the provider that AM will use to sign the following:

Client authentication JWTs when Client Authentication Method is set to PRIVATE_KEY_JWT.
(OpenID Connect providers only) Request JWTs when Request Parameter JWT Option is set to VALUE or REFERENCE.

Obtain a list of the supported algorithms from the provider’s .well-known endpoint. Select NONE if the client will encrypt the JWT with the Direct AES Encryption method, because the signature will be redundant.
Required: No.

JWT Encryption Algorithm

Specifies the encryption algorithm supported by the provider that AM should use to encrypt client authentication JWTs when Client Authentication Method is set to PRIVATE_KEY_JWT, and (OpenID Connect providers only) request JWTs when Request Parameter JWT Option is set to VALUE or REFERENCE.

If set to NONE, AM will not encrypt the JWTs. Obtain a list of the supported algorithms from the provider’s .well-known endpoint.

Required: No.

JWT Encryption Method

Specifies the encryption algorithm supported by the provider that AM should use to encrypt the following:

Client authentication JWTs when Client Authentication Method is set to PRIVATE_KEY_JWT.
(OpenID Connect providers only) Request JWTs when Request Parameter JWT Option is set to VALUE or REFERENCE.

Use in conjunction with JWT Encryption Algorithm. Obtain a list of the supported methods from the provider’s .well-known endpoint.
Required: No.

Private Key JWT Expiration Time (seconds)

Specifies the amount of time, in seconds, that AM will cache the client authentication JWT before creating a new one.

Caching the JWT avoids creating a new one for every client authentication. However, it may also become invalid if the provider changes it configuration.

Required: No.

Response Mode

(OpenID Connect providers only) Specify the way the provider will return ID tokens to AM. Possible values are:

DEFAULT. The provider returns the ID token as query parameters, as explained in the OpenID Connect Core 1.0 incorporating errata set 1 specification.

Most preconfigured providers use the DEFAULT response mode.
FORM_POST. The provider returns the ID token by submitting an HTML form using the HTTP POST method, as explained in the OAuth 2.0 Form Post Response Mode specification.

When using this response mode, add the /oauth2/client/form_post/ClientConfigName URI to the Redirect URL, where ClientConfigName is the name of the social identity provider client that you are configuring. For example, https://platform.example.com:8443/am/oauth2/client/form_post/myAppleClient.

By default, the form_post endpoint processes the post data, encrypts it, and redirects with it back to the authentication tree to resume authentication.

However, environments using custom login pages need to configure the Redirect after form post URL property to redirect back to the custom login pages.

Required: Yes.

Request Native App for UserInfo

(Apple SSO) When enabled, this flag indicates that the native app can send the user’s userinfo in JSON format.

Apple returns the userinfo only once, when the user first consents to send their details, and not on subsequent authentication attempts. In addition, the user has the option not to consent to Apple sending their userinfo.

If you are progressively profiling the userinfo with data from other social providers (usually, using a Patch Object node), there is a risk of overwriting the user’s details with blank values when the user authenticates through Apple SSO.

To mitigate this risk, you can add a Scripted Decision node to your authentication journey that assesses whether the userinfo is provided and patches the object accordingly.

How do I use a Scripted Decision node to patch an object, based on the returned userinfo?

The normalized-profile-to-managed-user.js script sets a boolean flag (nameEmptyOrNull) that indicates whether the user’s firstName and lastName have been returned.

Create a custom script that uses this flag, then add a Scripted Decision node that calls your script. An example of a custom script that achieves this functionality follows:

if (sharedState.get('nameEmptyOrNull')) {
  outcome = 'true'
} else {
outcome = 'false'
}

The outcome of the Scripted Decision node will be either to patch the userinfo object or not to patch the userinfo object.

If you need to progressively profile the user information on every authentication, regardless of whether the user’s first name and last name are returned by the OIDC provider, you can use another Scripted Decision node that does the following:

If the user details are not present, route the userinfo patch through a Patch Object node, configured to ignore the firstName and lastName. (In the Ignored Fields list, add givenName to ignore the firstName and sn to ignore the lastName.)
If the user details are present, route the userinfo patch through a Patch Object node that patches the full object.

For information about using Scripted Decision nodes in authentication journeys, see Scripted Decision node.

For more information, see "First name and last name are missing when signing in to Identity Cloud or AM 7.x using Apple social sign-on" in the ForgeRock Knowledge Base.

Required: No.

UI Config Properties

Specifies a map of properties defined and consumed in the UI. The map affects how the identity provider’s logo will show on the login page.

AM common end user UI properties

buttonImage: A relative path to an image in the End User UI.
buttonCustomStyle: Any custom CSS you wish to apply to the button outside of normal End User UI styling.
buttonClass: Adds the specified class to the identity provider button, for any additional styling you want to apply.
buttonCustomStyleHover: Adds custom styling when the cursor is hovering over the button.
buttonDisplayName: The name of the identity provider, which will be included either on the button or in the button’s alt attribute, depending on styling.
iconFontColor: Specifies the color of the icon. You can use methods supported in CSS (such as white, or #ffffff).
iconClass: Adds the specified class to the identity provider icon, for any additional styling you want to apply.
iconBackground: The color for the background of the icon. You can use methods supported in CSS (such as white, or #ffffff).

Required: Yes.

Transform Script

Specifies a script to convert the provider’s raw profile object into a normalized object. An authentication tree will later convert the object again into attributes the AM can use.

AM provides scripts for the preconfigured identity providers; they are ready to use, and suitable for most use cases.

To write a script in Javascript for an identity provider, go to Realms > Realm Name > Scripts, and use the provided scripts as a reference.

Transformation script information and example

The following is the default JavaScript transformation script for Google:

(function () {
    var frJava = JavaImporter(
        org.forgerock.json.JsonValue
    );

    var normalizedProfileData = frJava.JsonValue.json(frJava.JsonValue.object());

    normalizedProfileData.put('id', rawProfile.get('sub'));
    normalizedProfileData.put('displayName', rawProfile.get('name'));
    normalizedProfileData.put('givenName', rawProfile.get('given_name'));
    normalizedProfileData.put('familyName', rawProfile.get('family_name'));
    normalizedProfileData.put('photoUrl', rawProfile.get('picture'));
    normalizedProfileData.put('email', rawProfile.get('email'));
    normalizedProfileData.put('username', rawProfile.get('email'));
    normalizedProfileData.put('locale', rawProfile.get('locale'));

    return normalizedProfileData;
}());

The script returns a JsonValue object with all the mapped ojects.

Each field is mapped using a key and corresponding value in the following format: ("platformAttributeName", rawProfile.get(providerAttributeName)).

For example, id is the platform attribute name, while rawProfile.get('sub') is the value received from the provider.

Note that some field names are the same, for instance email and rawProfile.get('email'). These fields still need to be mapped, so they are included in the returned JsonValue object.

The social authentication nodes expect every attribute to have a value. In other words, the attributes returned by the identity provider cannot be empty, or null. If any of the attributes is empty or null, the social authentication tree journey will end with an error.

For example, if a user tries to log in using Google as the identity provider, but they did not configure a surname in their account, Google will return null as the value of the familyName for the identity, and social authentication will fail.

Ensure that all the users have their social profiles configured correctly, or modify the transformation scripts so that they not collect attributes that may be empty.

Required: Yes.

Suspended authentication

Suspended authentication lets you save a user’s progress through an authentication tree, and later resume from the same point.

Any input provided during authentication is saved when the authentication tree is suspended, and restored when the authentication tree is resumed. This lets the authentication tree continue after closing the browser, using a different browser, or even on a different device.

When suspending an authentication tree, you provide the user with a URL they must visit to resume their authentication. That URL contains a unique identifier for retrieving the saved progress, and can only be used once. These URLs are sometimes referred to as magic links.

The Email Suspend node supports suspended authentication.

Typical use cases include passwordless authentication, and email verification during progressive profile completion.

The following example lets a user authenticate if they have forgotten their username:

After obtaining the user’s email address in the Attribute Collector node, the example tree attempts to identify the user. Then, the tree attempts to email the user, and suspends itself.

Note that both the True and False outcomes are mapped into the Email Suspend node to reduce potential data leakage. If the username is found, it is included in the email sent to the user, along with the link to use to resume the authentication tree.

When the user follows the link, the authentication tree resumes at the Inner Tree Evaluator node, which lets the user authenticate with their recovered username and credentials.

Configure suspended authentication

You can configure the length of time an authentication session can last for in AM, so that resources can be freed up from incomplete authentications. You can also configure the length of time that a tree can be suspended.

You should set this value to the minimum reasonable time required to complete the authentication. For example, if you are sending an email, 10 minutes might be reasonable. The time allowed for suspending authentication must be the same or less than the maximum duration for the tree.

To configure these timeouts, in the AM admin UI, go to Authentication > Settings > Trees. For more information about the properties, see Trees.

MFA: Web authentication (WebAuthn)

Web authentication lets users authenticate by using an authenticator device, for example the fingerprint scanner on their laptop or phone.

Communication with the authentication devices is handled by the user’s browser. AM requests that the browser activates authenticators with certain criteria; for example it must be built-in to the platform rather than a roaming USB device, and/or that it must verify the identity of the user, rather than simply that a user is present.

To use WebAuthn with AM, users must first register their authenticators. If recovery codes are enabled, users must also make a copy of their codes.

Registration involves the selected authenticator creating, or minting, a key pair. The public key of the pair is returned to AM and stored in the user’s profile. The private key is stored securely, either in the authenticator itself, or in the platform managing the authenticators. The private key does not leave the client at any time.

When authenticating by using WebAuthn, the authenticator locks some data using the stored private key, which is sent to AM to verify using the public key stored in the user’s profile. If the data is verified as being from the correct device, and passes any attestation checks, the authentication is considered successful.

AM supports web authentication in the following user agents and platform minimum versions:

Table 6. Minimum Web Authentication User Agent Versions
User Agent	Platform	Version	Supported?
Google Chrome	Desktop	70	✔
Google Chrome	Android	70	✔
Microsoft Edge	Desktop	18	✔
Mozilla Firefox	Desktop	60	✔

Create trees for web authentication (WebAuthn)

This section explains how to create an authentication tree to authenticate users by using a WebAuthn device, and allow them to register a device if they have not already done so.

If the user has already registered a WebAuthn device, they only need to enter their username, and then perform the authorization gesture with their registered device to access their profile.

If the user does not have a registered device, they are prompted for their password, and must be verified by the Data Store Decision node before registering a new WebAuthn device. Once completed, they must authenticate with the new device before gaining access to their profile page.

This procedure assumes the following:

The WebAuthn Profile Encryption Service is configured.

This service specifies the attribute in which to store information about registered WebAuthn devices, and whether to encrypt that information.

For detailed information about the available properties, see WebAuthn Profile Encryption Service.

The tree created in this procedure is an example, and does not provide user-friendly features, such as allowing retries of the users' password.

To create a multi-factor authentication tree for WebAuthn authentication, and registration if required, perform the following steps:

In the AM admin UI, go to Realms > Realm Name > Authentication > Trees.
Create the authentication tree as follows:
- Click Create Tree.
  
  The New Tree page appears.
- Specify a name of your choosing, for example, myWebAuthnTree, and then click Create.
  
  The authentication tree designer is displayed, with the start entry point connected to the failure exit point.
  
  You can add nodes to the authentication tree by dragging the node from the Components panel on the left-hand side and dropping it into the designer area.
- Add the following nodes to the authentication tree:
- Connect the nodes as demonstrated in the following figure:
- Save your changes.

Test your WebAuthn authentication and registration tree as follows:

Log out of AM, and then go to a URL similar to the following: https://<tenant-name>.forgeblocks.com/am/XUI/?realm=/alpha&service=myWebAuthnTree#login

You must connect over HTTPS in order to use Web Authentication.

A login screen prompting you to enter your user ID appears.
Enter the username of an existing account in the specified realm. For example, enter demo.

If the demo user does not have a registered device:

When asked for the user’s password, enter the default Ch4ng31t.

At the following screen, register a WebAuthn authenticator by performing an authorization gesture, for example press the button on a connected Yubikey.

Figure 5. The WebAuthn Registration node waiting for an authenticator

The user’s browser may present a consent pop-up to allow access to the authenticators available on the client. When consent has been granted, the browser activates the relevant authenticators, ready for registration.

If the device registration is successful, the user is redirected to the new node in the tree in order to authenticate with the newly registered device.

When prompted, authenticate to AM by performing an authorization gesture with a registered device.

If the authorization is verified, the user’s profile page is displayed.
- Click the Dashboard link to see a list of the registered WebAuthn authenticators, and to rename or delete them. The default name for a new device is New Security Key.

Configure usernameless authentication with ForgeRock Go

With ForgeRock Go, you can create a secure and seamless login experience by authenticating with any credential on the user’s device that supports FIDO2 WebAuthn.

You can also extend passwordless authentication to include usernameless authentication with popular authenticators that support resident keys; for example, Windows Hello (biometric authenticators).

To use usernameless authentication, you must register an authenticator that supports resident keys to the user’s profile, and enable the option to associate a certificate on the device with the user’s username.

Once registered, that device can be used to authenticate the user without them having to provide their credentials; they just have to select the appropriate entry to use from the list their device provides.

To configure usernameless authentication with ForgeRock Go, create a Web Authentication registration tree to associate a device that supports resident keys with a user. The registration tree is similar to that described in Create trees for web authentication (WebAuthn).

Create a second tree that lets users authenticate to AM without entering their username or password, by using Forgerock Go.

The trees in this procedure are examples, and do not provide user-friendly features, such as allowing retries, or redirecting to further help on failures.

In the AM admin UI, select the realm that will contain the ForgeRock Go registration tree.
Create the registration tree as follows:
- Select Authentication > Trees, and click Create Tree.
  
  The New Tree page appears.
- Specify a name of your choosing, for example, fr-go-reg, and click Create.
  
  The authentication tree designer is displayed, with the start entry point connected to the failure exit point.
  
  You can add nodes to the authentication tree by dragging the node from the Components panel on the left side and dropping it into the designer area.
- Add the following nodes to the authentication tree:
  - Platform Username node
  - Platform Password node
  - WebAuthn Authentication node
  - Data Store Decision node
  - (Optional) Scripted Decision node
    
    When configured for ForgeRock Go, the WebAuthn Registration node will store the value of the username authentication tree shared state variable in the device by default. This value will later be used to identify the user during authentication.
    
    Use a Scripted Decision Node to customize the display name or string to be saved in the shared state. You will later configure the variable containing the data in the WebAuthn Registration node.
    
    Example JavaScript to create display names
    
    var username = sharedState.get("username"); var displayName = ''; var fullName = idRepository.getAttribute(username, "CN").iterator().next(); var email = idRepository.getAttribute(username, "mail").iterator().next(); if(fullName){ displayName += fullName; } if(email){ displayName += ' (' + email + ')'; } sharedState.put("displayName", displayName.toString()); outcome = "continue";
  - (Optional) Page node
- Connect the nodes as demonstrated in the following figure:
- In the WebAuthn Registration node properties, ensure Username to device is enabled.
- (Optional) If you are using a Scripted Decision node to create the display name, enter the shared state variable name into the Shared state attribute for display name property in the WebAuthn Registration node.
- (Optional)
  
  If you are not using the Scripted Decision node to create the display name, enter userName into the Shared state attribute for display name property in the WebAuthn Registration node.
- Save your changes.
Create an authentication tree for ForgeRock Go, and specify a name of your choosing; for example, fr-go-auth.
- Add a WebAuthn Authentication node to the authentication tree.
- Connect the nodes as demonstrated in the following figure:
- In the WebAuthn Authentication node properties, ensure Username from device is enabled.
- Save your changes.
You are now ready to register a device, and authenticate by using ForgeRock Go.

Proceed to Register and authenticate with ForgeRock Go.

Register and authenticate with ForgeRock Go

Follow these steps to register a device for use with usernameless authentication, and then authenticate without having to provide your username or password.

To register a device for use with ForgeRock Go:
- Log out of AM, and then go to your ForgeRock Go registration tree, with a URL similar to the following: https://<tenant-name>.forgeblocks.com/am/XUI/?realm=/alpha&service=fr-go-reg#login
  
  You must connect over HTTPS in order to use Web Authentication.
  
  A login screen prompting you to enter your credentials appears.
- Enter the username and password of an existing account in the specified realm. For example, enter demo, and the password Ch4ng31t, and then click btn:[Log In].
- If you are authenticating from a FIDO2-enabled device, a dialog will display asking you to choose the method to verify your identity; for example, a USB security key, or built-in biometric sensor.
  
  Select the option you want to associate with the user.
- Perform the authorization gesture of the chosen option when asked to do so. For example, scan your fingerprint with TouchID, or press the button on your USB security key.
  
  If successful, you are taken to the profile page for the user.
- The new device appears on the Dashboard page, as New Security Key.
  
  Give a suitable name to the device; for example, Apple Mac TouchID, by clicking the context icon, , and selecting Settings.
To use a device to authenticate without username or password by using ForgeRock Go:
- Log out of AM, and then go to your ForgeRock Go authentication tree, with a URL similar to the following: https://<tenant-name>.forgeblocks.com/am/XUI/?realm=/alpha&service=fr-go-auth#login
  
  You must connect over HTTPS in order to use Web Authentication.
- Perform the authorization gesture of the chosen option when asked to do so. For example, scan your fingerprint with TouchID, or press the button on your USB security key.
  
  If successful, a list of the accounts associated with the authentication device displays:
  
  Note that in this example the user’s full name and email address appear, which were gathered by the Scripted Decision node from the user’s profile during registration.
- Select the account that you want to sign in.
  
  If successful, you are taken to the profile page for the user, without having to enter username or password credentials!

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

An example of the interaction between the ForgeRock Authenticator (Push) authentication module, AM services, and the ForgeRock Authenticator.

Figure 6. Overview of Push Authentication

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

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.
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 Manage devices for MFA.
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.
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.

AM begins to poll the CTS for an accepted response from the registered device.
The user responds to the notification on the registered device, which will open the ForgeRock Authenticator app. In the ForgeRock Authenticator app, the user approves the authentication request with either a swipe, or by using a fingerprint or face recognition on supported hardware.

For more information, see Test push authentication.

The app returns the response to the AM site.
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.

AM detects the accepted record and redirects the user to their profile page, completing the authentication.

The following table summarizes the tasks you need to perform to implement Push authentication in your environment:

Task	Resources
Configure authentication If you are planning to implement passwordless push authentication, see also Limitations of passwordless push authentication.	Create trees for push authentication and registration
Test push authentication After configuring AM, download the ForgeRock Authenticator app and test your configuration.	Test push authentication

Task

Resources

Configure authentication

If you are planning to implement passwordless push authentication, see also Limitations of passwordless push authentication.

Create trees for push authentication and registration

Test push authentication

After configuring AM, download the ForgeRock Authenticator app and test your configuration.

Test push authentication

Create trees for push authentication and registration

Push authentication uses authentication trees to receive push notifications and to perform the actual authentication itself.

Authentication trees can be used for passwordless authentication using push notifications. When configured for passwordless authentication, the authentication flow asks 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.

Before implementing passwordless push authentication, consider the Limitations of passwordless push authentication.

Create a tree for push authentication

The procedure assumes the following:

Users will provide user IDs and passwords as the first step of MFA.
A push notification will be sent to the device as a second factor to complete authentication.
The following services are configured:

ForgeRock Authenticator (Push) Service

Specifies the attribute in which to store information about the registered Push device, and whether to encrypt the data.

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 Configure Service Credentials (Push Auth, Docker) in Backstage in the ForgeRock Knowledge Base.

For detailed information about the available properties, see Push Notification Service.

To create an MFA tree, perform the following steps:

In the AM admin UI, go to Realms > Realm Name > Authentication > Trees, and create the authentication tree as follows:
- Select Authentication > Trees, and click Create Tree.
  
  The New Tree page appears.
- Specify a name of your choosing, for example myPushTree, and click Create.
  
  The authentication tree designer is displayed, with the start entry point connected to the failure exit point.
  
  You can add nodes to the authentication tree by dragging the node from the Components panel on the left-hand side and dropping it into the designer area.
- Add the following nodes to the authentication tree:
- Connect the nodes as demonstrated in the following figure:
  
  Figure 7. Example Push Tree
- Save your changes.
Test your authentication tree as follows:
- Log out of AM, and then navigate to a URL similar to the following: https://<tenant-name>.forgeblocks.com/am/XUI/?realm=/alpha&service=myPushTree#login
  
  A login screen prompting you to enter your user ID and password appears.
- Follow the procedure described in Test push authentication to verify that you can use the ForgeRock Authenticator app to perform MFA. If the authentication tree is correctly configured, authentication is successful and AM displays the user profile page.

Create a tree for passwordless authentication

The procedure assumes the following:

Users will provide only their user IDs as the first step of MFA.
This procedure assumes users have a device registered for push authentication.
A push notification will be sent to the device as a second factor to complete authentication, without the need to enter the user’s password.
The following services are configured:

ForgeRock Authenticator (Push) Service

Specifies the attribute in which to store information about the registered Push device, and whether to encrypt the data.

For detailed information about the available properties, see ForgeRock Authenticator (Push) Service.

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 Configure Service Credentials (Push Auth, Docker) in Backstage in the ForgeRock Knowledge Base.

For detailed information about the available properties, see Push Notification Service.

To create an MFA tree for passwordless authentication, perform the following steps:

In the AM admin UI, go to Realms > Realm Name > Authentication > Trees, and create the authentication tree as follows:
- Select Authentication > Trees, and click Create Tree.
  
  The New Tree page appears.
- Specify a name of your choosing, for example myPasswordlessAuthTree, and click Create.
  
  The authentication tree designer is displayed, with the start entry point connected to the failure exit point.
  
  You can add nodes to the authentication tree by dragging the node from the Components panel on the left-hand side and dropping it into the designer area.
- Add the following nodes to the authentication tree:
- Connect the nodes as demonstrated in the following figure:
  
  Figure 8. Passwordless Push Authentication Example
- Save your changes.
Test your authentication tree as follows:
- Log out of AM, and then navigate to a URL similar to the following: https://<tenant-name>.forgeblocks.com/am/XUI/?realm=/alpha&service=myPasswordlessAuthTree#login
  
  A login screen prompting you to enter your user ID appears.
- Follow the procedure described in Test push authentication to verify that you can use the ForgeRock Authenticator app to perform MFA. If the authentication tree is correctly configured, authentication is successful and AM displays the user profile page, without having to enter a password.

Test 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 sends a push notification to the registered device.

If the user does not yet have a device registered for push authentication, see Register.

The device needs access to the Internet to receive push notifications, and the AM server must be able to receive responses from the device.

Receive push notifications

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:

Slide the notification across the screen, then unlock the phone. The ForgeRock Authenticator app will automatically open and display the push notification authentication screen.
If the phone is not locked, and the ForgeRock Authenticator app is not open, the notification may appear similar to the following:

Tap the notification. The ForgeRock Authenticator app will automatically open and display the push notification authentication screen.
If the phone is not locked, and the ForgeRock Authenticator app is open, the app will open the push notification authentication screen automatically.

Approve requests

On the push notification authentication screen, approve the request using one of the following methods:

Slide the switch with a checkmark on horizontally to the right.
If the registered device supports Touch ID, and fingerprints have been provided, you can approve the request by using a registered fingerprint.

If the registered device supports face recognition and you have set up facial recognition, you can approve the request by glancing at your device.

AM will display the user’s profile page.

Deny requests

Deny the request by tapping the cancel icon in the top-right of the screen or, if Touch ID or face recognition are enabled, tap the Cancel button.

After a timeout has passed, AM will report that authentication has failed.

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 or in the Push Sender node.

Register

If your credentials are valid but the account does not have a device registered for push notifications, AM presents the MFA Registration Options screen:

Default text of the MFA Registration Options node.

Register Device: The journey continues to the Push Registration node, which displays the QR code that should be scanned with a suitable authenticator app.

For information on how to register the ForgeRock Authenticator for use with push authentication, follow the steps in Register the ForgeRock Authenticator for multi-factor authentication.
Get the App: The journey continues to the Get Authenticator App node, which displays the links needed to obtain a suitable app; for example, the ForgeRock Authenticator.
Skip this step: Displayed only if the node configuration allows the user to skip. In this example tree, skipping is linked to the Success node.
Opt-out: Displayed only if the node configuration allows the user to skip or opt out. The journey continues to the Opt-out Multi-Factor Authentication node, which updates the users' profile to skip MFA with push in the future. In this example, after updating the profile, the journey continues to the Success node.

Once the registration is complete, the path returns to the Push Sender node, which starts the actual push notification stage of the journey. See Receive push notifications.

Limitations of passwordless push authentication

When authenticating to a passwordless push authentication tree, the user is 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 MFA, and not on their own.

MFA: Open AuTHentication (OATH)

The ForgeRock Authenticator (OATH) nodes support 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 (OTP) 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 Reset registered devices 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.

One-time password authentication

This section describes how to create and configure trees for one-time password authentication.

Create a tree for one-time password authentication

To create an example authentication tree that uses OATH authentication, perform the following steps:

In the AM admin UI, select the realm that will contain the authentication tree.
Select Authentication > Trees, and click +Create Tree.
Type a name for your tree in the New Tree page; for example, myAuthTree, and click Create.

The authentication tree designer page is displayed with default start, failure, and success nodes.

For information about using the authentication tree designer, see Create an authentication tree.
Add the following nodes to the designer area:
Connect the nodes as shown:
Type 'OATH' to filter the list of nodes in the search box:
Drag an OATH Token Verifier node and an OATH Registration node onto the designer area.
For both OATH nodes, set the OATH Algorithm property to TOTP, and connect to the existing nodes as follows:

The value for OATH Algorithm must be the same for both nodes. For this example, select TOTP to generate a new OTP at a specified time step interval.
Save your changes.

Note that the tree you have created is a simple example for the purposes of demonstrating a basic OATH authentication journey. In a production environment, you could include additional nodes, such as:

MFA Registration Options node

Provides options for users to register a multi-factor authentication device, get the authenticator app, or skip the registration process.

Opt-out Multi-Factor Authentication node

Sets an attribute in the user’s profile which lets them skip multi-factor authentication.

Recovery Code Display node

Lets a user to view recovery codes to use in case they have lost or damaged their registered authenticator device.

Retry Limit Decision node

Lets a journey loop a specified number of times, for example, to allow a user to retry entering their OATH token.

For information about how to configure these nodes, see Authentication nodes configuration reference.
Test your authentication tree as follows:
- Log out of AM, and then navigate to a URL similar to the following: https://openam.example.com:8443/openam/XUI/?realm=alpha&service=myAuthTree#login
  
  A login screen appears, prompting you to enter your user ID and password.
- Log in using the user name and password. For example, enter demo, and the password Ch4ng31t.
- On successful login, if the screen displays a QR code, you will need to register your device.
  
  To register the device with the ForgeRock Authenticator, follow the instructions as described in Register the ForgeRock Authenticator for MFA.
- Follow the procedure described in Authenticate using a one-time password to verify that you can authenticate using the ForgeRock Authenticator app.

Authenticate using a one-time password

This example task assumes the following prerequisites:

The authentication tree is set up as described in Create a tree for one-time password authentication.
You have successfully logged in with valid credentials.
You have registered your device for ForgeRock Authenticator (OATH) authentication.

Follow these steps to complete one-time password (OTP) authentication:

On your registered device, open the ForgeRock Authenticator app, and then tap the OTP section for the account matching the user ID. For example:
Note the OTP that is displayed on the screen. This is automatically refreshed at an interval defined in the OATH node configuration. If the animated timer indicates the OTP is close to expiry, wait until a new OTP is generated.
On the ForgeRock Authenticator (OATH) page in AM, enter the OTP that the authenticator app generated on your phone, and then click Submit:

AM displays the user’s profile page.

Manage devices for MFA

Multi-factor authentication requires you to register a device, which is used as an additional factor when you log in to AM.

The following table summarizes different tasks related to devices used for multi-factor authentication:

Task	Resources
Learn about the ForgeRock Authenticator Download the ForgeRock Authenticator app, which supports push authentication notifications and one-time passwords, and register it in AM.	The ForgeRock Authenticator app
Recovering user accounts Learn how to recover a user account when the user has lost their registered device, or when their device has become out of sync with AM.	Recover after replacing a lost device Recover after a device becomes out of sync
Reset registered devices In some scenarios, for example, when users are not able to access their recovery codes, you may need to reset their registered devices to allow them to register again.	Reset registered devices using REST

Task

Resources

Learn about the ForgeRock Authenticator

Download the ForgeRock Authenticator app, which supports push authentication notifications and one-time passwords, and register it in AM.

The ForgeRock Authenticator app

Recovering user accounts

Learn how to recover a user account when the user has lost their registered device, or when their device has become out of sync with AM.

Reset registered devices

In some scenarios, for example, when users are not able to access their recovery codes, you may need to reset their registered devices to allow them to register again.

Reset registered devices using REST

The ForgeRock Authenticator app

The ForgeRock Authenticator app supports push authentication notifications and one-time passwords.

Download and install the ForgeRock Authenticator app on your phone, so that you can perform multi-factor authentication. The app is available for both Android and iOS devices, and is free to download from:

For access to the source code for sample mobile applications, see How do I access and build the sample code provided for AM/OpenAM (All versions)? in the ForgeRock Knowledge Base.

Register the ForgeRock Authenticator for multi-factor authentication

Registering the ForgeRock Authenticator app enables it to be used as an additional factor when logging in to AM.

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.

For information on registering Web Authentication (WebAuthn) devices with AM, see Create trees for Web Authentication (WebAuthn).

ForgeRock Authenticator 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 registration with the identity provider is repeated for that additional method.

The ForgeRock Authenticator 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.

When visiting a protected resource without having any registered devices for multi-factor authentication, AM requires that you register a device.

To register your mobile phone with AM, click Register Device. A screen with a QR code appears:
Start the ForgeRock Authenticator app on the device to register, and then click the plus icon:

The screen on the device changes to an interface similar to your camera app.
Point the camera at the QR code on the 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.
Once registered, 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):
When registering a device, you MUST make a copy of the recovery codes associated with that device.

Depending on the device type you registered, perform one of the following steps:
1. If you registered an OATH device:
  - Click the Login Using Verification Code button.
    
    You will be asked to enter a verification code.
  - In the ForgeRock Authenticator app, select the newly registered account, and click the refresh button to generate a new one-time password.
  - Enter the one-time password into the web page, and click Submit.
  - On the recovery codes page, make a copy of the displayed recovery codes and store them safely. The codes will never be displayed again.
    
    When you have safely stored the recovery codes for your newly registered OATH device, click the Continue button.
2. If you registered a push device:
  - On the recovery codes page, make a copy of the displayed recovery codes and store them safely. The codes will never be displayed again.
    
    When you have safely stored the recovery codes for your newly registered push device, click the Continue button.

Your device is now registered. You will able to use it to perform multi-factor authentication.

Recover 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. Perform the following steps:

Register a new device after losing a registered device

Log in to AM.

If push authentication is enabled, enter your user ID, click Log In > 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.
Select Dashboard from the top-level menu.
Locate the entry for your phone in the Authentication Devices section, click the context menu button, and click Delete.
If you have not already done so, install the ForgeRock Authenticator app on your new phone.

See The ForgeRock Authenticator app.
Register your new device. See Registering the ForgeRock Authenticator 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 Reset registered devices using REST for more information.

Recover 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 Recover after replacing a lost device.

Reset registered devices using REST

As described in Recover 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.

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.

The following example resets the OATH devices of a user named myUser in a realm called mySubrealm:

$ curl \
--request POST \
--header "Content-Type: application/json" \
--header "Accept-API-Version: resource=1.0" \
--header "<session-cookie-name>: AQIC5w…2NzEz*" \
--data '{}' \
'https://<tenant-name>.forgeblocks.com/am/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 on the /users/user/devices/2fa/push?_action=reset endpoint as follows:

$ curl \
--request POST \
--header "Content-Type: application/json" \
--header "Accept-API-Version: resource=1.0" \
--header "<session-cookie-name>: AQIC5w…2NzEz*" \
--data '{}' \
'https://<tenant-name>.forgeblocks.com/am/json/realms/root/realms/mySubrealm/users/myUSER/devices/2fa/push?_action=reset"'
{
    "result":true
}

Reference

This reference covers settings and the scripting API for authentication in AM.

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 edit the authentication configuration in a realm, navigate to Realms > Realm Name > Authentication > Settings in the AM admin UI.

Core

The following properties are available under the Core tab:

Administrator Authentication Configuration: Specifies the default authentication journey used when an administrative user, such as amAdmin, logs in to the AM admin UI.
Organization Authentication Configuration: Specifies the default authentication journey used when a non-administrative user logs in to AM.

amster attribute: orgConfig

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.

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.

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.

amster attribute: aliasAttributeName

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.

amster attribute: loginFailureLockoutMode
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.

amster attribute: loginFailureCount
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.

amster attribute: loginFailureDuration
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.

amster attribute: lockoutEmailAddress
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.
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.

amster attribute: lockoutDuration
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.

amster attribute: lockoutDurationMultiplier
Lockout Attribute Name: Defines the LDAP attribute used for physical lockout. The default attribute is inetuserstatus, although the field in the AM admin UI is empty. The Lockout Attribute Value field must also contain an appropriate value.

amster attribute: lockoutAttributeName
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 admin UI is empty. The Lockout Attribute Name field must also contain an appropriate value.

amster attribute: lockoutAttributeValue
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 admin UI, AM stores this data in the sunAMAuthInvalidAttemptsDataAttrName attribute defined in the sunAMAuthAccountLockout objectclass by default.

amster attribute: invalidAttemptsDataAttributeName
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.

amster attribute: storeInvalidAttemptsInDataStore

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.

amster attribute: locale

Identity Types

Lists the type or types of identities used during a profile lookup. You can choose more than one type; this lets AM conduct a second lookup if the first lookup fails.

The Identity Types property does not apply to Identity Cloud.

amster attribute: identityType

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.

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.

amster attribute: statelessSessionsEnabled

External Login Page URL

Specifies the URL of the external login user interface, if the authentication user interface is hosted separately from AM.

When set, AM will use the provided URL as the base of the resume URI, rather than using the Base URL Source Service to obtain the base URL. AM will use this URL when constructing the resume URI if authentication is suspended in an authentication tree.

amster attribute: externalLoginPageUrl

Default Authentication Level

Specifies the default authentication level for authentication nodes.

The Default Authentication Level property does not apply to Identity Cloud.

amster attribute: defaultAuthLevel

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.

For more information on authentication session storage locations, and the requirements for each, see Sessions and cookies.

Default: JWT (new installations), In-Memory (after upgrade)

amster attribute: authenticationSessionsStateManagement

Max duration (minutes)

Specifies the maximum allowed duration of an authentication session, including any time spent in the suspended state, in minutes.

Values from 1 to 2147483647 are allowed.

Default: 5

amster attribute: authenticationSessionsMaxDuration

Suspended authentication duration (minutes)

Specifies the length of time an authentication session can be suspended, in minutes.

Suspending an authentication session allows time for out-of-band authentication methods, such as responding to emailed codes or performing an action on an additional device. The value must be less than or equal to the total time allowed for an authentication session, specified in the Max duration (minutes) property.

Values from 1 to 2147483647 are allowed.

Default: 5

Enable whitelisting

When enabled, AM allowlists authentication sessions to protect them against replay attacks.

Default: Disabled

amster attribute: authenticationSessionsWhitelist

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.

The Module Based Authentication property does not apply to Identity Cloud.

amster attribute: moduleBasedAuthEnabled

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

amster attribute: keyAlias

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.

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)

The Zero Page Login property does not apply to Identity Cloud.

amster attribute: zeroPageLoginEnabled

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.

The Zero Page Login Referer Whitelist property does not apply to Identity Cloud.

amster attribute: zeroPageLoginReferrerWhiteList

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.

amster attribute: zeroPageLoginAllowedWithoutReferrer

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

amster attribute: sharedSecret

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.

amster attribute: loginSuccessUrl

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.

amster attribute: loginFailureUrl

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.

The Authentication Post Processing Classes property does not apply to Identity Cloud.

For information about post-authentication processing for trees, see Create Post-Authentication Hooks for Trees.

amster attribute: loginPostProcessClass

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.

The Generate UserID Mode property does not apply to Identity Cloud.

amster attribute: usernameGeneratorEnabled

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.

amster attribute: usernameGeneratorClass

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.

The User Attribute Mapping to Session Attribute property does not apply to Identity Cloud.

For authentication trees, use the Scripted Decision node to retrieve user attributes and session properties, or the Set Session Properties node for session properties only.

amster attribute: userAttributeSessionMapping

Supported callbacks

For more information about how to use callbacks to authenticate to AM, see Return callback information to AM.

The following types of callbacks are available:

Callback Type

Description

Interactive

AM returns these callbacks to request information from the user.

Read-Only

AM uses these callbacks to return information to the client or to show information to the user.

Backchannel

AM uses backchannel callbacks when it needs to recover additional information from the user’s request. For example, when it requires a particular header or a certificate.

Interactive callbacks

AM returns the following callbacks to request information from the user:

BooleanAttributeInputCallback

On a ForgeRock Identity Platform deployment, this callback is used to ask for a boolean-style confirmation, such as yes/no, or true/false, and retrieve the response.

Used to ask for a boolean-style confirmation, such as yes/no, or true/false, and retrieve the response.

Differs from the ConfirmationCallback in that the BooleanAttributeInputCallback can be used with IDM policy information to validate the input against the managed user schema. For use examples, see the Attribute Collector node.

Callback output object reference

name. A string containing the name of the attribute in the user profile.
prompt. A string containing the description of the attribute. In other words, a description of the information required from the user.
required. A boolean indicating whether input is required for this attribute.
policies. One or more JSON objects describing validation policies that the provided input is required to pass. The object will be empty if validation is disabled in the Attribute Collector node.

The node collects policy information from IDM. For information about the policies available by default, see Default policy for managed objects in the IDM documentation.
failedPolicies. One or more JSON objects describing validation policies that the input failed. The object will only be populated after input has been submitted and validation failed.

Requires validation to be enabled in the Attribute Collector node.
validateOnly. A boolean indicating the state of this flag when previously submitted. If the UI returns this property as true in the input of the callback, the node will only perform input validation. The authentication journey will not continue to the next node.

This is useful for UIs to make validation checks as the user types instead of validating the input once and continuing the journey to the next node.

Requires validation to be enabled in the Attribute Collector node.
value. A string containing a default value for the attribute, if required.

Example

{
  "callbacks": [
    {
      "type": "BooleanAttributeInputCallback",
      "output": [
        {
          "name": "name",
          "value": "preferences/marketing"
        },
        {
          "name": "prompt",
          "value": "Send me special offers and services"
        },
        {
          "name": "required",
          "value": true
        },
        {
          "name": "policies",
          "value": {}
        },
        {
          "name": "failedPolicies",
          "value": []
        },
        {
          "name": "validateOnly",
          "value": false
        },
        {
          "name": "value",
          "value": false
        }
      ],
      "input": [
        {
          "name": "IDToken1",
          "value": false
        },
        {
          "name": "IDToken1validateOnly",
          "value": false
        }
      ]
    }
  ]
}

Return the value in the callback and the boolean that specifies whether validateOnly should be true.

Class to import: org.forgerock.openam.authentication.callbacks.BooleanAttributeInputCallback

ChoiceCallback

Used to display a list of choices and retrieve the selected choice. To indicate that the user selected the first choice, return a value of 0 to AM. For the second choice, return a value of 1, and so forth.

Example

"callbacks":[
   {
      "type":"ChoiceCallback",
      "output":[
         {
            "name":"prompt",
            "value":"Choose one"
         },
         {
            "name":"choices",
            "value":[
               "Choice A",
               "Choice B",
               "Choice C"
            ]
         },
         {
            "name":"defaultChoice",
            "value":2
         }
      ],
      "input":[
         {
            "name":"IDToken1",
            "value":0
         }
      ]
   }
]

Class to import: javax.security.auth.callback.ChoiceCallback

ConfirmationCallback

Used to ask for a boolean-style confirmation, such as yes/no or true/false, and retrieve the response. Also can present a "Cancel" option. To indicate that the user selected the first choice, return a value of 0 to AM. For the second choice, return a value of 1, and so forth.

Example

"callbacks":[
   {
      "type":"ConfirmationCallback",
      "output":[
         {
            "name":"prompt",
            "value":""
         },
         {
            "name":"messageType",
            "value":0
         },
         {
            "name":"options",
            "value":[
               "Submit",
               "Start Over",
               "Cancel"
            ]
         },
         {
            "name":"optionType",
            "value":-1
         },
         {
            "name":"defaultOption",
            "value":1
         }
      ],
      "input":[
         {
            "name":"IDToken1",
            "value":0
         }
      ]
   }
]

Class to import: javax.security.auth.callback.ConfirmationCallback

ConsentMappingCallback

On a ForgeRock Identity Platform deployment, this callback displays managed user attributes that require user consent. It also collects consent from the user.

Used to display managed user attributes that require consent, and to collect consent from the user.

Example

{
  "callbacks": [
    {
      "type": "ConsentMappingCallback",
      "output": [
        {
          "name": "name",
          "value": "managedUser_managedUser"
        },
        {
          "name": "displayName",
          "value": "Test Mapping"
        },
        {
          "name": "icon",
          "value": ""
        },
        {
          "name": "accessLevel",
          "value": "Actual Profile"
        },
        {
          "name": "isRequired",
          "value": true
        },
        {
          "name": "message",
          "value": "You consent to your data being shared with external services."
        },
        {
          "name": "fields",
          "value": []
        }
      ],
      "input": [
        {
          "name": "IDToken1",
          "value": false
        }
      ]
    }
  ]
}

The user must give consent to all attributes, or to none. Therefore, the input object for this callback is a single boolean value.

Class to import: org.forgerock.openam.authentication.callbacks.ConsentMappingCallback

DeviceProfileCallback

Used to request information about the device being used to authenticate.

The callback may request metadata and/or location information about the device by setting the relevant value to true in the JSON:

Example

"callbacks": [
    {
        "type": "DeviceProfileCallback",
        "output": [
            {
                "name": "metadata",
                "value": true
            },
            {
                "name": "location",
                "value": true
            },
            {
                "name": "message",
                "value": "Collecting....."
            }
        ],
        "input": [
            {
                "name": "IDToken1",
                "value": ""
            }
        ]
    }
]

The callback also contains the message entry, with optional text to display to the user while collecting the information.

The ForgeRock SDKs gather and return the requested information in a JSON abject, as well as the following elements:

identifier: A unique identifier string that can be used to later match the device.
alias: A friendly name for the device, often derived from the make and model.

Return an escaped JSON in the input object on the callback. It should include information resembling the following:

Callback Response Example

{
   "identifier":"aec3fe784...o3Xjiizyb9=",
   "alias":"Pixel 3 XL",
   "metadata":{
      "platform":{
         "platform":"Android",
         "version":28,
         "device":"generic_x86_arm",
         "deviceName":"AOSP on IA Emulator",
         "model":"AOSP on IA Emulator",
         "brand":"google",
         "locale":"en_US",
         "timeZone":"America/Vancouver",
         "jailBreakScore":1
      },
      "hardware":{
         "hardware":"ranchu",
         "manufacturer":"Google",
         "storage":774,
         "memory":1494,
         "cpu":4,
         "display":{
            "width":1440,
            "height":2621,
            "orientation":1
         },
         "camera":{
            "numberOfCameras":2
         }
      },
      "browser":{
         "agent":"Dalvik/2.1.0 (Linux; U; Android 9; AOSP on IA Emulator Build/PSR1.180720.117)"
      },
      "bluetooth":{
         "supported":false
      },
      "network":{
         "connected":true
      },
      "telephony":{
         "networkCountryIso":"us",
         "carrierName":"Android"
      }
   },
   "location":{
      "latitude":51.431534,
      "Longitude":-2.622353
   }
 }

Class to import: org.forgerock.openam.authentication.callbacks.DeviceProfileCallback

IdPCallback

Provides the information required by a client to authenticate with a social identity provider. Clients, such as an app using the ForgeRock SDK for Android or iOS, can use this information to authenticate to the social identity provider using native APIs and SDKs provided by the mobile OS.

The Social Provider Handler node returns this callback when its Client Type is set to NATIVE.

The response to this callback should be the result of authenticating with the social provider. For example, it might be an OAuth 2.0 or OpenID Connect access or ID token, depending on the provider.

Example

"callbacks": [
    {
        "type": "IdPCallback",
        "output": [
            {
                "name": "provider",
                "value": "amazon"
            },
            {
                "name": "clientId",
                "value": "amzn1.application-oa2-client.f0c11aa1f8504f8da26a346ccc55a39e"
            },
            {
                "name": "redirectUri",
                "value": "https://localhost:8443/openam"
            },
            {
                "name": "scopes",
                "value": [
                    "profile"
                ]
            },
            {
                "name": "nonce",
                "value": ""
            },
            {
                "name": "acrValues",
                "value": []
            },
            {
                "name": "request",
                "value": ""
            },
            {
                "name": "requestUri",
                "value": ""
            }
        ],
        "input": [
            {
                "name": "IDToken1token",
                "value": ""
            },
            {
                "name": "IDToken1token_type",
                "value": ""
            }
        ]
    }
]

Class to import: org.forgerock.openam.authentication.callbacks.IdPCallback

KbaCreateCallback

On a ForgeRock Identity Platform deployment, this callback collects knowledge-based authentication (KBA) answers to questions predefined in IDM, or lets users register both questions and answers.

Used to collect knowledge-based authentication (KBA) answers to predefined questions, or to let users register both questions and answers.

Example

{
  "callbacks": [
    {
      "type": "KbaCreateCallback",
      "output": [
        {
          "name": "prompt",
          "value": "Select a security question"
        },
        {
          "name": "predefinedQuestions",
          "value": [
            "What's your favorite color?"
          ]
        }
      ],
      "input": [
        {
          "name": "IDToken1question",
          "value": ""
        },
        {
          "name": "IDToken1answer",
          "value": ""
        }
      ]
    }
  ]
}

Input objects enumerate pairs of questions and answers. When IDToken_number_question is empty, the value returned in IDToken_number_answer is related to the predefined questions. In other words, the answer collected in IDToken1answer is related to the first predefined question, unless IDToken1question is collected in as well.

Class to import: org.forgerock.openam.authentication.callbacks.KbaCreateCallback

NameCallback

Used to retrieve a data string which can be entered by the user. Usually used for collecting user names.

Example

"callbacks":[
   {
      "type":"NameCallback",
      "output":[
         {
            "name":"prompt",
            "value":"User Name"
         }
      ],
      "input":[
         {
            "name":"IDToken1",
            "value":""
         }
      ]
   }
 ]

Class to import: javax.security.auth.callback.NameCallback

NumberAttributeInputCallback

On a ForgeRock Identity Platform deployment, this callback collects numerical-only attributes, such as size, or age.

Used to collect numerical-only attributes, such as size, or age.

It can be used with IDM policy information to validate the input against the managed user schema. For use examples, see the Attribute Collector node.

Callback output object reference

name. A string containing the name of the attribute in the user profile.
prompt. A string containing the description of the attribute. In other words, a description of the information required from the user.
required. A boolean indicating whether input is required for this attribute.
policies. One or more JSON objects describing validation policies that the provided input is required to pass. The object will be empty if validation is disabled in the Attribute Collector node.

The node collects policy information from IDM. For information about the policies available by default, see Default policy for managed objects in the IDM documentation.
failedPolicies. One or more JSON objects describing validation policies that the input failed. The object will only be populated after input has been submitted and validation failed.

Requires validation to be enabled in the Attribute Collector node.
validateOnly. A boolean indicating the state of this flag when previously submitted. If the UI returns this property as true in the input of the callback, the node will only perform input validation. The authentication journey will not continue to the next node.

This is useful for UIs to make validation checks as the user types instead of validating the input once and continuing the journey to the next node.

Requires validation to be enabled in the Attribute Collector node.
value. A string containing a default value for the attribute, if required.

Return the numeric value in the callback and the boolean that specifies whether validateOnly should be true.

Class to import: org.forgerock.openam.authentication.callbacks.NumberAttributeInputCallback

PasswordCallback

Used to retrieve a password value.

Example

"callbacks":[
   {
      "type":"PasswordCallback",
      "output":[
         {
            "name":"prompt",
            "value":"Password"
         }
      ],
      "input":[
         {
            "name":"IDToken1",
            "value":""
         }
      ]
   }
]

Class to import: javax.security.auth.callback.PasswordCallback

SelectIdPCallback

Offers a choice of social identity provider, or local authentication.

The Select Identity Provider node returns this callback when one or more social identity providers are enabled, or a single provider is enabled as well as the Local Authentication option, and therefore a choice from the user is required.

The response to this callback should be the name of the provider; for example amazon, or localAuthentication, if the user wants to authenticate without using a social provider.

Example

"callbacks": [
    {
        "type": "SelectIdPCallback",
        "output": [
            {
                "name": "providers",
                "value": [
                    {
                        "provider": "amazon",
                        "uiConfig": {
                            "buttonCustomStyle": "background: linear-gradient(to bottom, #f7e09f 15%,#f5c646 85%);color: black;border-color: #b48c24;",
                            "buttonImage": "",
                            "buttonClass": "fa-amazon",
                            "buttonDisplayName": "Amazon",
                            "buttonCustomStyleHover": "background: linear-gradient(to bottom, #f6c94e 15%,#f6c94e 85%);color: black;border-color: #b48c24;",
                            "iconClass": "fa-amazon",
                            "iconFontColor": "black",
                            "iconBackground": "#f0c14b"
                        }
                    },
                    {
                        "provider": "google",
                        "uiConfig": {
                            "buttonImage": "images/g-logo.png",
                            "buttonCustomStyle": "background-color: #fff; color: #757575; border-color: #ddd;",
                            "buttonClass": "",
                            "buttonCustomStyleHover": "color: #6d6d6d; background-color: #eee; border-color: #ccc;",
                            "buttonDisplayName": "Google",
                            "iconFontColor": "white",
                            "iconClass": "fa-google",
                            "iconBackground": "#4184f3"
                        }
                    },
                    {
                        "provider": "localAuthentication"
                    }
                ]
            },
            {
                "name": "value",
                "value": ""
            }
        ],
        "input": [
            {
                "name": "IDToken1",
                "value": ""
            }
        ]
    }
]

Class to import: org.forgerock.openam.authentication.callbacks.SelectIdPCallback

StringAttributeInputCallback

On a ForgeRock Identity Platform deployment, this callback collects string attributes, such as city names, telephone numbers, and postcodes.

Used to collect string attributes, such as city names, telephone numbers, and postcodes.

Differs from the TextInputCallback in that the StringAttributeInputCallback can be used to validate the input against the managed user schema policies. For use examples, see the Attribute Collector node.

Callback output object reference

name. A string containing the name of the attribute in the user profile.
prompt. A string containing the description of the attribute. In other words, a description of the information required from the user.
required. A boolean indicating whether input is required for this attribute.
policies. One or more JSON objects describing validation policies that the provided input is required to pass. The object will be empty if validation is disabled in the Attribute Collector node.

The node collects policy information from IDM. For information about the policies available by default, see Default policy for managed objects in the IDM documentation.
failedPolicies. One or more JSON objects describing validation policies that the input failed. The object will only be populated after input has been submitted and validation failed.

Requires validation to be enabled in the Attribute Collector node.
validateOnly. A boolean indicating the state of this flag when previously submitted. If the UI returns this property as true in the input of the callback, the node will only perform input validation. The authentication journey will not continue to the next node.

This is useful for UIs to make validation checks as the user types instead of validating the input once and continuing the journey to the next node.

Requires validation to be enabled in the Attribute Collector node.
value. A string containing a default value for the attribute, if required.

Example

{
  "callbacks": [
    {
      "type": "StringAttributeInputCallback",
      "output": [
        {
          "name": "name",
          "value": "givenName"
        },
        {
          "name": "prompt",
          "value": "First Name"
        },
        {
          "name": "required",
          "value": true
        },
        {
          "name": "policies",
          "value": {
            "policyRequirements": [
              "REQUIRED",
              "VALID_TYPE"
            ],
            "fallbackPolicies": null,
            "name": "givenName",
            "policies": [
              {
                "policyRequirements": [
                  "REQUIRED"
                ],
                "policyId": "required"
              },
              {
                "policyRequirements": [
                  "VALID_TYPE"
                ],
                "policyId": "valid-type",
                "params": {
                  "types": [
                    "string"
                  ]
                }
              }
            ],
            "conditionalPolicies": null
          }
        },
        {
          "name": "failedPolicies",
          "value": []
        },
        {
          "name": "validateOnly",
          "value": false
        },
        {
          "name": "value",
          "value": ""
        }
      ],
      "input": [
        {
          "name": "IDToken1",
          "value": ""
        },
        {
          "name": "IDToken1validateOnly",
          "value": false
        }
      ]
    }
  ]
}

The following example shows the value of the policy object when input validation is not required:

...
{
"name": "policies",
"value": {}
},
...

Return the string value in the callback and the boolean that specifies whether validateOnly should be true.

Class to import: org.forgerock.openam.authentication.callbacks.StringAttributeInputCallback

TermsAndConditionsCallback

On a ForgeRock Identity Platform deployment, this callback shows the company’s terms and conditions, and collects the user’s agreement to them.

Used to show the company’s terms and conditions, and to collect the user’s agreement to them.

Example

{
  "callbacks": [
    {
      "type": "TermsAndConditionsCallback",
      "output": [
        {
          "name": "version",
          "value": "0.0"
        },
        {
          "name": "terms",
          "value": "Terms and conditions text that customers must agree to."
        },
        {
          "name": "createDate",
          "value": "2019-10-28T04:20:11.320Z"
        }
      ],
      "input": [
        {
          "name": "IDToken1",
          "value": false
        }
      ]
    }
  ]
}

The input object for this callback is a boolean that specifies whether the user agrees to the terms and conditions.

Class to import: org.forgerock.openam.authentication.callbacks.TermsAndConditionsCallback

TextInputCallback

Used to retrieve text input from the end user.

Example

"callbacks":[
   {
      "type":"TextInputCallback",
      "output":[
         {
            "name":"prompt",
            "value":"Provide a nickname for this account"
         }
      ],
      "input":[
         {
            "name":"IDToken1",
            "value":""
         }
      ]
   }
]

Class to import: javax.security.auth.callback.TextInputCallback

ValidatedCreatePasswordCallback

On a ForgeRock Identity Platform deployment, this callback is used to collect a password value.

Used to collect a password value.

Differs from the PasswordCallback in that the ValidatedCreatePasswordCallback validates the input against the managed user schema policies. For use examples, see the Platform Password node.

Callback output object reference

name. A string containing the name of the attribute in the user profile.
policies. One or more JSON objects describing validation policies that the provided input is required to pass.

The node collects policy information from IDM. For more information about the policies available by default, see Default policy for managed objects.
failedPolicies. One or more JSON objects describing validation policies that the input failed. The object will only be populated after input has been submitted and validation failed.
validateOnly. A boolean indicating the state of this flag when previously submitted. If the UI returns this property as true in the input of the callback, the node will only perform input validation. The authentication journey will not continue to the next node.

This is useful for UIs to make validation checks as the user types instead of validating the input once and continuing the journey to the next node.
prompt. A string containing the description of the attribute. In other words, a description of the information required from the user.

Example

{
  "callbacks": [
    {
      "type": "ValidatedCreatePasswordCallback",
      "output": [
        {
          "name": "echoOn",
          "value": false
        },
        {
          "name": "policies",
          "value": {
            "policyRequirements": [
              "VALID_TYPE",
              "MIN_LENGTH",
              "AT_LEAST_X_CAPITAL_LETTERS",
              "AT_LEAST_X_NUMBERS",
              "CANNOT_CONTAIN_OTHERS"
            ],
            "fallbackPolicies": null,
            "name": "password",
            "policies": [
              {
                "policyRequirements": [
                  "VALID_TYPE"
                ],
                "policyId": "valid-type",
                "params": {
                  "types": [
                    "string"
                  ]
                }
              },
              {
                "policyId": "minimum-length",
                "params": {
                  "minLength": 8
                },
                "policyRequirements": [
                  "MIN_LENGTH"
                ]
              },
              {
                "policyId": "at-least-X-capitals",
                "params": {
                  "numCaps": 1
                },
                "policyRequirements": [
                  "AT_LEAST_X_CAPITAL_LETTERS"
                ]
              },
              {
                "policyId": "at-least-X-numbers",
                "params": {
                  "numNums": 1
                },
                "policyRequirements": [
                  "AT_LEAST_X_NUMBERS"
                ]
              },
              {
                "policyId": "cannot-contain-others",
                "params": {
                  "disallowedFields": [
                    "userName",
                    "givenName",
                    "sn"
                  ]
                },
                "policyRequirements": [
                  "CANNOT_CONTAIN_OTHERS"
                ]
              }
            ],
            "conditionalPolicies": null
          }
        },
        {
          "name": "failedPolicies",
          "value": []
        },
        {
          "name": "validateOnly",
          "value": false
        },
        {
          "name": "prompt",
          "value": "Password"
        }
      ],
      "input": [
        {
          "name": "IDToken1",
          "value": ""
        },
        {
          "name": "IDToken1validateOnly",
          "value": false
        }
      ]
    }
  ]
}

Return the password value in the callback and the boolean that specifies whether validateOnly should be true.

Class to import: org.forgerock.openam.authentication.callbacks.ValidatedCreatePasswordCallback

ValidatedCreateUsernameCallback

On a ForgeRock Identity Platform deployment, this callback is used to collect user name strings.

Used to collect user name strings.

Differs from the NameCallback in that the ValidatedCreateUsernameCallback validates the input against the managed user schema policies. For use examples, see the Platform Username node.

Callback output object reference

name. A string containing the name of the attribute in the user profile.
policies. One or more JSON objects describing validation policies that the provided input is required to pass.

The node collects policy information from IDM. For more information about the policies available by default, see Default policy for managed objects.
failedPolicies. One or more JSON objects describing validation policies that the input failed. The object will only be populated after input has been submitted and validation failed.
validateOnly. A boolean indicating the state of this flag when previously submitted. If the UI returns this property as true in the input of the callback, the node will only perform input validation. The authentication journey will not continue to the next node.

This is useful for UIs to make validation checks as the user types instead of validating the input once and continuing the journey to the next node.
prompt. A string containing the description of the attribute. In other words, a description of the information required from the user.

Example

{
  "callbacks": [
    {
      "type": "ValidatedCreateUsernameCallback",
      "output": [
        {
          "name": "policies",
          "value": {
            "policyRequirements": [
              "REQUIRED",
              "VALID_TYPE",
              "VALID_USERNAME",
              "CANNOT_CONTAIN_CHARACTERS",
              "MIN_LENGTH",
              "MAX_LENGTH"
            ],
            "fallbackPolicies": null,
            "name": "userName",
            "policies": [
              {
                "policyRequirements": [
                  "REQUIRED"
                ],
                "policyId": "required"
              },
              {
                "policyRequirements": [
                  "VALID_TYPE"
                ],
                "policyId": "valid-type",
                "params": {
                  "types": [
                    "string"
                  ]
                }
              },
              {
                "policyId": "valid-username",
                "policyRequirements": [
                  "VALID_USERNAME"
                ]
              },
              {
                "policyId": "cannot-contain-characters",
                "params": {
                  "forbiddenChars": [
                    "/"
                  ]
                },
                "policyRequirements": [
                  "CANNOT_CONTAIN_CHARACTERS"
                ]
              },
              {
                "policyId": "minimum-length",
                "params": {
                  "minLength": 1
                },
                "policyRequirements": [
                  "MIN_LENGTH"
                ]
              },
              {
                "policyId": "maximum-length",
                "params": {
                  "maxLength": 255
                },
                "policyRequirements": [
                  "MAX_LENGTH"
                ]
              }
            ],
            "conditionalPolicies": null
          }
        },
        {
          "name": "failedPolicies",
          "value": []
        },
        {
          "name": "validateOnly",
          "value": false
        },
        {
          "name": "prompt",
          "value": "Username"
        }
      ],
      "input": [
        {
          "name": "IDToken1",
          "value": ""
        },
        {
          "name": "IDToken1validateOnly",
          "value": false
        }
      ]
    }
  ]
}

Return the user name in the callback and the boolean that specifies whether validateOnly should be true.

Class to import: org.forgerock.openam.authentication.callbacks.ValidatedCreateUsernameCallback

Read-only Callbacks

AM uses the following callbacks to return information to the client or to show information to the user:

HiddenValueCallback

Used to return form values that are not visually rendered to the end user.

Example

"callbacks":[
   {
      "type":"HiddenValueCallback",
      "output":[
         {
            "name":"value",
            "value":"6186c911-b3be-4dbc-8192-bdf251392072"
         },
         {
            "name":"id",
            "value":"jwt"
         }
      ],
      "input":[
         {
            "name":"IDToken1",
            "value":"jwt"
         }
      ]
   }
]

Class to import: com.sun.identity.authentication.callbacks.HiddenValueCallback

MetadataCallback

Used to inject key-value meta data into the authentication process. For example:

Example

"callbacks":[
   {
      "type":"MetadataCallback",
      "output":[
         {
            "name":"data",
            "value":{
                  "myParameter": "MyValue"
            }
         }
      ]
   }
]

Class to import: com.sun.identity.authentication.spi.MetadataCallback

PollingWaitCallback

Tells the user the amount of time to wait before responding to the callback.

Example

"callbacks":[
   {
      "type":"PollingWaitCallback",
      "output":[
         {
            "name":"waitTime",
            "value":"8000"
         },
         {
            "name":"message",
            "value":"Waiting for response..."
         }
      ]
   }
]

Class to import: org.forgerock.openam.authentication.callbacks.PollingWaitCallback

RedirectCallback

Used to redirect the user’s browser or user-agent.

For example, the Social Provider Handler node returns this callback when its Client Type is set to BROWSER, and the client needs to redirect the user to a social identity provider for authentication.

Example

"callbacks":[
   {
      "type":"RedirectCallback",
      "output":[
         {
            "name":"redirectUrl",
            "value":"https://accounts.google.com/o/oauth2/v2/auth?nonce..."
         },
         {
            "name":"redirectMethod",
            "value":"GET"
         },
         {
            "name":"trackingCookie",
            "value":true
         }
      ]
   }
]

Class to import: com.sun.identity.authentication.spi.RedirectCallback

SuspendedTextOutputCallback

Used to display a message to the end user after their authentication tree is suspended.

Example

"callbacks":[
  {
     "type": "SuspendedTextOutputCallback",
     "output": [
       {
           "name": "message",
           "value": "An email has been sent to your inbox."
       },
       {
           "name": "messageType",
           "value": "0"
       }
     ]
  }
]

Class to import: org.forgerock.openam.auth.node.api.SuspendedTextOutputCallback

TextOutputCallback

Used to display a message to the end user.

Example

"callbacks":[
   {
      "type":"TextOutputCallback",
      "output":[
         {
            "name":"message",
            "value":"Default message"
         },
         {
            "name":"messageType",
            "value":"0"
         }
      ]
   }
]

Class to import: javax.security.auth.callback.TextOutputCallback

Backchannel Callbacks

AM uses backchannel callbacks when it needs to recover additional information from the user’s request. For example, when it requires a particular header or a certificate.

HttpCallback

Used to access user credentials sent in the Authorization header. For example:

Authorization: Basic bXlDbGllbnQ6Zm9yZ2Vyb2Nr

Class to import: com.sun.identity.authentication.spi.HttpCallback

LanguageCallback

Used to retrieve the locale for localizing text presented to the end user. The locale is sent in the request as a header.

Class to import: javax.security.auth.callback.LanguageCallback

ScriptTextOutputCallback

Used to insert a script into the page presented to the end user. The script can, for example, collect data about the user’s environment.

Class to import: com.sun.identity.authentication.callbacks.ScriptTextOutputCallback

X509CertificateCallback

Used to retrieve the content of an x.509 certificate, for example, from a header.

Class to import: com.sun.identity.authentication.spi.X509CertificateCallback

Authenticate endpoint parameters

To authenticate to AM using REST, make an HTTP POST request to the json/authenticate 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 list describes the json/authenticate endpoint supported parameters:

authIndexType

Specifies the type of authentication the user will perform. Always use in conjunction with the authIndexValue parameter to provide additional information about the way the user is authenticating.

If not specified, AM authenticates the user against the default authentication service configured for the realm.

The authIndexType parameter supports the following types:

composite_advice

Specifies that the value of the authIndexValue parameter is a URL-encoded composite advice string.

Use composite_advice when you want to give AM hints of which authentication services to use when logging in a user. For example, use an authentication service that provides an authentication level of 10 or higher:

$ curl -get \
--request POST \
--header "Content-Type: application/json" \
--header 'Accept-API-Version: resource=2.0, protocol=1.0' \
--data-urlencode 'authIndexType=composite_advice' \
--data-urlencode 'authIndexValue=<Advices>
    <AttributeValuePair>
        <Attribute name="AuthLevelConditionAdvice"/>
        <Value>10</Value>
    </AttributeValuePair>
</Advices>' \
'https://<tenant-name>.forgeblocks.com/am/json/realms/root/realms/alpha/authenticate'

Note that the previous curl command URL-encodes the XML values, and the -G parameter appends them as query string parameters to the URL.

Possible options for advices are:

TransactionConditionAdvice. Requires the unique ID of a transaction token. For example:

<Advices>
  <AttributeValuePair>
    <Attribute name="TransactionConditionAdvice"/>
    <Value>9dae2c80-fe7a-4a36-b57b-4fb1271b0687</Value>
  </AttributeValuePair>
</Advices>

For more information, see Transactional authorization.

AuthenticateToServiceConditionAdvice. Requires the name of an authentication tree. For example:

<Advices>
  <AttributeValuePair>
    <Attribute name="AuthenticateToServiceConditionAdvice"/>
    <Value>myExampleTree</Value>
  </AttributeValuePair>
</Advices>

AuthenticateToRealmConditionAdvice. Requires the name of a realm. For example:

<Advices>
  <AttributeValuePair>
    <Attribute name="AuthenticateToRealmConditionAdvice"/>
    <Value>myRealm</Value>
  </AttributeValuePair>
</Advices>

AuthLevelConditionAdvice. Requires an authentication level. For example:

<Advices>
  <AttributeValuePair>
    <Attribute name="AuthLevelConditionAdvice"/>
    <Value>10</Value>
  </AttributeValuePair>
</Advices>

AuthenticateToTreeConditionAdvice. Requires the name of an authentication tree. For example:

<Advices>
  <AttributeValuePair>
    <Attribute name="AuthenticateToTreeConditionAdvice"/>
    <Value>PersistentCookieTree</Value>
  </AttributeValuePair>
</Advices>

You can specify multiple advice conditions and combine them. For example:

<Advices>
  <AttributeValuePair>
    <Attribute name="AuthenticateToServiceConditionAdvice"/>
    <Value>ldapService</Value>
  </AttributeValuePair>
  <AttributeValuePair>
    <Attribute name="AuthenticateToServiceConditionAdvice"/>
    <Value>Example</Value>
  </AttributeValuePair>
  <AttributeValuePair>
    <Attribute name="AuthLevelConditionAdvice"/>
    <Value>10</Value>
  </AttributeValuePair>
</Advices>

level

Specifies that the value of the authIndexValue parameter is the minimum authentication level an authentication service must satisfy to log in the user.

For example, to log into AM using an authentication service that provides a minimum authentication level of 10, you could use the following:
```
$ curl \
--request POST \
--header 'Accept-API-Version: resource=2.0, protocol=1.0' \
'https://<tenant-name>.forgeblocks.com/am/json/realms/root/realms/alpha/authenticate?authIndexType=level&authIndexValue=10'
```
resource

Specifies that the value of the authIndexValue parameter is a URL protected by an AM policy.

For example, to log into AM using a policy matching the http://www.example.com resource, you could use the following:
```
$ curl \
--request POST \
--header 'Accept-API-Version: resource=2.0, protocol=1.0' \
'https://<tenant-name>.forgeblocks.com/am/json/realms/root/realms/alpha/authenticate?authIndexType=resource&authIndexValue=http%3A%2F%2Fwww.example.com'
```
Note that the resource must be URL-encoded. Authentication will fail if no policy matches the resource.
service

Specifies that the value of the authIndexValue parameter is the name of an authentication tree AM must use to log in the user.

For example, to log in to AM using the built-in login authentication tree, you could use the following:
```
$ curl \
--request POST \
--header 'Accept-API-Version: resource=2.0, protocol=1.0' \
'https://<tenant-name>.forgeblocks.com/am/json/realms/root/realms/alpha/authenticate?authIndexType=service&authIndexValue=login'
```
If authIndexType=service and no authIndexValue is specified, the default service is used. This is similar to no authIndexType being set.
user

Specifies that the value of the authIndexValue parameter is a valid user ID. AM will authenticate the user against the tree configured in the User Authentication Configuration field of that user’s profile.

For example, for the user demo to log into AM using the tree specified in their user profile, you could use the following:
```
$ curl \
--request POST \
--header 'Accept-API-Version: resource=2.0, protocol=1.0' \
'https://<tenant-name>.forgeblocks.com/am/json/realms/root/realms/alpha/authenticate?authIndexType=user&authIndexValue=demo'
```
Authentication will fail if the User Authentication Configuration field is empty for the user.

If several authentication services that satisfy the authentication requirements are available, AM presents them as a choice callback to the user. Return the required callbacks to AM to authenticate.

Required: No.

authIndexValue

Specifies the value of the authIndexType parameter.

Required: Yes, when using the authIndexType parameter.

noSession

When set to true, specifies that AM should not return a session when authenticating a user. For example:

$ curl \
--request POST \
--header "Content-Type: application/json" \
--header "Accept-API-Version: resource=2.0, protocol=1.0" \
--header "X-OpenAM-Username: demo" \
--header "X-OpenAM-Password: Ch4ng31t" \
'https://<tenant-name>.forgeblocks.com/am/json/realms/root/realms/alpha/authenticate?noSession=true'
{
    "message":"Authentication Successful",
    "successUrl":"/openam/console",
    "realm":"/"
}

Required: No.

Authentication nodes configuration reference

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

Even though they appear in the UI, the following nodes are incompatible with AM:

OAuth 2.0 Node

Social Facebook Node

Social Google Node

Social Ignore Profile Node

OpenID Connect Node

Provision IDM Account Node

Create Password Node

Password Collector Node

Username Collector Node

Authenticate Thing

Kerberos Node

Therefore, their reference information is not shown in this section.

Replace the Password Collector and the Username Collector nodes in the tree examples with the Platform Username and Platform Collector nodes.

Basic authentication nodes

Use the following nodes for basic authentication tasks, such as collecting usernames and passwords:

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.

Tree evaluation continues along the True path if the credentials are located in the configured data store. Otherwise, the tree evaluation continues along the False path.

Unlike the LDAP Decision node, which supports LDAP Behera Password Policies, the data store decision node does not have separate outcomes for accounts that are locked or their password has expired.

The Identity Store Decision node is an enhanced version of the Data Store Decision node, with additional outcomes. If your authentication journey needs more functionality than a simple True or False outcome, use the Identity Store Decision node instead.

Properties

This node has no configurable properties.

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.

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 user needs to change their password on first login, but cancels the password change form, tree evaluation continues along the Cancelled outcome path.

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

Properties

Property Usage

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.

Note that if you have specified multiple attribute values, you must also add those attributes to the Alias Search Attribute Name property when using account lockout. See User Profile for more information about this property.

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)

Identity Store Decision node

The Identity Store Decision node attempts to locate the provided username and password in the identity store. If the credentials exist, the node checks whether the profile is locked out, whether the provided password has expired, or whether the user cancels a password reset.

Tree evaluation progresses as follows:

Follows the True outcome path if the credentials are found.
- Follows the Locked outcome path if the profile associated with the provided credentials is locked.
- Follows the Expired outcome path if the profile is found, but the password has expired.
- Follows the Cancelled outcome path if the user needs to change their password on first login, but cancels the password change form.
Follows the False outcome path if the credentials are not found.

The Data Store Decision node is a simpler version of the Identity Store Decision node, with only two outcomes, True and False. If your authentication journey only needs these outcomes, use the Data Store Decision node instead.

Properties

Property Usage

Name

The name of the node in the authentication journey.

Default: Identity Store Decision

Minimum Password Length

Specifies the minimum acceptable password length.

Default: 8

The following image shows the Identity Store Decision node incorporated into an authentication journey.

The Identity Store Decision node in an authentication journey.

Multi-factor authentication nodes

Use the following nodes to configure trees with multi-factor authentication capabilities, such as web authentication and push authentication:

Get Authenticator App node

The Get Authenticator App node presents the user with links to obtain your authenticator app from the Apple App Store or the Google Play store.

Tree evaluation continues along the single outcome path when the user clicks the Continue button.

Properties

Property Usage

Get App Authenticator Message

Optional. Localized title for the node. The key is the language (such as en or fr), and the value is the message to display.

Continue Label

Optional. Localized text to use on the Continue button. The key is the language (such as en or fr), and the value is the message to display.

Apple App Store URL

Specifies the URL to download your authenticator app from the Apple App Store. The default value points to the ForgeRock Authenticator app for iOS.

Google Play URL

Specifies the URL to download your authenticator app from the Google Play Store. The default value points to the ForgeRock Authenticator app for Android.

HOTP Generator node

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

Passwords are stored in the oneTimePassword transient state property of the authentication tree.

Properties

Property

Usage

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

The HmacOneTimePassword authentication tree, showing HOTP Generator node usage.

Figure 9. HmacOneTimePassword Tree With HOTP Generator Node

MFA Registration Options node

The MFA Registration Options node lets the user register a multi-factor authentication device or skip the registration process.

The node requires the username of the identity to update; for example, by using a Platform Username node and also the type of MFA device; for example, by placing a Push Sender node earlier in the authentication journey.

Properties

Property Usage

Remove 'skip' option

Localized title for the node.

The key is the language (such as en or fr), and the value is the message to display.

Display Get Authenticator App

Localized text to use on the Continue button.

The key is the language (such as en or fr), and the value is the message to display.

Message

Localized text to use as the title of the screen.

The key is the language (such as en or fr), and the value is the message to display.

Localized text to use on the Register Device button.

The key is the language (such as en or fr), and the value is the message to display.

Get Authenticator App

Localized text to use on the Get Authenticator App button.

The key is the language (such as en or fr), and the value is the message to display.

Skip this Step

Localized text to use on the Skip this Step button.

The button, and the outcome, only appear if the Remove 'skip' option is not enabled.

The key is the language (such as en or fr), and the value is the message to display.

Opt-out

Localized text to use on the Opt-Out button. The button, and the outcome, only appear if the Remove 'skip' option is not enabled.

Note that the node itself does not affect the users' profile. Connect the Opt-out outcome to an Opt-out Multi-Factor Authentication node to actually persist the ability to skip MFA to the users' profile.

The key is the language (such as en or fr), and the value is the message to display.

Tree evaluation continues along whichever outcome the user selects when presented with the options.

Example

OATH Token Verifier node

The OATH Token Verifier node requests and verifies a one-time password (OTP) generated by a device such as a mobile phone. The default configuration is time-based OTP (TOTP), but the node also supports HMAC (HOTP).

The node requires that the user credentials are authenticated, and that the user has previously registered a device using the OATH Registration node. These two nodes work together to provide all the capabilities of a secure OATH authentication journey.

They can also be used in combination with other MFA nodes to extend these capabilities, for example:

You can use the OATH nodes in conjunction with the ForgeRock Authenticator app to register your phone, receive notifications, or generate one-time passwords.

For a visual overview of how the OATH nodes can be used within an authentication tree layout, see the Example.

Properties

Property Usage

OATH Algorithm

Specify the algorithm your device uses to generate the OTP:

HOTP: HOTP uses a counter value that is incremented every time a new OTP is generated.
TOTP: TOTP generates a new OTP every few seconds as specified by the TOTP Time Step Interval value.

The default value is TOTP. If this is changed to HOTP, you need to set the same value in the OATH Registration node.

HOTP Window Size

This property sets 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, the server will accept an OTP that is generated between counter 3 and 102.

TOTP Time Step Interval

The length of time that an OTP is valid, in seconds. For example, if the time step interval is 30 seconds, a new OTP will be generated every 30 seconds, and it will be valid for 30 seconds only.

The default value is 30.

TOTP Time Steps

This is the number of time step intervals that the OTP is permitted to be out of sync. This applies to codes that are generated before or after the current code. For example, with a time step of 1, the server will permit either the previous, the current, or the next code.

The default value is 2.

TOTP Hash Algorithm

The HMAC hash algorithm to be used to generate the OTP codes. ForgeRock Authenticator (OATH) supports SHA1, SHA256, and SHA512.

TOTP Maximum Allowed Clock Drift

Number of time steps a client is allowed to be out of sync with the server before a manual resynchronization is required.

For example, with 3 allowed drifts and a time step interval of 30 seconds, the server will allow codes from up to 90 seconds from the current time to be treated as the current time step. The drift for a user’s device is calculated each time they enter a new code. If the drift exceeds this value, the user’s authentication code will be rejected.

Allow recovery codes

Specify whether to allow users to use one of the recovery codes to proceed with the login.

Tree evaluation continues along one of the following outcome paths:

Not registered: If there is no registered device for the user.
Failure: If the user is not authenticated, or the collected token code cannot be verified.
Success: If there is a registered device and the token code is verified.

Example

OATH Registration node

The OATH Registration node lets the user register a device for OATH-based multi-factor authentication (MFA). Based on the node properties, the user device displays a QR code that includes all the details required for registration. If registration is successful, the node stores the device data, recovery codes (if enabled), and sets the skippable attribute to prevent repeat registration at next login.

The node requires the credentials of the user; for example, by using a sequence of the following nodes earlier in the authentication journey:

Connect the OATH Registration node’s Success outcome path to the OATH Token Verifier node to continue to OTP verification.

You can use the OATH nodes in conjunction with the ForgeRock Authenticator app to register your phone, receive notifications, or generate one-time passwords.

View the OATH Token Verifier node example to see how these nodes can be used in combination with other MFA nodes to create a complete OATH authentication journey.

Properties

Property Usage

Issuer

Specify an identifier to appear on the user’s device, such as a company name, a website, or an AM realm. The value is displayed by the authenticator app.

Account Name

Define the profile attribute to display as the username in the authenticator app.

If not specified, or if the specified profile attribute is empty, their username is used.

Background Color

The background color, in hex notation, to display behind the issuer’s logo within the authenticator app.

Logo Image URL

The location of an image to download and display as the issuer’s logo within the authenticator app.

Generate Recovery Codes

If enabled, recovery codes are generated and stored in the success outcome’s transient state.

Use the Recovery Code Display node to display the codes to the user for safekeeping.

One Time Password Length

The length of the generated OTP in digits. This value must be at least 6, and compatible with the hardware/software OTP generators you expect your end-users to use. For example, Google and ForgeRock authenticators support values of 6 and 8 respectively.

Minimum Secret Key Length

Number of hexadecimal characters allowed for the Secret Key.

OATH Algorithm

Specify the algorithm your device uses to generate the OTP:

HOTP: HOTP uses a counter value that is incremented every time a new OTP is generated.
TOTP: TOTP generates a new OTP every few seconds as specified by the TOTP Time Step Interval value.

The default value is TOTP. If this is changed to HOTP, you need to set the same value in the OATH Token Verifier node.

TOTP Time Step Interval

The length of time that an OTP is valid, in seconds. For example, if the time step interval is 30 seconds, a new OTP will be generated every 30 seconds, and it will be valid for 30 seconds only.

The default value is 30.

TOTP Hash Algorithm

The HMAC hash algorithm to be used to generate the OTP codes. AM supports SHA1, SHA256, and SHA512.

HOTP Checksum Digit

This adds a digit to the end of the OTP generated to be used as a checksum to verify the OTP was generated correctly. This is in addition to the actual password length. You should only set this if your device supports it.

HOTP Truncation Offset

This is an option used by the HOTP algorithm that not all devices support. This should be left as the default value of -1, unless you know your device uses an offset.

If registration is succesful and the device details are stored, tree evaluation continues along the Success outcome path. If AM encounters an issue during the registration process or the user fails to complete registration, evaluation proceeds along the Failure path.

Opt-out Multi-Factor Authentication node

The Opt-out Multi-Factor Authentication node sets the Skippable attribute in the user’s profile, which lets them skip MFA.

The node requires the username of the identity to update; for example, by using a Platform Username node and also the type of MFA device to set as "skippable." For example, by placing a Push Sender node node earlier in the authentication journey.

Tree evaluation continues along the single outcome path after setting the MFA device as "skippable" in the users' profile.

Properties

This node has no configurable properties.

OTP Collector Decision node

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

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

Property Usage

One Time Password Validity Length

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

Default: 5

OTP Email Sender node

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

Send mail requests will timeout after 10 seconds.

Properties

Property Usage

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

The subject of the email

Click Add to add a new email subject. Enter the locale (for example, en-uk) in the KEY field and the subject in the VALUE field. Repeat these steps for each locale that you support.

The content of the email

Click Add to add the content of the email. Enter the locale (for example, en-uk) in the KEY field and the email content in the VALUE field. Repeat these steps for each locale that you support.

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

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 kbd:[@] 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

Property Usage

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

Push Registration node

The Push Registration authentication node provides a way to register a device, such as a mobile phone, for multi-factor authentication using push notifications. For more information, see MFA: Push authentication.

If the user successfully registers their authenticator, then tree evaluation continues along the Success outcome path.

If the node does not receive a response from the users' device within the time specified in the node configuration, evaluation continues along the Time Out outcome path.

If AM encounters an issue when attempting to register using a device, tree evaluation continues along the Failure outcome path.

The node requires the username of the identity to update; for example, by using a Platform Username node.

You must also configure the Push Notification Service.

For information on provisioning the credentials required by the Push Notification Service, see How To Configure Service Credentials (Push Auth, Docker) in Backstage in the ForgeRock Knowledge Base.

For detailed information about the available properties, see Push Notification Service.

Properties

Property Usage

Issuer

Specify an identifier so that the user knows which service their account relates to. The value is displayed by the authenticator app:

The icons next to a registered account represent the authentication factors supported. The bell icon represents push notification support.

For example, Example Inc., or the name of your application.

Account Name

Specifies the profile attribute to display as the username in the authenticator app.

If not specified, or if the specified profile attribute is empty, their username is used.

Registration Response Timeout

Specify the number of seconds to wait for a response from the authenticator.

If the specified time is reached, tree evaluation continues along the Time Out outcome path.

Background Color

Specifies the background color, in hex notation, to display behind the issuer’s logo within the ForgeRock Authenticator app.

Logo Image URL

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

Generate recovery codes

Specify whether push-specific recovery codes should be generated. If enabled, recovery codes are generated and stored in transient state if registration was successful.

Use the Recovery Code Display node to display the codes to the user for safe keeping.

Generating recovery codes will overwrite all existing push-specific recovery codes.

Only the most recent set of recovery codes can be used for authentication if a device has been lost or stolen.

Example

Figure 10. Example Push Tree

The example tree above shows a possible implementation of a tree for handling push devices.

After verifying the users credentials against the configured data store, tree evaluation continues to the Push Sender node.

If the user does not yet have a registered device, the MFA Registration Options node displays the following options:

Register Device: The journey continues to the Push Registration node, which displays the QR code that should be scanned with a suitable authenticator app.
Get the App: The journey continues to the Get Authenticator App node, which displays the links needed to obtain a suitable app; for example, the ForgeRock Authenticator.
Skip this step: Displayed only if the node configuration lets the user skip. In this example tree, skipping is linked to the Success node.
Opt-out: Displayed only if the node configuration allows the user to skip or opt out. The journey continues to the Opt-out Multi-Factor Authentication node, which updates the users' profile to skip MFA with push in the future. In this example, after updating the profile the journey continues to the Success node.

Once the registration is complete the path returns to the Push Sender node, which starts the actual push notification stage of the journey.

A polling loop using the Polling Wait node in combination with the Push Result Verifier node continuously checks whether the user has successfully responded to the push notification.

An option displayed on the Polling Wait node lets the user exit that loop, and instead provide one of their push-specific recovery codes, letting them log in if they have lost their device, for example.

Note that in order for a user to manage their registered push devices, they must log in using either the device, or a recovery code. For more information, see Manage devices for MFA.

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.

If the push message contained any additional information, for example if it was a registration request, the values are stored in the nodeState object of the tree for the pushContent key.

Properties

This node has no configurable properties.

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

Push Notification Service.

For information on provisioning the credentials used by the service, see How To Configure Service Credentials (Push Auth, Docker) in Backstage 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

Authentication trees are not capable of registering a device to a profile.

If the user chooses to skip push authentication, tree evaluation continues along the Skipped outcome path.

Properties

Property Usage

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

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

Nodes in authentication journeys are not affected by the Two Factor Authentication Mandatory property, available at Realms > Realm Name > Authentication > Settings > General.

Example

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

If the user has a registered device:

A push notification is sent to their registered device.
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.
  
  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.

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:

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:

Present the user with information about registering their device.

You can use the MFA Registration Options node, which has several built-in options, or a Page node with, for example, a Choice Collector node.
The user registers the device with the Push Registration node. After registration, the tree displays the recovery codes to the user for safekeeping.

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

An Inner Tree Evaluator node may provide an alternative method of authentication. Otherwise, you may decide to allow the user to log in, as shown in the example.

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 viewing the recovery codes when registering a device, see Registering the ForgeRock Authenticator for Multi-Factor Authentication.

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 Platform Username node.

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

The Recovery Code Collector Decision node.

Properties

Property Usage

Recovery Code Type

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

Default: OATH

Recovery Code Display node

The Recovery Code Display node is used in conjunction with the WebAuthn Registration node or Push Registration node. It retrieves generated recovery codes from the transient state and presents them to the user, for safe-keeping. The codes can be used to authenticate if a registered device is lost or stolen.

Generated recovery codes are inserted into transient state when tree evaluation continues along the Success outcome path of the MFA nodes, when configured to generate recovery codes. Connect the Recovery Code Display node to the Success outcome path to display the codes.

If no recovery codes are available in transient state, tree evaluation continues along the only outcome path, and nothing is displayed to the user.

Generated recovery codes cannot be retrieved from the user’s profile - they are one-way encrypted. The Recovery Code Display node is the one and only opportunity to view the recovery codes, and keep them safe.

Properties

This node has no configurable properties.

Example

The following is an example of the output of the Recovery Code Display node:

Figure 11. Example output of the Recovery Code Display node

WebAuthn Authentication node

The WebAuthn Authentication node allows users of supported clients to use a registered FIDO device during authentication.

To determine whether the user has a registered device, the tree must have already acquired a username, for example by using a Platform Username node.

If the user’s client does not support web authentication, tree evaluation will continue along the Unsupported outcome path. For example, clients connected over the HTTP protocol rather than HTTPS do not support WebAuthn. (HTTPS may not be required when testing locally, on http://localhost, for example. For more information, see Is origin potentially trustworthy?.)

If the user does not have a registered device, tree evaluation continues along the No Device Registered outcome path.

If AM encounters an issue when attempting to authenticate using the device, tree evaluation continues along the Failure outcome path. For example, AM could not verify that the response from the authenticator was appropriate for the specific instance of the authentication ceremony.

If the user’s client encounters an issue when attempting to authenticate using the device, for example, if the timeout was reached, then tree evaluation continues along the Client Error outcome path. This outcome is used whenever the client throws a DOMException, as required by the Web Authentication: An API for accessing Public Key Credentials Level 1 specification.

If a client error occurs, the error type and description are added to a property named WebAuthenticationDOMException in the shared state. This property can be read by other nodes later in the tree, if required.

If the Allow recovery code property is enabled, AM provides the user the option to enter a recovery code rather than authenticate using a device. Tree evaluation continues along the Recovery Code outcome path if the users chooses to enter a recovery code. To accept and verify the recovery code, ensure the outcome path leads to a Recovery Code Collector Decision node.

If the user successfully authenticates with a device of the type determined by the User verification requirement property, tree evaluation continues along the Success outcome path.

Properties

Property Usage

Relying party identifier

Specifies the domain used as the relying party identifier during web authentication. If not specified, AM uses the domain name of the instance, for example openam.example.com.

Specify an alternative domain if your AM instances are behind a load balancer, for example.

Origin domains

Specifies a list of fully qualified URLs to accept as the origin of incoming requests.

If left empty, AM accepts any incoming domain.

User verification requirement

Specifies the required level of user verification.

The available options are:

REQUIRED: The authenticator used must verify the identity of the user, for example, by using biometrics. Authenticators that do not verify the identity of the user should not be activated for authentication.
PREFERRED: Use of an authenticator that verifies the identity of the user is preferred, but if none are available any authenticator is accepted.
DISCOURAGED: Use of an authenticator that verifies the identity of the user is not required. Authenticators that do not verify the identity of the user should be preferred.

Allow recovery codes

Specify whether to allow the user to enter one of their recovery codes instead of performing an authentication gesture.

Enabling this options adds a Recovery Code outcome path to the node. This outcome path should lead to a Recovery Code Collector Decision node in order to collect and verify the recovery code.

Timeout

Specify the number of seconds to wait for a response from an authenticator.

If the specified time is reached, tree evaluation continues along the Client error outcome path, and a relevant message is stored in the WebAuthenticationDOMException property of the shared state.

Username from device

Specifies whether AM requests that the device provides the username.

When enabled, if the device is unable to store or provide usernames, the node will fail and results in the Failure outcome.

For information on using this property for usernameless authentication with ForgeRock Go, see Configuring Usernameless Authentication with ForgeRock Go.

Return challenge as JavaScript

Specifies that the node returns its challenge as a fully encapsulated client-side JavaScript that interacts directly with the WebAuthn API, and auto-submits the response back.

If disabled, the node returns the challenge and associated data in a metadata callback. A custom UI, for example an application using the ForgeRock SDKs, uses the information from the callback to interact with the WebAuthn API on AM’s behalf.

Example

The example tree above shows one possible implementation of a tree for authenticating with WebAuthn devices.

After verifying the users credentials against the configured data store, tree evaluation continues to the WebAuthn Authentication node.

If the user’s client does not support WebAuthn, the tree fails and the user does not get a session. A more user-friendly approach would be to set a success URL to redirect the user to a page explaining the benefits of multi-factor authentication, and then proceeding to the Success node.

If there are no registered WebAuthn devices present in the user’s profile, the failure URL is set, pointing to a tree that allows the user to register a device. This stage could also be an Inner Tree Evaluator, with a registration tree inside.

If the user’s client does support WebAuthn, and the connection is secured with TLS, the user will be asked to complete an authorization gesture, for example scanning a fingerprint, or entering a PIN number:

The relying party details configured in the node are often included in the consent message to help the user verify the entity that is requesting access.

The authenticators the client activates for authentication depends in the value of the properties in the node. For example, if the User verification requirement property is set to REQUIRED, the client SHOULD only activate authenticators which verify the identity of the user. For extra protection, AM WILL verify that the response from an authenticator matches the criteria configured for the node, and will reject - by using the Failure outcome - an authentication attempt by an inappropriate authenticator type.

When the user completes an authorization gesture, for example scanning a fingerprint, or entering a PIN number, tree evaluation continues along the Success outcome path. In this example, their authentication level is increased by ten to signify the stronger authentication that has occurred, and the user is taken to their profile page.

If the user clicks the Use Recovery Code button, tree evaluation continues to the Recovery Code Collector Decision node, ready to accept the recovery code. If verified, the user is taken to their profile page.

Any problems encountered during the authentication (thorugh the Failure outcome), including a timeout (through the Client Error outcome), results in the overall failure of the authentication tree.

WebAuthn Device Storage node

The WebAuthn Device Storage node writes information about FIDO2 devices to a user’s profile, so that they can subsequently authenticate using the device.

Use this node to store the device data that the WebAuthn Registration node places into the tree’s transient state when its Store device data in transient state property is enabled.

If AM encounters an issue when attempting to save the device data to the user’s profile; for example, the user has not been identified earlier in the tree, then tree evaluation continues along the Failure outcome path.

If the node successfully stores the device data to the user’s profile, tree evaluation continues along the Success outcome path.

Properties

Property

Usage

Generate recovery codes

Specify whether WebAuthn device recovery codes should be generated. If enabled, recovery codes are generated and stored in the tree’s transient state, and stored alongside the device profile.

Use the Recovery Code Display node to display the codes to the user for safe keeping.

Generating recovery codes will overwrite all existing WebAuthn device recovery codes.

Only the most recent set of recovery codes can be used for authentication if a device has been lost or stolen.

WebAuthn Registration node

The WebAuthn Registration authentication node allows users of supported clients to register FIDO2 devices for use during authentication.

AM interacts with FIDO2/WebAuthn capable browsers, for example Chrome, Firefox and Microsoft Edge. These browsers interact with CTAP2 authenticators, including U2F and FIDO2 Security Keys, and platforms such as Windows Hello or MacOS TouchId.

If the user’s client does not support WebAuthn, tree evaluation will continue along the Unsupported outcome path. For example, clients connected over the HTTP protocol rather than HTTPS do not support WebAuthn.

If AM encounters an issue when attempting to register using a device, tree evaluation continues along the Failure outcome path. For example, AM could not verify that the response from the authenticator was appropriate for the specific instance of the authentication ceremony.

If the user’s client encounters an issue when attempting to register using a device, for example, if the timeout was reached, then tree evaluation continues along the Client Error outcome path. This outcome is used whenever the client throws a DOMException, as required by the Web Authentication: An API for accessing Public Key Credentials Level 1 specification.

If the user successfully registers an authenticator of the correct type as determined by the node’s properties, tree evaluation continues along the Success outcome path.

Properties

Property Usage

Relying party

Specify the name of the relying party entity that is registering and authenticating users by using WebAuthn.

For example, Example Inc..

Relying party identifier

Specifies the domain used as the relying party identifier during WebAuthn. If not specified, AM uses the domain name of the instance, for example openam.example.com.

Specify an alternative domain if your AM instances are behind a load balancer, for example.

Origin domains

Specifies a list of fully qualified URLs to accept as the origin of incoming requests.

If left empty, AM accepts any incoming domain.

User verification requirement

Specifies the required level of user verification.

The available options are:

REQUIRED: The authenticator used must verify the identity of the user, for example by using biometrics. Authenticators that do not verify the identity of the user should not be activated for registration.
PREFERRED: Use of an authenticator that verifies the identity of the user is preferred, but if none are available any authenticator is accepted.
DISCOURAGED: Use of an authenticator that verifies the identity of the user is not required. Authenticators that do not verify the identity of the user should be preferred.

Preferred mode of attestation

Specifies whether AM requires that the authenticator provides attestation statements.

The available options are:

NONE: AM does not require the authenticator to provide attestation statements. If the authenticator does send attestation statements, AM will not verify them, and will not fail the process.
INDIRECT: AM does not require the authenticator to provide attestation statements. If the authenticator does send attestation statements, AM will verify them, and will fail the process if they fail verification.
DIRECT: AM requires that the authenticator provides attestation statements, and will verify them. The process will fail if the attestation statements cannot be verified.

AM supports the following attestation formats:

You must set the Preferred mode of attestation property to NONE to use an authenticator that provides attestation statements in a format other than the supported formats above.

Specifically, AM does not currently support:

Accepted signing algorithms

Specify the algorithms that authenticators can use to sign their assertions.

Authentication attachment

Specifies whether AM requires that the authenticator is a particular attachment type.

There are two types of authenticator attachment:

An authenticator that is built-in to the client device is labelled a platform attachment.

A fingerprint scanner built-in to a phone or laptop is an example of a platform attachment authenticator.
An authenticator that can roam, or move, between different client devices is labelled a cross-platform attachment.

A USB hardware security key is an example of a cross-platform attachment authenticator.

The available options are:

UNSPECIFIED: AM accepts any attachment type.
PLATFORM: The authenticator must be a platform attachment type. The client should not activate other authenticator types for registration.
CROSS_PLATFORM: The authenticator must be a cross-platform attachment type. The client should not activate other authenticator types for registration.

Enforce revocation check

Specifies whether to enforce certificate revocation checks. When enabled, then any attestation certificate’s trust chain MUST have a CRL or OCSP entry that can be verified by AM during processing.

When disabled, certificates are not checked for revocation. You must ensure expired or revoked certificates are manually removed.

Timeout

Specify the number of seconds to wait for a response from an authenticator.

Limit registrations

Specify whether the same authenticator can be registered multiple times.

If enabled, the client should not activate an authenticator that is already registered for registration.

Generate recovery codes

Specify whether WebAuthn-specific recovery codes should be generated. If enabled, recovery codes are generated and stored in transient state if registration was successful.

Use the Recovery Code Display node to display the codes to the user for safe-keeping.

If you have enabled the Store device data in transient state and there are not saving the device data to the user’s profile immediately, do not enable this property. Enable the Generate recovery codes property in the WebAuthn Device Storage node instead.

Generating recovery codes will overwrite all existing WebAuthn-specific recovery codes.

Only the most recent set of recovery codes can be used for authentication if a device has been lost or stolen.

Store data in transient state

Specify whether the information provided by the device to the node will be stored in the tree’s transient state for later analysis by subsequent nodes, using the key webauthnData.

In addition to the information provided by the device, the type of attestation achieved; for example, BASIC, CA, SELF and so on, will be stored in the tree’s transient data, using the key webauthnAttestationType.

The amount of data involved can be large. Only enable this option if you intend to analyze it.

Store device data in transient state

Specify whether the information about the device required for WebAuthn is stored in the tree’s transient state rather than saved immediately to the user’s profile.

Enable this option if you intend to make decisions in scripts, and have enabled the Store data in transient state property, and therefore do not want to register the device to the user until the outcome of the analysis is complete.

Do not alter the data whilst it is in the tree’s transient state, nor when saved to a user’s profile.

Modifying the device data will likely cause the device to be unable to authenticate.

Use the WebAuthn Device Storage node to write the device data to the user’s profile when this option is enabled.

When disabled, device data is written automatically to the user’s profile when registration is successful.

Username to device

Specifies whether AM requests that the device stores the user’s username.

When enabled, if the device is unable to store or provide usernames, the node will fail and results in the Failure outcome.

For information on using this property for usernameless authentication with ForgeRock Go, see Configuring Usernameless Authentication with ForgeRock Go.

Shared state attribute for display name

Specifies a variable in tree’s shared state that contains a display name for the user; for example, their full name, or email address.

The value is written to devices alongside the username when the Username to device property is enabled, and helps the user select between the accounts they may have on their devices.

If not specified, or the variable is not found in shared state, the user name is used.

For information on using this property for usernameless authentication with ForgeRock Go, see Configuring Usernameless Authentication with ForgeRock Go.

Return challenge as JavaScript

Specifies that the node returns its challenge as a fully encapsulated client-side JavaScript that interacts directly with the WebAuthn API, and auto-submits the response back.

If disabled, the node returns the challenge and associated data in a metadata callback. A custom UI; for example, an application using the ForgeRock SDKs, uses the information from the callback to interact with the WebAuthn API on AM’s behalf.

Example

The example tree above shows a possible implementation of a tree for registering WebAuthn devices.

After verifying the users credentials against the configured data store, tree evaluation continues to the WebAuthn Registration node.

If the user’s client does not support WebAuthn, the failure URL is altered, for example to redirect the user to a page explaining which clients and operating systems support WebAuthn.

If the user’s client does support WebAuthn, and the connection is secured with TLS, the user will be asked to register an authenticator:

The user’s browser may present a consent pop-up to allow access to the authenticators available on the client. When consent has been granted the browser activates the relevant authenticators, ready for registration.

The relying party details configured in the node are often included in the consent message to help the user verify the entity that is requesting access.

The authenticators the client activates for registration depends in the value of the properties in the node. For example, if the User verification requirement property is set to REQUIRED, the client would not activate a USB hardware security key for registration.

When the user completes an authorization gesture, for example scanning a fingerprint, or entering a PIN number, tree evaluation continues along the Success outcome path, and in this example will be taken to their profile page.

The registered authenticator appears on the user’s dashboard page, with the label New Security Key. To rename the authenticator, click its vertical ellipsis context icon, , and then click Rename.

Any problems encountered during the registration, including a timeout, results in tree evaluation continuing to the Failure outcome.

Risk Management Authentication Nodes

Use the following nodes to examine the perceived risk associated to the authentication and act on it:

Account Active Decision node

Checks if the account the user has entered is activated. This node relies on the tree’s shared state to determine which account to check. Use this node to validate whether an account is currently activated, such as in login flows where an account may already be created, but not enabled until a later date.

For more information, see Account lockout for trees.

Properties

This node has no configurable properties.

Account Lockout node

The Account Lockout node can lock or unlock the authenticating user’s account profile.

For more information, see About Account Lockout for Trees.

Properties

Property Usage

Lock Action

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

The Data Store Decision authentication node checks if the account profile is in the LOCK state. For more information, see Data Store Decision node.

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 12. RetryLimit Tree With Account Lockout Decision node

Auth Level Decision node

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

Properties

Property Usage

Sufficient Authentication Level

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.

Modify Auth Level node

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

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

Properties

Property

Usage

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.

CAPTCHA node

The CAPTCHA node implements Google’s reCAPTCHA v2 and reCAPTCHA v3 widgets and hCaptcha’s v1 widget, to add CAPTCHA support to authentication trees.

This node verifies the response token received from Google or hCaptcha and creates a CAPTCHA callback for the UI to interact with. The node has two outcomes—success and failure.

By default, the node is configured for Google’s reCAPTCHA v2.

Properties

Property Usage

CAPTCHA Site Key (required)

The CAPTCHA site key, provided by Google or hCaptcha when you sign up for access to the API.

CAPTCHA Secret Key (required)

The CAPTCHA secret key, provided by Google or hCaptcha when you sign up for access to the API.

CAPTCHA Verification URL (required)

The URL used to verify the CAPTCHA submission. Possible values are:

Google: https://www.google.com/recaptcha/api/siteverify
hCaptcha: https://hcaptcha.com/siteverify

CAPTCHA API URL (required)

The URL of the JavaScript that loads the CAPTCHA widget. Possible values are:

Google: https://www.google.com/recaptcha/api.js
hCaptcha: https://hcaptcha.com/1/api.js

Class of CAPTCHA HTML Element

The class of the HTML element required by the CAPTCHA widget. Possible values are:

Google: g-recaptcha
hCaptcha: h-captcha

ReCaptcha V3 node

If you’re using Google reCaptcha, specifies whether it’s v2 or v3. Turn on for v3.

Score Threshold

If you’re using Google reCAPTCHA v3, or hCaptcha, enter a Score Threshold. reCAPTCHA v3 and hCaptcha return a score for each user request, based on observed interaction with your site. Both facilities "learn" by observing real site traffic, so scores in a staging environment or in a production deployment that has just been implemented might not be very accurate. A score of 1.0 is likely a good user interaction, while 0.0 is likely to be a bot. The threshold you set here determines whether to allow or deny access, based on the score returned by Google or hCaptcha. You can generally start with a threshold of 0.5. For more information about score thresholds, see the Google documentation.

Example

Figure 13. Example Tree With CAPTCHA node

Test the CAPTCHA node

ForgeRock provides a Postman collection to configure AM to test the CAPTCHA node. The Postman collection contains the queries to demonstrate the CAPTCHA node with reCAPTCHA V2, V3 and with hCaptcha. Before you start, set up a reCAPTCHA V2 and V3 site, and an hCaptcha site, and copy their site and secret keys.

Download and install Postman.
Download the ForgeRock CAPTCHA Collection.
Import the collection into Postman:
- Select File > Import … > Upload Files.
- Select the CAPTCHA collection, and click Open, then click Import.
Change the collection variables to suit your environment:
- On the Collections tab, select the ForgeRock CAPTCHA Collection.
- Click on the Variables tab, and set the value of at least the following variables:
  - URL_base
  - admin_password
  - demo_username
  - demo_password
- Click Update to save your changes.
  
  You are ready to run the collection.
When the authentication trees have been created visit the following URLs in your browser to demonstrate the login flow for each CAPTCHA type:
- URL_base/XUI/?realm=sub_realm&service=recaptchav3
- URL_base/XUI/?realm=sub_realm&service=recaptchav2
- URL_base/XUI/?realm=sub_realm&service=hcaptcha

Use the demo_username and demo_password to log in.

Behavioral Authentication Nodes

Use the following nodes to adjust the behavior of authentication trees:

Increments the successful login count property of a managed object in IDM.

Use this node in conjunction with the Login Count Decision node. If you plan to track the number of logins, include this node in your login authentication flow, but you can safely omit it if you are not planning to use that functionality.

Properties

Property

Usage

Identity Attribute

The attribute used to identify the object in IDM.

Triggers an action when a user’s successful login count property reaches a specified number.

The action can either be triggered once, by setting the interval property to happen AT the set amount of successful login attempts; or set to occur EVERY time the specified number of additional successful login attempts occur.

Use this node in conjunction with the Increment Login Count node. The Increment Login Count node needs to be present in your login authentication flow for the Login Count Decision node to have the data necessary to trigger a decision.

Properties

Property Usage

Interval

The type of interval the decision should trigger on. Valid types are every and at. Every refers to a recurring action that happens every specified number of successful logins, such as prompting a user to update their contact information every 30 days. At refers to an action that occurs once, after the specified number of successful logins. For example, prompting the user to set their communication preferences once they have logged in 10 times.

Amount

The amount (count) of logins the interval should trigger on.

Identity Attribute

The attribute used to identify the object in IDM.

Contextual Authentication Nodes

Use the following nodes to examine the authentication context and act on it:

Certificate Collector node

This node collects an X.509 digital certificate from the request coming from the authenticating user so that AM can use it as the user’s credentials.

The tree continues through the Collected path if AM collects the digital certificate, and through the Not Collected path, otherwise.

To validate the certificate, add a Certificate Validation node to the tree.

The Certificate Collector authentication node.

Properties

Property Usage

Certificate Collection Method

Specifies how AM should collect the certificate from the request. Possible values are:

Request. AM looks for the certificate in the request. Use this value if TLS termination happens at the container where AM runs.
Header. AM looks for the certificate in the HTTP header name specified in the HTTP Header Name for the Client Certificate property. Use this value if TLS termination happens in a proxy or load balancer placed in front of the container where AM runs.
Either. AM looks for the certificate in the request; if it cannot find it, AM looks for the certificate in the HTTP header specified in the HTTP Header Name for the Client Certificate property.

Default: Either

HTTP Header Name for the Client Certificate

Specifies the name of the HTTP header containing the certificate when the Certificate Collection Method property is configured to Header or Either.

Default: No value specified.

Trusted Remote Hosts

Specifies a list of IP addresses trusted to supply certificates on behalf of the authenticating client, such as load balancers doing SSL termination.

If no value is specified, AM will reject certificates supplied by remote hosts. If you specify the any value, AM will trust certificates on behalf of the authenticating client supplied by any remote host.

Default: No value specified.

Certificate Validation node

This node validates a digital X.509 certificate collected by the Certificate Collector node.

The node has different outcomes, some of which are used depending on the configuration of the node:

True: The node could validate the certificate.
False: The node could not validate the certificate. The node will use this path when it cannot validate the certificate, but the cause is not managed by any of the other outcomes.
Not found: The Match Certificate in LDAP property is enabled, but the certificate was not found in the LDAP store.
Expired: The Check Certificate Expiration property is enabled, and the certificate has expired.
Path Validation Failed: The Match Certificate to CRL property is enabled, and the certificate path is invalid.
Revoked: The OCSP Validation property is enabled, and the certificate has been revoked.

When the outcome is True, append a Certificate User Extractor node to extract the values of the certificate and return them to AM.

The Certificate Validation authentication node.

Properties

Property Usage

Match Certificate in LDAP

When enabled, AM matches the certificate collected with the one stored in an LDAP directory entry. This entry, and additional security-related properties, are defined later in the node.

Default: Disabled

Check Certificate Expiration

When enabled, AM checks whether the certificate has expired.

Default: Disabled

Subject DN Attribute Used to Search LDAP for Certificates

Specifies the attribute that AM will use to search the LDAP directory for the certificate. The search filter will also use the value of the Subject DN as it appears in the certificate.

Default: CN

Match Certificate to CRL

When enabled, AM checks whether the certificate has been revoked according to a CRL in the LDAP directory. Related properties are defined later in the node.

Default: Disabled.

Issuer DN Attribute(s) Used to Search LDAP for CRLs

Specifies which attribute and value in the certificate Issuer DN AM will use to find the CRL in the LDAP directory.

If only one attribute is specified, the LDAP search filter used 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).

Specify several CLRs for the same CA issuer in a comma-separated list (kbd:[,]) where the names are in the same order as they occur in the subject DN.

In this case, the LDAP search filter used is (cn=attr1=attr1-value-in-subject-DN,attr2=attr2-value-in-subject-DN,…, and so on.

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

Default: CN

HTTP Parameters for CRL Update

Specifies parameters that AM will include in any HTTP CRL call to the CA that issued the certificate.

If the client or CA contains the Issuing Distribution Point Extension, AM uses this information to retrieve the CRL from the distribution point.

Add the parameters as key pairs of values in a comma-separated list (kbd:[,]). For example, param1=value1,param2=value2.

Cache CRLs in Memory

(LDAP distribution points only) When enabled, AM caches CRLs.

Default: Enabled

Update CA CRLs from CRLDistributionPoint

When enabled, AM updates the CRLs stored in the LDAP directory store if the CA certificate includes either the IssuingDistributionPoint or the CRLDistributionPoint extensions.

Default: Enabled

OCSP Validation

When enabled, AM checks the revocation status of certificates using the Online Certificate Status Protocol (OCSP).

The AM instance must have internet access, and you must configure OSCP for AM by going to Configure > Server Defaults > Security > Online Certificate Status Protocol Check.

Default: Disabled

LDAP Server Where Certificates are Stored

Specifies the LDAP server that holds the certificates. Enter each server in the ldap-server:port format.

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.

To configure a secure connection, enable the Use SSL/TLS for LDAP Access property.

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 am_server|base_dn. For example, openam.example.com|dc=example,dc=com openam1.test.com|dc=test,dc=com.

LDAP Server Authentication User

Specifies the DN of the service account that AM will use to authenticate to the LDAP that holds the certificates. For example, cn=LDAP User.

Default: cn=Directory Manager

LDAP Server Authentication Password

Specifies the password of the user configured in the LDAP Server Authentication User property.

Use SSL/TLS for LDAP Access

Specifies whether AM should use SSL/TLS to access the LDAP. When enabled, AM must be able to trust the LDAP server certificate.

Default: Disabled

Example

The following is an example of how to use the certificate nodes. Note that all the failure outcomes of the Certificate Validation node are linked so that the user provides a username and password, but you could choose different authentication methods for each outcome.

Figure 14. Certificate Validation Example

Certificate User Extractor node

This node extracts a value from the certificate collected by the Certificate Collector node, and searches for it in the identity store. The goal is to match the certificate with a user in the identity store.

The tree continues through the Extracted path if AM was able to match the certificate to a user in the identity store, and through the Not Extracted path otherwise.

The extracted value is stored in the username key in the shared state of the authentication tree.

The Certificate User Extractor authentication node.

Properties

Property Usage

Certificate Field Used to Access User Profile

Specifies the field in the certificate that AM will use to search for the user in the identity store. Possible values are:

Subject DN
Subject CN
Subject UID
Email Address
Other
None

If you select Other, provide an attribute name in the Other Certificate Field Used to Access User Profile property.

Select None if you want to specify an alternate way of looking up the user profile in the SubjectAltNameExt Value Type to Access User Profile property.

Default: Subject CN

Other Certificate Field Used to Access User Profile

Specifies a custom certificate field to use as the base of the user search.

SubjectAltNameExt Value Type to Access User Profile

Specifies how to look up the user profile. Possible values are:

None. AM uses the value specified in the Certificate Field Used to Access User Profile or the Other Certificate Field Used to Access User Profile properties when looking up the user profile.
RFC822Name. AM looks up for the user profile using the value of the RFC822Name field.
UPN. AM looks up the user profile as the User Principal Name attribute used in Active Directory.

Default: None

Configuration Provider Node

The Configuration Provider node creates a dynamic node configuration, based on the current node state. The node references a script that lets you build up a configuration map object with custom values, and provides this configuration map to the specified node type.

The node has all the outcomes of the specified node and an additional outcome, Configuration failure. Use the Configuration failure outcome to specify what should happen in the tree if the node is unable to build the configuration map, the configuration map is missing required values, or the configuration map is invalid.

Before you use the Configuration Provider node, create a script, of type Config Provider, that provides the functionality for the node. The map that you build in the script must be named config, and must be populated with the required configuration.

This example creates a configuration map that pulls in the user’s username from the node state to display a custom message, requesting the user to confirm that they are over 18:

config = {
    "message": {"en-GB": "Hi " + nodeState.get("username") + ". Please confirm that you are over 18."},
    "messageYes": {"en-GB": "Confirm"},
    "messageNo": {"en-GB": "Deny"},
};

See the sample script for a reference to the bindings available to this script.

Example

Figure 15. Example Tree With Configuration Provider Node (ForgeRock Identity Platform)

Referencing the script shown in the previous example, the configuration of this node would look something like this:

The configuration of a configuration provider node.

Properties

Property

Usage

Script

Select the Config Provider type script that you created for this node.

Node Type

Select the type of node for which you are generating a configuration.

The Configuration Provider node cannot provide configuration for all node types. The node type must have a fixed set of outcomes that cannot be changed by the node’s configuration.

The Cookie Presence Decision authentication node checks if a named cookie is present in the incoming authentication request.

Note that the node does not check the value of the named cookie, only that it exists.

Properties

Property Usage

Name of Cookie

Tree evaluation continues along the True path if the named cookie is present in the incoming authentication request. Otherwise, the tree evaluation continues along the False path.

Device Profile Collector node

The Device Profile Collector authentication node gathers metadata about the device the user is authenticating with.

The node sends a DeviceProfileCallback callback. For more information, see Interactive Callbacks.

When used with the ForgeRock SDKs, the node can collect the following:

Device Metadata: Information such as the platform, versions, device name, hardware information, and the brand of the device being used.

The captured data is in JSON format, and stored in the authentication tree’s shared state, in a variable named forgeRock.device.metadata.
Device Location: Provides the last known latitude and longitude of the device’s location.

The captured data is in JSON format, and stored in the authentication tree’s shared state, in a variable named forgeRock.device.location.

The collection of geographical information requires end user approval. This process is driven by a browser function. End users see a pop up asking if sharing geographical location can be permitted. Note that this function is not honored by the browser if the connection is not secure.

It is up to you what information you collect from users and devices.

You should always use data responsibly and provide your users appropriate control over data they share with you.

You are responsible for complying with any regulations or data protection laws.

In addition to the collected metadata, an identifier string in the JSON uniquely identifies the device.

Use this node with the Device Profile Save node when you want to create a trusted profile from the collected data. The trusted device profile can be used in subsequent authentication attempts; for example, with the Device Match and Device Profile Location Match node.

Properties

Property Usage

Maximum Profile Size (KB)

Specifies the maximum accepted size, in kilobytes, of a device profile.

If the collected profile data exceeds this size, authentication fails.

Collect Device Metadata

Specifies whether device metadata is requested.

Collect Device Location

Specifies whether device location is requested.

Message

Specifies an optional message to display to the user while the node collects the requested data.

Messages provided in the node override the defaults provided by AM.

Device Match node

The Device Match authentication node compares any collected device metadata with that stored in the user’s profile.

Use this node alongside the Device Profile Collector node to determine if the authenticating user is on a previously saved, trusted device.

You can choose between two methods of comparison:

Built-in Matching

The node handles the comparison and matching, and you can configure the acceptable variance, and specify a time frame that profiles are considered current.
Custom Matching

Create scripts to do the comparison of captured device data against trusted device profiles.

AM includes a template script that you can customize to your requirements. In the AM admin UI, go to Realms > Realm Name > Scripts, and then click Device Match Template - Decision Node Script.

ForgeRock also provides a more complete sample script, as well as instructions for its use, and a development toolkit. Find these resources on GitHub, at: https://github.com/ForgeRock/forgerock-device-match-script.

You must establish the identity of the user in the tree before attempting to match device profiles.

Tree evaluation continues along the True path if the collected device profile matches a saved profile, within the configured variance; otherwise, tree evaluation continues along the False path.

If the user has no trusted device profiles, or the identity of the user has not been established, tree evaluation continues along the Unknown Device path.

Properties

Property

Usage

Acceptable Variance

Specify the maximum amount of device attribute differences that is still acceptable for a match.

Expiration

Specify the maximum age, in the number of days since being saved, that existing profiles can be considered for comparison. Device profiles that were saved to the user’s profile before this time will not be compared to the collected metadata.

Use Custom Matching Script

Specifies whether to use a custom script to compare the collected metadata with saved device profiles. The script type has to be Decision node script for authentication trees.

When a custom matching script is used, the Acceptable Variance and Expiration properties are ignored.

Custom Matching Script

Specifies the custom script to use if the Use Custom Matching Script property is enabled.

Only scripts of type Decision node script for authentication trees appear in the list.

Device Profile Save node

The Device Profile Save authentication node persists collected device data to a user’s profile in the identity store.

Use this node alongside the Device Profile Collector node when you want to reuse the collected data in future authentications; for example, with the Device Match and Device Profile Location Match node.

You must establish the identity of the user in the tree before attempting to save to their profile.

A user profile can contain multiple device profiles. Use the Maximum Saved Profiles property to configure the maximum number of device profiles to persist per user. Saving a device profile with the same identifier as an existing entry overwrites the original record, and does not increment the device profile count.

The user UI component of the platform UI displays saved device profiles to end users. Note that the Access Management UI does not display saved device profiles to end users.

You can manage device profiles with REST, by using the /json/users/user/devices/profile endpoint.

Use the AM API Explorer for detailed information about the parameters supported by the /devices/profile endpoint, and to test it against your deployed AM instance.

In the AM admin UI, select the Help icon, and then go to API Explorer > /users > /{user} > /devices > /profile.

Properties

Property

Usage

Device Name Variable

Specifies the name of a variable in the authentication tree’s shared state that contains an alias label for the device profile.

Maximum Saved Profiles

Specify the maximum number of device profiles to save in a user’s profile.

When the maximum is reached, saving a new device profile replaces the oldest record.

Save Device Metadata

Specifies whether device metadata is saved to the user’s profile.

Save Device Location

Specifies whether device location metadata is saved to the user’s profile.

Device Profile Location Match node

The Device Profile Location Match authentication node compares any collected device location metadata with that stored in the user’s profile.

Use this node alongside the Device Profile Collector node to determine if the authenticating user’s device is located within range of somewhere they have authenticated from, and saved, previously.

You must establish the identity of the user in the tree before attempting to match locations.

Tree evaluation continues along the True path if the collected location is within the specified range of saved location data; otherwise, tree evaluation continues along the False path.

If the user has no saved device profiles, or the identity of the user has not been established, tree evaluation continues along the Unknown Device path.

Properties

Property

Usage

Maximum Radius (km)

Specifies the maximum distance, in kilometers, that a device can be from a previously saved location.

The distance is calculated point-to-point.

Device Geofencing node

The Device Geofencing authentication node compares any collected device location metadata with the trusted locations configured in the authentication node.

Use this node alongside the Device Profile Collector node to determine if the authenticating user’s device is located within range of configured, trusted locations.

Tree evaluation continues along the Inside path if the collected location is within the specified range of a configured trusted location; otherwise, tree evaluation continues along the Outside path.

Properties

Property Usage

Trusted Locations

Specify the latitude and longitude of at least one trusted location. Separate the values with a comma; for example, 37.7910855,-122.3951663.

Geofence Radius (km)

Specifies the maximum distance, in kilometers, that a device can be from a configured trusted location.

The distance is calculated point-to-point.

Device Tampering Verification node

The Device Tampering Verification authentication node specifies a threshold for deciding if the device has been tampered with; for example, if it has been rooted or jailbroken.

A score between zero and one is returned by the device, based on the likelihood that is has been tampered with or may pose a security risk. For example, an emulator scores the maximum of 1.

Use this node alongside the Device Profile Collector node to retrieve the tampering score from the device.

Tree evaluation continues along the Not Tampered path if the device scores less than or equal to the configured threshold, otherwise tree evaluation continues along the Tampered path.

Properties

Property Usage

Score Threshold

Specifies the score threshold for determining if a device has been tampered with. Enter a decimal fraction, between 0 and 1; for example, 0.75.

The higher the score returned from the device, the more likely the device is jailbroken, rooted, or is a potential security risk.

Emulators score the maximum; 1.

The Persistent Cookie Decision authentication node checks for the existence of the persistent cookie specified in the Persistent cookie name property, the default being session-jwt.

If the cookie is present, the node verifies the signature of the JWT stored in the cookie by using the signing key specified in the HMAC signing key property.

If the signature is valid, the node will decrypt the payload of the JWT by using the key pair specified in the Persistent Cookie Encryption Certificate Alias property. This property can be found at the global level by navigating to Configure > Authentication > Core Attributes > Security, or at the realm level by navigating to Realms > Realm Name > Authentication > Settings > Security.

Within the decrypted JSON payload is information such as the UID of the identity, and the client IP address. Enable the Enforce client IP property to verify that the current IP address and the client IP address in the cookie are identical.

The Persistent Cookie Decision authentication node recreates the received persistent cookie, updating the value for the idle time property. Therefore, cookie creation properties as used by the Set Persistent Cookie node are also available in the Persistent Cookie Decision authentication node.

Tree evaluation continues along the True outcome path if the persistent cookie is present and all the verification checks above are satisfied. Otherwise, tree evaluation continues along the False outcome path.

Properties

Property Usage

Idle Timeout

Specifies the maximum amount of idle time allowed before the persistent cookie is invalidated, in hours. If no requests are received and the time is exceeded, the cookie is no longer valid.

Enforce Client IP

When enabled, ensures that the persistent cookie is only used from the same client IP to which the cookie was issued.

Use secure cookie

When enabled, adds the Secure flag to the persistent cookie.

If the Secure flag is included, the cookie can only be transferred over HTTPS. When a request is made over HTTP, the cookie is not made available to the application.

Use HTTP only cookie

When enabled, adds the HttpOnly flag to the persistent cookie.

When the HttpOnly flag is included, that cookie will not be accessible through JavaScript. According to RFC 6265, the HttpOnly 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)."

HMAC Signing Key

Specifies a key to use for HMAC signing of the persistent cookie. Values must be base64-encoded and at least 256 bits (32 bytes) long.

To consume the persistent cookies generated by instances of the Set Persistent Cookie node in the tree, ensure they are using the same HMAC signing key.

To generate an HMAC signing key, run one of the following commands:

$ openssl rand -base64 32

$ cat /dev/urandom | LC_ALL=C tr -dc 'a-zA-Z0-9' | fold -w 32 | head -n 1|base64

Persistent cookie name

Specifies the name of the persistent cookie to check.

Example

The PersistentCookie authentication tree, showing persistent cookie decision and set persistent cookie node usage.

The Set Custom Cookie node lets you store an additional custom cookie in the client. The node uses the specified properties to create a cookie with a custom name and value, and optionally, sets attributes such as the cookie path, domain, expiry, and security flags.

Tree evaluation continues along the single outcome path. The custom cookie is created when AM next returns to the client.

The Set Custom Cookie node can be used in conjunction with the Configuration Provider node to extend custom capabilities. For instance, create a Config Provider script to set custom static values or access values from the shared or transient state.

Include all the Set Custom Cookie node attributes in the configuration provider script’s config map. This example shows how to set the attributes of the custom cookie to static values:

config = {
    "name": "testname",
    "value": "testvalue",
    "maxAge": "60",
    "domain": "am.exampledomain.com",
    "path": "/",
    "useSecureCookie": false,
    "useHttpOnlyCookie": false,
    "sameSite": "LAX"
};

Reference the script when you create a Configuration Provider node, and set the Node Type to Set Custom Cookie. For example:

Configuration Provider node referencing the Set Custom Cookie node

Example

This example uses a Set Custom Cookie node in a login tree. The custom cookie is set in the client after the user has successfully authenticated.

Figure 16. Login Tree With Set Custom Cookie Node (ForgeRock Identity Platform)

Properties

Property Usage

Custom Cookie Name

Sets the name of the custom cookie.

The cookie name can contain any US-ASCII characters except for: space, tab, control, or a separator character (()<>@,;:"/[]?=\{}).

Custom Cookie Value

Sets the value of the custom cookie.

Max Age

(Optional). Specifies the length of time the custom cookie remains valid, in seconds. If that time is exceeded, the cookie is no longer valid.

Both the Max-Age and Expires attributes are set in the cookie to increase compatibility with different browsers.

If omitted, the cookie will expire at the end of the current session. The precise implementation of this is determined by the specific browser. See RFC 6265 for details.

Custom Cookie Domain

(Optional). Sets the domain that the custom cookie will be sent to.

Custom Cookie Path

(Optional). Sets the path of the custom cookie.

Use Secure Cookie

When enabled, adds the Secure flag to the custom cookie.

If the Secure flag is included, the cookie can only be transferred over HTTPS. When a request is made over HTTP, the cookie is not made available to the application.

Use HTTP Only Cookie

When enabled, adds the HttpOnly flag to the custom cookie.

When the HttpOnly flag is included, the cookie is not accessible to scripts.

Custom Cookie SameSite attribute

Sets the SameSite attribute of the custom cookie.

The default value is LAX, to align with most modern browsers.

For more information about cookies in AM, see SameSite cookie support in AM and IG.

The Set Persistent Cookie authentication node creates a persistent cookie named after the value specified in the Persistent cookie name property, the default being session-jwt.

The cookie contains a JWT, inside which there is a JSON payload with information such as the UID of the identity, and the client IP address.

The node encrypts the JWT using the key pair specified in the Persistent Cookie Encryption Certificate Alias property. This property can be found by navigating to Configure > Authentication > Core Attributes > Security.

The node signs the cookie with the signing key specified in the HMAC signing key property. Any node that will read the persistent cookie must be configured with the same HMAC signing key.

Properties

Property Usage

Idle Timeout

Specifies the maximum amount of idle time allowed before the persistent cookie is invalidated, in hours. If no requests are received and the time is exceeded, the cookie is no longer valid.

Max life

Specifies the length of time the persistent cookie remains valid, in hours. If that time is exceeded, the cookie is no longer valid.

Use Secure Cookie

When enabled, adds the Secure flag to the persistent cookie.

If the Secure flag is included, the cookie can only be transferred over HTTPS. When a request is made over HTTP, the cookie is not made available to the application.

Use HTTP Only Cookie

When enabled, adds the HttpOnly flag to the persistent cookie.

HMAC Signing Key

Specifies a key to use for HMAC signing of the persistent cookie. Values must be base64-encoded and at least 256 bits (32 bytes) long.

To consume the persistent cookies generated by instances of the Set Persistent Cookie node in the tree, ensure they are using the same HMAC signing key.

To generate an HMAC signing key, run one of the following commands:

$ openssl rand -base64 32

$ cat /dev/urandom | LC_ALL=C tr -dc 'a-zA-Z0-9' | fold -w 32 | head -n 1|base64

Persistent Cookie Name

Specifies the name used for the persistent cookie.

Federation Authentication Nodes

Use the following nodes to configure trees with federation capabilities, such as OAuth 2.0, social authentication, and account provisioning:

SAML2 Authentication node

This node lets you integrate SAML v2.0 SSO into an AM authentication tree. Use it when deploying SAML v2.0 single sign-on in integrated mode (SP-initiated SSO only).

SLO is not supported, even though the UI has an option to enable it.

If a user account is found that matches the federated account, tree evaluation continues along the "Account Exists" outcome. Otherwise, a matching account could not be found, and tree evaluation continues along the "No Account Exists" outcome.

If the node continues along the "Account Exists" or along the "No Account Exists" outcomes (in other words, if the node reaches the end of its processing without a failure), it sets the successURL parameter in the tree’s shared state to the value of the RelayState parameter in the request, if any.

If the request does not provide a value, the node uses the default RelayState value configured in the SP.

You can dynamically provision an account on the SP if it does not exist, or you can link the remote account to a local account using the Write Federation Information node.

Before attempting to configure a SAML2 authentication node, ensure that:

You have configured a remote IdP and a hosted SP in a CoT in the same realm where the authentication node will be configured.
The SP is configured for integrated mode. See SSO and SLO in Integrated Mode.

Properties

Property Usage

IdP Entity ID

Specifies the name of the remote IdP.

SP MetaAlias

Specifies the local alias for the SP, in the format /Realm Name/SP Name.

Allow IdP to Create NameID

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

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

Default: Enabled

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

Authentication Context Class Reference

(Optional) 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. In the AM admin UI, go to Realms > Realm Name > Applications > Federation > Entity Providers > Service Provider Name > Assertion Content > Authentication Context.

Authentication Context Supported by the SP

When specifying multiple authentication context classes, use the kbd:[|] character to separate the classes. For example:

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

Authentication Context Declaration Reference

(Optional) Specifies one or more URIs that identify authentication context declarations.

When specifying multiple URIs, use the kbd:[|] 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.

Request Binding

Specifies the format the SP will use to send the authentication request to the IdP.

Valid values are HTTP-Redirect and HTTP-POST.

Default: HTTP-Redirect

Response Binding

Specifies the format the IdP will use to send the response to the SP.

Valid values are HTTP-POST and HTTP-Artifact.

Default: HTTP-Artifact

Force IdP Authentication

Specifies whether the IdP forces authentication or if it can reuse existing security contexts.

Default: Disabled

Passive Authentication

Specifies whether the IdP uses 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.

Default: Disabled

NameID Format

Specifies the SAML name ID format that will be requested in the SAML authentication request. For example:

urn:oasis:names:tc:SAML:2.0:nameid-format:persistent
urn:oasis:names:tc:SAML:2.0:nameid-format:transient
urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified

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

Single Logout Enabled

Not implemented.

Single Logout URL

Not implemented.

For examples, see SSO and SLO in Integrated Mode.

This node is used alongside the Select Identity Provider node to enable use of the Social Identity Provider Service.

It takes the provider selection from the Select Identity Provider node and attempts to authenticate the user with that provider. It then collects relevant profile information from the provider and returns the user to the flow, and transforms that profile information into attributes AM can use.

Properties

Property Usage

Transformation Script

A script that transforms a normalized social profile to an identity or managed object.

Select Normalized Profile to Managed User, or any other script you have created for this purpose.

Username Attribute

The attribute in IDM that contains the username for this object.

Client Type

Specify the client type you are using to authenticate to the provider.

Use the default, BROWSER, when making use of the ForgeRock-provided user interfaces, or the ForgeRock SDK for JavaScript. This causes the node to return the RedirectCallback.

Select NATIVE if you are using the ForgeRock SDKs for Android or iOS. This causes the node to return the IdPCallback.

Write Federation Information node

This node creates a persistent link between a remote IdP account and a local account in the SP, if none exists yet. If a transient link exists, it is persisted. Existing account links with different IdPs are not lost.

Use this node alongside the SAML2 Authentication node, and ensure that the NameID Format is persistent.

Properties

This node has no configurable properties.

For examples, see SSO and SLO in Integrated Mode.

Identity Management Authentication Nodes

Use the following nodes to perform identity management during an authentication tree flow, such as mapping anonymous users to a session.

Accept Terms and Conditions node

This node prompts the user to accept the currently active terms and conditions.

For information on setting up terms and conditions, see Terms & Conditions in the platform documentation.

This node is used in a registration tree, or combined with the Terms and Conditions Decision node in a progressive profile or login tree.

Note that there is no failure path for this node. The user must accept the terms and conditions in order to proceed:

Example Accept Terms and Conditions Node Output.

Properties

This node has no configurable properties.

Example

In a progressive profile tree, the Accept Terms and Conditions node is used after the Terms and Conditions Decision node. If the user has not accepted the latest version of the Terms and Conditions, they are taken to a page notifying them that proceeding indicates accepting the current Terms and Conditions.

If the user clicks next, the acceptance response is stored in IDM.

An Example authentication tree, showing Accept Terms and Conditions node usage.

Figure 17. Example Tree With Accept Terms and Conditions Node

Anonymous User Mapping node

The Anonymous User Mapping node lets users log in to your application or website 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.

The anonymous user status is Inactive by default. If you use the default anonymous user in this node, you must change the user status to Active.

Properties

Property

Usage

Anonymous User Name

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

Example

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

A tree showing Social Identity Provider login With Anonymous User Mapping node

Anonymous Session Upgrade node

The Anonymous Session Upgrade node allows an anonymous session to be upgraded to a non-anonymous session by adding the Anonymous Session Upgrade node as the first node in any tree.

Properties

This node has no configurable properties.

Example

After using the Anonymous User Mapping node to access AM as an anonymous user, the Anonymous Session Upgrade authentication node lets users upgrade their session to a non-anonymous one.

Figure 18. Example Tree With Anonymous Session Upgrade node

Attribute Collector node

The Attribute Collector node is used to collect the values of attributes for use elsewhere in a tree, such as collecting user information to populate a new account in a registration tree.

To request a value, the attribute must be present in the IDM schema of the Identity Object configured in the tree. This node supports three types of attributes: string, boolean, and number.

The node configuration allows the admin to specify if the attributes are required to continue, and if they should be subject to validation through IDM’s policy filter.

You can place the node anywhere in your authentication tree, or within a page node.

Properties

Property

Usage

Attributes to Collect

A list of the attributes you wish to collect, based on the attributes found in the IDM schema for the identity object configured in the tree.

All Attributes Required

When enabled, all attributes collected in this node are required in order to continue.

Validate Input

When enabled, the content input in this node should be validated against IDM policy settings specified in the IDM schema.

Identity Attribute

The attribute used to identify the object in IDM.

Attribute Present Decision node

Checks if an attribute is present on an object, regardless of whether the field is private. Use this to verify an attribute is present, without needing to know the value of the attribute itself.

A good use case is during an update password flow, where you want to check if the account has a password (rather than no password and logging in through a social identity) before continuing.

This node is similar to the Attribute Value Decision node when that node is set to use the PRESENT operator, except it cannot return the value of the attribute, but can work with private attributes.

Properties

Property Usage

Present Attribute

The object attribute to verify is present in the IDM object. This can be an otherwise private attribute, such as password.

Identity Attribute

The attribute used to identify the object in IDM.

Attribute Value Decision node

Verifies that the user’s specified attribute satisfies a specific condition.

Use this node to check whether an attribute’s expected value is equal to a collected attribute value, or to validate that a specified attribute has been collected (regardless of the value of that attribute).

For example, to validate that a user filled out the country attribute when registering, set the comparison operation to PRESENT, and the comparison attribute to country.

If you instead need to ensure the country attribute is set to the United States, set the comparison operation to EQUALS, the comparison attribute to country, and the comparison value to United States.

Use Attribute Present Decision node instead when you need to check for the presence of a private attribute (such as, password).

Properties

Property Usage

Comparison Operation

The operation to perform on the object attribute; PRESENT checks for existence of an attribute, EQUALS checks if the object’s attribute value equals the configured comparison value.

Comparison Attribute

The object attribute to compare.

Comparison Value

This property is only relevant when using the EQUALS comparison operation, and is the value to compare the object’s attribute value to.

Identity Attribute

The attribute used to identify the object in IDM.

Create Object node

The Create Object node is used to create a new object in IDM based on information collected during an auth tree flow, such as user registration.

Any managed object attributes that are marked as required in IDM will need to be collected during the auth tree flow in order for the new object to be created.

Properties

Property

Usage

Identity Resource

The type of IDM managed identity resource object that this node will create. It must match the identity resource type for the current tree.

To check for the available managed identity resource types, go to the IDM admin UI, and open the Manage drop-down list, at the upper right corner of the screen.

Identity managed object types are preceded by the icon.

The Consent Collector node prompts the user to consent to share their profile data.

A consent notice is listed for each IDM mapping that has consent enabled. If an IDM mapping is not created, or the mappings do not have privacy and consent enabled, no consent message will be shown to the user.

This node is primarily used in progressive profile or registration flows.

Properties

Property Usage

All Mappings Required

If enabled, all mappings listed by this node require consent in order to move forward.

Privacy & Consent Message

Localized message providing the privacy and consent notice. The key is the language (such as en or fr), and the value is the message to display.

Display Username node

This node is used to fetch a username based on a different identifying attribute (such as an email address), then display it on screen. To email the username to the user instead, use the Identify Existing User node combined with a Email Suspend node or Email Template node. The Display Username node requires IDM integration to function.

Properties

Property

Usage

User Name

The attribute used to identify the username in an IDM object.

Identity Attribute

The attribute used to identify the object in IDM. Since this node is generally used for recovering a username, the identity attribute in this case should be some other attribute that is unique to a user object, such as the user’s email address. You will receive an exception if there is more than one result for this attribute, so make sure the value of whatever attribute you select is unique for each user.

Identify Existing User node

This node verifies a user exists based on an identifying attribute, such as an email address, then makes the value of a specified attribute available in a tree’s shared state.

For example, use this node in a "Forgot Username" flow to fetch a username to email to the user. If you want to display the username on screen, use the instead.

Properties

Property

Usage

Identifier

The attribute to collect from an IDM object.

Identity Attribute

Example

The following is an example of a forgotten password tree. The user enters information that the Identify Existing User will use to try to identify them. Next, AM uses the Email Suspend node to send an email to the user and suspend the authentication tree. Once authentication is resumed, the user is sent to a different tree to reset their password:

Authentication tree showing identify existing user node usage during a forgotten password flow.

Figure 19. Identify Existing User Tree

KBA Decision node

The KBA Decision node is used to check if the minimum number of KBA questions required by the system are defined for the user.

The number of KBA questions is determined by the minimumAnswersToDefine property in selfservice.kba.json in IDM. This node is mainly used for Progressive Profile completion.

Properties

Property

Usage

Identity Attribute

The attribute used to identify the object in IDM.

KBA Definition node

The KBA Definition node collects KBA questions and answers from the user and saves them to the user object.

This is used when creating or updating a user with Knowledge-Based Authentication enabled. For more information, see Security Questions.

Properties

Property

Usage

Purpose Message

A localised message describing the purpose of the data requested from the user.

KBA Verification node

The KBA Verification node presents KBA questions to the user, collects answers to those questions, and verifies the input against the user’s stored answers.

This is used during self-service actions such as Forgot Password or Forgot Username, where additional authentication is needed. The number of KBA questions is determined by the minimumAnswersToVerify property in selfservice.kba.json in IDM.

Properties

Property

Usage

KBA Attribute

The IDM object attribute in which KBA questions and answers are stored.

Identity Attribute

The attribute used to identify the object in IDM.

Pass-Through Authentication node

The Pass-Through Authentication node authenticates an identity through a connector to a third-party service. This lets you migrate user profiles without forcing users to reset their passwords, or retain a third-party service indefinitely as the canonical store for authentication credentials.

Before you use the node:

Configure the connector to the third-party service.

For details, see Connector configuration.
If you plan to collect credentials in the identity repository for users, synchronize accounts from the third-party service.

For details, see Sync identities.

Use this node after collecting the authentication credentials. For example, use the Platform Username node and Platform Password node to collect the username and password.

Pass the credentials to this node to authenticate the identity against the service.

Properties

Property Usage

System Endpoint

Required. Name of the connector to the third-party service that performs authentication.

Object Type

The OpenICF object type for the object being authenticated.

Default: account

Identity Attribute

The username attribute for authentication.

Default: userName

Password Attribute

The password attribute for authentication.

Default: password

Example

Before trying this example, synchronize accounts from the third-party service. The example shows a login journey that tries pass-through authentication when local authentication fails, and stores the user password when authentication with the third-party service succeeds.

In this example, the user enters their credentials with the Platform Username node and Platform Password node. The Data Store Decision node authenticates against the platform directory service. On failure, authentication passes through to the third-party service. On success, the Identify Existing User node and Required Attributes Present node check for a valid user profile. The Patch Object node updates the user’s profile with the successful password:

Pass-through authentication that updates user credentials.

Figure 20. Pass-Through Authentication

Patch Object node

The Patch Object node is used to update attributes in an existing managed object in IDM.

This is used in cases such as progressive profile completion, where you may wish to collect additional profile data from a user after they have logged in several times.

Properties

Property Usage

Patch as Object

Allows patching as the object being updated. Enable this property to patch a user object as part of the user’s current session, such as when updating their password.

Ignored Fields

Fields from the tree’s shared state that should be ignored as part of patch. If this is empty, all shared-state fields in the tree’s nodeState object are attempted as part of the patch. Use this to keep your patch focused only on the fields you want to update.

Identity Resource

The type of IDM managed identity resource object that this node will create. It must match the identity resource type for the current tree.

To check for the available managed identity resource types, go to the IDM admin UI, and open the Manage drop-down list, at the upper right corner of the screen.

Identity managed object types are preceded by the icon.

Identity Attribute

The attribute used to identify the object to update in IDM.

Platform Password node

This node prompts the user to enter their password and stores the input in a configurable state attribute.

Use this node instead of the Password Collector node for Identity Cloud deployments.

This node uses the _id of the object for policy evaluation. For existing users, the user’s _id must therefore be in the shared state for user-specific policies (such as password history, cannot-contain-others, and so on) to be evaluated. (No _id is available for new users.)

Properties

Property Usage

Validate Password

When enabled, this node checks the user’s input against IDM’s password policies, and returns any policy failures as errors. For example, if you submitted an invalid password on registration, the response from this node would include a list of failed policies:

{
    "name": "failedPolicies",
    "value": [
        "{ \"params\": { \"minLength\": 8 },
           \"policyRequirement\": \"MIN_LENGTH\" }",
        "{ \"params\": { \"numCaps\": 1 },
           \"policyRequirement\": \"AT_LEAST_X_CAPITAL_LETTERS\" }",
        "{ \"params\": { \"numNums\": 1 },
           \"policyRequirement\": \"AT_LEAST_X_NUMBERS\" }"
    ]
},

Password Attribute

The attribute used to store a password in the IDM object.

Platform Username node

This node prompts the user to enter their username, and stores it in a configurable state attribute.

Use this node instead of the Username Collector node when working with AM and IDM as an integrated platform.

Properties

Property

Usage

Validate Username

When enabled, this node checks the user’s input against IDM’s username policies, and returns any policy failures as errors.

Username Attribute

The attribute used to store a username in the IDM object.

Profile Completeness Decision node

The Profile Completeness Decision node is used in progressive profile flows. It checks how much of a user’s profile has been filled out, where the completeness of a profile is expressed as a percentage of user-viewable, user-editable fields that are not null.

Properties

Property

Usage

Profile Completeness Threshold

Percentage of user-viewable and user-editable fields in a profile that need to be filled out for the node to pass. Expressed as a number between 0 and 100.

Identity Attribute

The attribute used to identify the object in IDM.

Query Filter Decision node

Checks if the contents of a user’s profile matches a specified query filter.

Use this node to verify whether a particular field has been filled out, or that the contents of a field match a specific pattern. For instance, use this in progressive profile flows to check if marketing preferences are set on a user’s profile.

For more information on constructing effective query filters, see Construct queries.

Properties

Property

Usage

Query Filter

A query filter used to check the contents of an object.

Identity Attribute

The attribute used to identify the object that will be queried in IDM.

Required Attributes Present node

The Required Attributes Present node checks the specified identity resource in IDM (by default, managed/user), and determines if all attributes required to create the specified object exist within shared state of the tree.

Properties

Property

Usage

Identity Resource

The type of IDM managed identity resource object that this node will create. It must match the identity resource type for the current tree.

To check for the available managed identity resource types, go to the IDM admin UI, and open the Manage drop-down list, at the upper right corner of the screen.

Identity managed object types are preceded by the icon.

Select Identity Provider node

This node is used in combination with the Social Provider Handler node to enable use of the Social Identity Provider Service. It presents the user with a list of configured, enabled, social identity providers to use for authentication.

The node has two possible outputs: social authentication, and local authentication. Local authentication can be turned off by disabling Include local authentication.

This node returns the SelectIdPCallback] when more than one social identity provider is enabled, or a single provider is enabled as well as the Local Authentication option, and therefore a choice from the user is required. If no choice from the user is required, authentication proceeds to the next node in the tree.

Properties

Property

Usage

Include local authentication

Determines whether local authentication will be included as an available method for authenticating.

Offer only existing providers

Password attribute

Identity Attribute

Filter Enabled Providers

By default, the node displays all identity providers that are marked as Enabled in the Social Identity Provider Service as a selectable option. Specify the name of one of more providers to filter the list.

View the names of your configured social identity providers by navigating to Services > Social Identity Provider Service > Secondary Configurations.

If this field is not empty, providers must be in the list, and also be enabled in the Social Identity Provider service, in order to be displayed. If left blank, all enabled providers are displayed.

Terms and Conditions Decision node

The Terms and Conditions Decision node verifies that the user has accepted the active set of Terms and Conditions. Use this node to verify that the user has accepted your Terms and Conditions before proceeding (such as logging in, or in a progressive profile tree). The node is often used with the Accept Terms and Conditions node.

For information on setting up Terms and conditions, see Terms & Conditions in the platform documentation.

Properties

Property

Usage

Identity Attribute

The attribute used to identify the object to check in IDM.

Time Since Decision node

Checks if a specified amount of time has passed since the user was registered.

For example, if you wanted to prompt users to review your terms and conditions after the account is a week old, you could set the Elapsed Time property to 10080 minutes. After that time has elapsed, the next time the user logs in, they will be prompted to review your terms and conditions.

This node is mainly used for Progressive Profile completion.

Properties

Property Usage

Elapsed Time

The amount of time since the user was created, in minutes, that needs to elapse before this node is triggered.

This property also supports specifying basic time units. For example, when setting the property to 10080 minutes, writing 7 days or 1 week also works.

Identity Attribute

The attribute used to identify the object to update in IDM.

Utility Authentication Nodes

Use the following nodes to perform various tasks during the authentication flow:

Agent Data Store Decision node

The Agent Data Store Decision authentication node verifies that a provided agent ID and password match a web agent or Java agent profile configured in AM.

Non-agent identities, such as users stored in configured identity repositories, cannot be verified by using the Agent Data Store Decision node. Instead, you should use the Data Store Decision node.

Tree evaluation continues along the True path if the credentials match those of a configured agent profile. Otherwise, the tree evaluation continues along the False path.

Properties

This node has no configurable properties.

Choice Collector node

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

Properties

Property

Usage

Choices

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

To remove a choice, select its Delete icon (kbd:[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:

Email Suspend node

The Email Suspend node is used to generate and send an email to a user, such as an address verification email, based on an email template in IDM. The authentication tree will pause until the user clicks a link in the email to resume the tree flow.

The link is generated by the Email Suspend node, and is passed along to IDM as part of the email object, in a property called resumeURI.

This node uses the email service configured in IDM to send email. If you do not need the auth tree to pause and wait for a response from email, use the Email Template node instead.

Properties

Property Usage

Email Template Name

The name of the IDM email template to be sent. Check IDM for the names of available email templates, or to create a new template.

Email Attribute

The IDM attribute storing the address to send the email to.

Email Suspend Message

The localized message to be returned once the tree is suspended. The default message is, "An email has been sent to your inbox."

Object Lookup

Determines whether the object should be looked up in IDM. If true, IDM is queried for an existing object. Otherwise, the object in the authentication tree’s shared state is used. For example, if suspending a user registration flow before the user object is created in IDM, this should be set to false. If the registration flow has already created the new user object when the flow is suspended, then this should be set to true.

Identity Attribute

The attribute used to identify the object in IDM.

Example

The following is an example of a forgotten password tree. The user enters information that the Identify Existing User node will use to try to identify them. Next, AM uses the Email Suspend node to send an email to the user and suspend the authentication tree. Once authentication is resumed, the user is sent to a different tree to reset their password:

Authentication tree showing email suspend node usage during a forgotten password flow.

Figure 21. Email Suspend Tree

Email Template node

The Email Template node is used to generate and send an email to a user, such as a welcome email, based on an email template in IDM.

This node uses the email service configured in IDM to send email. If you need the auth tree to pause and wait for a response from email, use the Email Suspend node instead.

This node has two possible outcomes: "Email Sent" and "Email Not Sent", which can be used if you need different behavior depending on the outcome. According to OWASP authentication recommendations, the message to the user should be the same in both cases.

Properties

Property

Usage

Email Template Name

The name of the IDM email template to be sent. Check IDM for the names of available email templates, or to create a new template.

Email Attribute

The IDM attribute storing the address to send the email to.

Identity Attribute

The attribute used to identify the object in IDM.

Failure URL node

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

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

For more information on how AM determines the redirection URL, and to configure the Validation Service to trust redirection URLs, see Configure success and failure redirection URLs.

The URL is also saved into the nodeState object for the failureUrl key, which can be useful for custom node developers.

Properties

Property

Usage

Failure URL

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

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 with the specified key in the tree’s nodeState 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 Session upgrade.

The node will fail with an error if you attempt to get a property when the user does not have an existing session. Use a Scripted Decision node to determine if an existing session is present.

Example Check for Existing Session Script

if (typeof existingSession !== 'undefined')
{
  outcome = "hasSession";
}
else
{
  outcome = "noSession";
}

Properties

Property Usage

Session Data Key

Specify the name of a key in the user’s session data to use to retrieve the value.

Shared State Key

Specify the name of a key in the nodeState object to use to store the retrieved value.

Example

Figure 22. Get Session Data Tree Example

The following table includes example keys that may be available in an existing session, and corresponding sample values:

Table 7. Get Session Data Example Keys and Values
Key	Sample value
`AMCtxId`	`e370cca2-02d6-41f9-a244-2b107206bd2a-122934`
`amlbcookie`	`01`
`authInstant`	`2018-04-04T09:19:05Z`
`AuthLevel`	`0`
`CharSet`	`UTF-8`
`clientType`	`genericHTML`
`FullLoginURL`	`/openam/UI/Login?realm=%2F`
`Host`	`198.51.100.1`
`HostName`	`openam.example.com`
`Locale`	`en_US`
`Organization`	`dc=openam,dc=forgerock,dc=org`
`Principal`	`uid=amAdmin,ou=People,dc=openam,dc=forgerock,dc=org`
`Principals`	`amAdmin`
`Service`	`ldapService`
`successURL`	`/openam/console`
`sun.am.UniversalIdentifier`	`uid=amAdmin,ou=People,dc=openam,dc=forgerock,dc=org`
`UserId`	`amAdmin`
`UserProfile`	`Required`
`UserToken`	`amAdmin`
`webhooks`	`myWebHook`

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.

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

Property

Usage

Tree name

Enter the name of the tree to evaluate.

Message node

The Message authentication node lets you present a custom, localized message to the user.

In addition to the message, you can provide a localized positive, and negative response that the user must select to proceed.

Properties

Property Usage

Message

Click Add. Enter the message locale in the Key field; for example en-gb. Enter the message to display to the user in the Value field.

Locales that you specify here must be real locales, otherwise AM returns an Invalid config error.

If the locale of the user’s browser does not match any locale configured in the node, the node uses the Default Authentication Locale (set, per realm, in Authentication > Settings > General). If there is no default authentication locale, the node uses the Default Locale (set in Deployment > Servers > Server Name >General > System).

If the message property is left blank, the text Default message is displayed to the user.

To remove a message, select its Delete icon ().

Positive answer

Specify a positive answer that will cause tree evaluation to continue along the True outcome path.

Click the Add button, and then enter the locale of the positive answer in the Key field, and the message to display to the user in the Value field.

If the locale of the user’s browser cannot be determined during authentication, the first message in the list is used.

If the message property is left blank, the text Yes is displayed to the user.

To remove a message, select its Delete icon ().

Negative answer

Specify a negative answer that will cause tree evaluation to continue along the False outcome path.

Click the Add button, and then enter the locale of the negative answer in the Key field, and the message to display to the user in the Value field.

If the locale of the user’s browser cannot be determined during authentication, the first message in the list is used.

If the message property is left blank, the text No is displayed to the user.

To remove a message, select its Delete icon ().

Example

Meter node

The Meter authentication node increments a specified metric key each time tree evaluation passes through the node.

Properties

Property

Usage

Metric Key

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

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

Property

Usage

Header

Optional. Localized title for the page node and the nodes contained within it. Use this when components of an authentication flow need a title, such as breaking a registration into labelled sections.

Description

Optional. A localized description for the page node and the nodes contained within it. Use this when additional descriptive text is needed in an authentication flow.

Stage

Optional. This is used in UI development, to help identify what node or series of nodes are being returned so they can be rendered in the UI appropriately.

The Page node’s optional properties are passed in the response, but the UI needs to support these properties before they will be visible to the end user.

Example

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

Figure 23. Example Tree With Page Node

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

User’s view of an example tree containing a page node.

Figure 24. User View of Example Tree with Page Node

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 \
--cookie "<session-cookie-name>=AQIC5w…NTcy*" \" \
--request POST \
--header "Content-Type: application/json" \
--header "Accept-API-Version: resource=2.0, protocol=1.0" \
--data '{
    "authId":"eyJ0eXAiOi…WLxJ-1d6ovYKHQ",
    "template":"",
    "stage":"AuthenticatorPush3",
    "header":"Authenticator Push",
    "callbacks":[
        {
            "type":"PollingWaitCallback",
            "output":[
                {
                    "name":"waitTime",
                    "value":"10000"
                }
            ]
        },
        {
            "type":"ConfirmationCallback",
            "output":[
                {
                    "name":"prompt",
                    "value":""
                },
                {
                    "name":"messageType",
                    "value":0
                },
                {
                    "name":"options",
                    "value":[
                        "Use Emergency Code"
                    ]
                },
                {
                    "name":"optionType",
                    "value":-1
                },
                {
                    "name":"defaultOption",
                    "value":0
                }
            ],
            "input":[
                {
                    "name":"IDToken2",
                    "value":100
                }
            ]
        }
    ]
}' \
"https://<tenant-name>.forgeblocks.com/am/json/realms/root/realms/alpha/authenticate\
?authIndexType=composite_advice\
&authIndexValue=%3CAdvices%3E%0A\
%3CAttributeValuePair%3E%0A%3CAttribute%20name%3D\
%22TransactionConditionAdvice%22%2F%3E%0A\
%3CValue%3E9dae2c80-fe7a-4a36-b57b-4fb1271b0687\
%3C%2FValue%3E%0A%3C%2FAttributeValuePair\
%3E%0A%3C%2FAdvices%3E"

For more information on authenticating using the REST API, see Authenticate using REST.

When using the UI for authentication, it automatically waits for the required amount of time and resubmits 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

Property Usage

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.

Messages provided in the node override the defaults provided by AM.

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.

Messages provided in the node override the defaults provided by AM.

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 Configuring Authentication Webhooks.

Properties

Property

Usage

Webhook name

Specify the name of the webhook to register.

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

Property

Usage

Property Names

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

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

Property Usage

Retry limit

Specify the number of times to allow a retry.

Default: 3

Save Retry Limit to User

Specify whether the number of failed login attempts persists between successful authentications. Possible values are:

Enabled. The node saves the number of failed login attempts to the user’s profile. New authentication journeys using the Retry Limit Decision node will use the stored value as the starting point for the retry limit.

AM resets the count after the user authenticates successfully with a tree that contains this node.

If AM cannot find the user’s profile, the authentication journey will end with an error.
Disabled. The node saves the number of failed login attempt in the tree’s nodeRetryLimitKey shared state property, which is discarded when the authentication session ends.

For security reasons, ForgeRock recommends that you enable this setting.

Default: Enabled.

Example

The RetryLimit authentication tree, showing Retry Limit Decision node usage.

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.

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

All of the inputs required by the script and the outputs produced by it must be declared in the node’s configuration or the script may fail. Even if the definition is null, it still needs to be declared. Use the wildcard * to include any available inputs or outputs.

For information about the API available for use in the Scripted Decision node, see Scripted decision node API.

Properties

Property Usage

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.

Script Inputs

A list of state inputs required by the script. Defaults to *.

Script Outputs

A list of state outputs produced by the script. Defaults to *.

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.

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

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

Properties

Property

Usage

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.

Success URL node

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

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

For more information on how AM determines the redirection URL, and to configure the Validation Service to trust redirection URLs, see Configure success and failure redirection URLs.

The URL is also saved into the nodeState object for the successUrl key, which can be useful for custom node developers.

Properties

Property

Usage

Success URL

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

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

Property

Usage

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.

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.

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.

Properties

Property

Usage

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.

Scripted decision node API

The scripted decision node lets you write a server-side script in JavaScript to determine the path the authentication journey takes.

These scripts have access to a number of bindings, which provide the context to help you make the decision.

The primary role of a scripted decision node is to specify the possible paths a user can take. There are two methods to define these paths within the script:

outcome

The simplest method is to assign one or more string values to the outcome variable.

if (...) {
  outcome = "true"
} else {
  outcome = "false"
}

When configuring the scripted decision node in an authentication tree, add the two outcomes true and false, and connect them to other parts of the tree, so that tree evaluation can continue.

You can specify as many outcomes as required in your scripts; for example, you might have hours, days, and months. Be sure to specify each possible outcome when designing your authentication journey.

Action

You can use the Action interface to define the script outcome and/or specify an operation to perform.

Example:

var fr = JavaImporter(
    org.forgerock.openam.auth.node.api.Action
)

if (...) {
  // Set outcome to "true", and create and populate a custom session property:
  action = fr.Action.goTo("true").putSessionProperty("customKey", "customValue").build()
}
else
{
  // Set outcome to "false". If supported by the UI, the error message is displayed:
  action = fr.Action.goTo("false").withErrorMessage("Friendly error description.").build()
}

You can also use the Action interface for other functionality:

Set session properties
Callbacks

An outcome specified as an Action takes precedence over the value set for the outcome variable:

action = Action.goTo("false").build() // Tree continues along "false" outcome.

outcome = "true" // No effect.

For more information on specifying outcomes when using the scripted decision node, see Scripted Decision node.

The following table lists the bindings accessible to scripted decision node scripts:

Table 8. Scripted decision node bindings
Binding	Information
`auditEntryDetail`	Add information to the AM audit logs. See Audit information.
`callbacks`	Request additional data from the user, by sending any of the supported callbacks. See Callbacks.
`existingSession`	If the user has previously authenticated and has a session, use this variable to access the properties of that session. The user will only have an existing session when performing a session upgrade. Any properties that may have been added by nodes earlier in the current tree will not appear on the user’s new session until the authentication tree is completed, and are therefore not available to the `existingSession` variable. See Access existing session properties.
`httpClient`	Make outbound HTTP calls.
`idRepository`	Access the data stored in the user’s profile. See Access profile data.
`logger`	Write information to the AM debug logs.
`realm`	Return the name of the realm to which the user is authenticating as a string. For example, authenticating to the top-level realm returns a string value of `/` (forward-slash). Authenticating to a subrealm of the top level realm might return `/subRealm`.
`requestHeaders`	Access the HTTP headers provided in the login request. See Access request header data.
`requestParameters`	Access the HTTP headers provided in the login request. See Access request parameter data.
`secrets`	Access the secrets configured in an AM instance.
`nodeState`	Access data set by previous nodes in the tree, or store data to be used by subsequent nodes. See Access shared state data.

Access request header data

Scripted Decision node scripts can access the headers provided by the login request by using the methods of the requestHeaders object.

Note that the script has access to a copy of the headers. Changing their values does not affect the request itself.

Methods

String[] requestHeaders.get(String HeaderName)

Return a java.util.ArrayList of the values in the named request header, or null, if the property is not set. Note that header names are case-sensitive.

Example:

var headerName = "user-agent"

if (requestHeaders.get(headerName).get(0).indexOf("Chrome") !== -1) {
    outcome = "true"
} else {
    outcome = "false"
}

Access request parameter data

Scripted Decision node scripts can access any query parameters provided by the login request by using the methods of the requestParameters object.

Note that the script has access to a copy of the parameters. Changing their values does not affect the request itself.

Methods

String[] requestParameters.get(String ParameterName)

Return a java.util.ArrayList of the values in the named request parameter, or null, if the parameter is not available.

Example:

var service
var authIndexType = requestParameters.get("authIndexType")

if (authIndexType && String(authIndexType.get(0)) === "service") {
    service = requestParameters.get("authIndexValue").get(0)
}

In JavaScript, the values stored in requestParameters have a typeof of object, and represent the java.lang.String class. Convert the value to a string in order to use strict equality comparisons.

Access shared state data

Scripted Decision node scripts can get access to the shared state within the tree by using the nodeState object.

Methods

JsonValue nodeState.get(String Property Name)

Returns the value of the named property. The value may come from the transient, secure, or shared states, in that order. For example, if the same property is available in several states, the method will return the value of the property in the transient state first.

If the property is not set, the method returns null.

Note that property names are case-sensitive.

Example:

var currentAuthLevel = nodeState.get("authLevel").asString()
var givenPassword = nodeState.get("password").asString()

nodeState nodeState.putShared(String PropertyName, String ProperyValue)

Sets the value of the named shared state property. Note that property names are case-sensitive.

Example:

try {
  var currentAuthLevel = nodeState.get("authLevel").asString()
} catch (e) {
  nodeState.putShared("errorMessage", e.toString())
}

nodeState nodeState.putTransient(String PropertyName, String ProperyValue)

Sets the value of the named transient state property. Note that property names are case-sensitive.

Example:

nodeState.putTransient("sensitiveKey", "sensitiveValue")

Access profile data

Scripted decision nodes can access profile data through the methods of the idRepository object.

Methods

Set idRepository.getAttribute(String UserName, String AttributeName)

Return the values of the named attribute for the named user.

Void idRepository.setAttribute(String UserName, String AttributeName, Array Attribute Values)

Set the named attribute as specified by the attribute value for the named user, and persist the result in the user’s profile.

Example:

var username = nodeState.get("username")
var attribute = "mail"

idRepository.setAttribute(username, attribute, ["user.0@a.com", "user.0@b.com"])

Void idRepository.addAttribute(String UserName, String AttributeName, String Attribute Value)

Add an attribute value to the list of attribute values associated with the attribute name for a particular user.

Example:

var username = nodeState.get("username")
var attribute = "mail"

// Add a value as a String.
idRepository.addAttribute(username, attribute, "user.0@c.com")
logger.error(idRepository.getAttribute(username, attribute).toString())
// > ERROR: [user.0@a.com, user.0@c.com]

// Get the first value.
logger.error(idRepository.getAttribute(username, attribute).iterator().next())
// > ERROR: user.0@a.com

// Get a value at the specified index.
logger.error(idRepository.getAttribute(username, attribute).toArray()[1])
// > ERROR: user.0@c.com

logger.error(idRepository.getAttribute(username, "non-existing-attribute").toString())
// > ERROR: []: If no attribute by this name is found, an empty Set is returned.

Set session properties

Scripted Decision node scripts can create session properties by using the Action interface. The following example sets the outcome to true, and adds a custom session property:

var goTo = org.forgerock.openam.auth.node.api.Action.goTo

action = goTo("true").putSessionProperty("mySessionProperty","myPropertyValue").build()

Add the property name to the Whitelisted Session Property Names list in the Session Property Whitelist Service; otherwise, it will not be added to sessions.

For more information on this service, see Session Property Whitelist Service.

Add the script to a scripted decision node in your authentication tree. Users that authenticate successfully using that tree will have the property added to their session, as shown in the following output when introspecting a session:

{
    "username": "15249a65-8f9a-4063-9586-a2465963cee4",
    "universalId": "id=15249a65-8f9a-4063-9586-a2465963cee4,ou=user,o=alpha,ou=services,ou=am-config",
    "realm": "/alpha",
    "latestAccessTime": "2020-10-22T15:01:14Z",
    "maxIdleExpirationTime": "2020-10-22T15:31:14Z",
    "maxSessionExpirationTime": "2020-10-22T17:01:13Z",
    "properties": {
        "AMCtxId": "dffed74d-f203-469c-9ed2-34738915baea-5255",
        "mySessionProperty": "myPropertyValue"
    }
}

Access existing session properties

Scripted decision node scripts can access any existing session properties during a session upgrade request, by using the existingSession object.

The following table lists the methods of the existingSession object:

Methods

String existingSession.get(String _Property Name)

Return the string value of the named existing session property, or null, if the property is not set. Note that property names are case-sensitive.

If the current request is not a session upgrade and does not provide an existing session, the existingSession variable is not declared. Check for a declaration before attempting to access the variable.

Example:

if (typeof existingSession !== 'undefined')
{
    existingAuthLevel = existingSession.get("AuthLevel")
}
else
{
    logger.error("Variable existingSession not declared - not a session upgrade.")
}

Callbacks

The scripted decision node can use callbacks to provide or request additional information during the authentication process.

Example:

The following script uses the NameCallBack callback to request a "Nickname" value from the user, and adds the returned value to the nodeState object for use elsewhere in the authentication tree:

var fr = JavaImporter(
  org.forgerock.openam.auth.node.api,
  javax.security.auth.callback.NameCallback
)

with (fr) {
  if (callbacks.isEmpty()) {
    action = Action.send(new NameCallback("Enter Your Nickname")).build()
  } else {
    nodeState.putShared("Nickname", callbacks.get(0).getName())
    action = Action.goTo("true").build()
  }
}

For a list of supported callbacks, see Supported callbacks.

Audit information

The scripted decision node can add information to audit log entries, by using the auditEntryDetail variable.

AM appends the value of the variable, which can be either plain text, or a JSON object, to the authentication audit logs.

Example:

The following JavaScript adds the user’s email address to the authentication.audit.json audit log file:

var currentUser = nodeState.get("username")
var attributeToRead = "mail"

auditEntryDetail="Extra Audit: " + currentUser + " email address: " +
  idRepository.getAttribute(currentUser,attributeToRead).iterator().next().toString()
outcome = "true"

The code above adds the information to the auditInfo element in the audit log entry:

{
  "_id":"f036618e-e318-4134-ac2a-13e860396103-545013",
  "timestamp":"2020-08-13T18:20:25.202Z",
  "eventName":"AM-NODE-LOGIN-COMPLETED",
  "transactionId":"f036618e-e318-4134-ac2a-13e860396103-544998",
  "trackingIds":[
    "f036618e-e318-4134-ac2a-13e860396103-544956"
  ],
  "principal":[
    "demo"
  ],
  "entries":[
    {
      "info":{
        "nodeOutcome":"true",
        "treeName":"Example",
        "displayName":"Audit Entry",
        "nodeType":"ScriptedDecisionNode",
        "nodeId":"13d40add-137c-4564-ad3c-7d98f7c180c1",
        "authLevel":"0",
        "nodeExtraLogging":{
          "auditInfo":"Extra Audit: demo email address: demo@example.com"
        }
      }
    }
  ]
}

Identity Cloud

Authentication and SSO

Configure AM for authentication

Multi-factor authentication

Single sign-On

Social authentication

Introduction to authentication

Multi-factor authentication

Configure AM for authentication

Authentication nodes and trees

Authentication levels for trees

Account lockout for trees

Specify IDM identity resources in trees

Configure authentication trees

Create an authentication tree

Configure authentication webhooks

To Create an Authentication Webhook

Customize authentication trees

Create post-authentication hooks for trees

The core class of an authentication tree hook

Configure success and failure redirection URLs

Configure the validation service

Configure realm authentication properties

Authenticate with a browser

Specify the realm in the URL

Authentication parameters

Example UI login URLs

Authenticate using REST

Log in to AM using REST

Using UTF-8 usernames

Authenticate to specific authentication services

Return callback information to AM

Using the session token after authentication

Log out of AM using REST

Invalidate all sessions for a given user

Single sign-on

Realms and SSO

HTTP cookies

Implementing CDSSO

Troubleshooting SSO

Social authentication

Configure social identity providers

Add identity providers

Configure basic social registration trees

Set up a basic social registration tree

Configure social registration with account claiming

Client configuration reference

Suspended authentication

Configure suspended authentication

MFA: Web authentication (WebAuthn)

Create trees for web authentication (WebAuthn)

Configure usernameless authentication with ForgeRock Go

Register and authenticate with ForgeRock Go

MFA: Push authentication

Create trees for push authentication and registration

Create a tree for push authentication

Create a tree for passwordless authentication

Test push authentication

Receive push notifications

Approve requests

Deny requests

Register

Limitations of passwordless push authentication

MFA: Open AuTHentication (OATH)

One-time password authentication

Create a tree for one-time password authentication

Authenticate using a one-time password

Manage devices for MFA

The ForgeRock Authenticator app

Register the ForgeRock Authenticator for multi-factor authentication

Recover after replacing a lost device

Register a new device after losing a registered device

Recover after a device becomes out of sync

Reset registered devices using REST

Reset OATH devices

Reset push devices

Reference

Core authentication attributes

Supported callbacks

Interactive callbacks