PingOne Advanced Identity Cloud

Authentication and SSO

These topics cover concepts, implementation, and customization of the authentication and single sign-on (SSO) features of PingOne Advanced Identity Cloud.

Configure PingOne Advanced Identity Cloud for authentication

Learn about PingOne Advanced Identity Cloud’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.

Name changes for ForgeRock products

Product names changed when ForgeRock became part of Ping Identity. Learn more in New name for ForgeRock Identity Cloud.

Introduction to authentication

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

As part of an access management strategy, authentication is tightly coupled with authorization; usually, not only is it 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 (as it’s tied to their shipping and email addresses and payment information). You also want to ensure that they can only access their own information.

You can deploy a web agent on the web server hosting the online shop. The agent redirects the user’s request to an PingOne Advanced Identity Cloud login page, where the user enters their credentials, such as username and password. PingOne Advanced Identity Cloud determines who the user is, and whether the user has the right to access the protected page. PingOne Advanced Identity Cloud 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 PingOne Advanced Identity Cloud to access the page.

In the same way, you can also use PingOne Advanced Identity Cloud 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.

PingOne Advanced Identity Cloud uses authentication nodes and journeys to implement authentication.

PingOne Advanced Identity Cloud creates an authentication session to track the user’s progress through an authentication journey. After the user has authenticated, PingOne Advanced Identity Cloud creates a session to manage the user’s access to resources. To learn more about sessions, refer to 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 PingOne Advanced Identity Cloud.

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 PingOne Advanced Identity Cloud multi-factor authentication (MFA). Devices are most commonly mobile phones with authenticator applications 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 PingOne Advanced Identity Cloud:

  1. In the Advanced Identity Cloud admin UI, configure an authentication journey to capture the user’s username and password and to create one-time passwords.

  2. An end user authenticates to PingOne Advanced Identity Cloud using that authentication journey.

  3. PingOne Advanced Identity Cloud prompts the user to enter the username and password—​the first factor in multi-factor authentication.

  4. If the user ID and password were correct, PingOne Advanced Identity Cloud sends the user an email with a one-time password.

  5. The user provides the one-time password to PingOne Advanced Identity Cloud to successfully complete authentication—​the second factor in multi-factor authentication.

PingOne Advanced Identity Cloud supports the following multi-factor authentication protocols:

Configure PingOne Advanced Identity Cloud for authentication

PingOne Advanced Identity Cloud uses authentication nodes and journeys to authenticate users and provides a large variety of authentication nodes. Based on your authentication requirements, you connect these nodes to create a journey that guides users through the authentication process.

Authentication journeys are extremely flexible, and can be adapted to suit your specific deployment. Although the number of choices can seem daunting, once you understand the basic process, you will be able to configure multiple journeys to protect access to most applications in your organization.

Self-managed AM deployments can also use a legacy authentication mechanism, with modules and chains. Modules and chains are not supported in PingOne Advanced Identity Cloud, even though it might appear that you can configure them in the UI. All authentication to Advanced Identity Cloud must use an authentication journey.

Authentication is configured per realm. 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 journeys

Configure the success and failure URLs for the realm

By default, PingOne Advanced Identity Cloud redirects users to the UI after successful authentication. No failure URL is defined by default.

Success and failure redirection URLs

Authentication nodes and journeys

Authentication journeys 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 journeys 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. These outcomes let you create complex yet user-friendly authentication experiences by linking nodes together, creating loops and sections for different authentication scenarios, and nesting nodes within a journey.

Create multiple paths for authentication by linking nodes within journeys.
Figure 1. Example authentication journey

For greater control of the authentication process, you can assign authentication levels to sections of a journey, with higher levels typically allowing access to more restricted resources.

Authentication levels

When a user authenticates successfully, PingOne Advanced Identity Cloud creates a session which allows PingOne Advanced Identity Cloud 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, a simple username and password might be assigned a low authentication level, while multi-factor authentication with push and WebAuthn might be assigned a high level.

Authorization policies might 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, PingOne Advanced Identity Cloud denies access to the resource and returns an advice indicating that the user must reauthenticate at the required level to access the resource.

The policy enforcement point, such as an agent, sends the user back to PingOne Advanced Identity Cloud for a session upgrade.

PingOne Advanced Identity Cloud provides the following nodes to manage authentication levels:

Position these nodes to alter the authentication level, depending on the route taken through the authentication flow.

Account lockout

Use account lockout to limit the number of times an end-user can attempt to authenticate with invalid credentials before rendering their account inactive. Limiting the number of attempts helps to prevent password-guessing and brute-force attacks.

Authentication journeys have built-in support for account lockout. They also provide nodes for checking and changing the status of a user.

For more information refer to Account lockout.

Configure authentication journeys

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

Task Resources

Design your user authentication journey

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

It’s easy to create a massive journey that’s difficult to understand, read, and maintain in the UI. To avoid this, PingOne Advanced Identity Cloud lets you nest journeys within journeys.

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 PingOne Advanced Identity Cloud.

Configure your authentication journeys

Use the journey editor to put together your journeys quickly.

Configure webhooks, if required

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

Specify the identity object type for a journey

Each authentication journey assumes a specific identity object type. The nodes in the journey use this object type to verify the identity, for example, users, roles, or organizations. The default journeys provided with Advanced Identity Cloud assume the identity object using the journey to authenticate is a realm-name user, for example Alpha realm - Users or Bravo realm - Users.

When you create a new journey, you select the object type in the Identity Object list.

To change the object type of an existing journey:

  1. In the Advanced Identity Cloud admin UI select Journeys > Journey name > Edit.

  2. On the journey page, click the ellipses () at the top right of the page, then click Edit details.

  3. Select a new object type in the Identity Object list.

Enable and disable an authentication journey

Custom authentication journeys are enabled by default, when they are saved. For security purposes, you can disable custom authentication journeys during development and testing, to prevent accidentally allowing access through these journeys. Rather than having unused authentication journeys enabled, you should disable the default authentication journeys until you need them.

When a user attempts to authenticate through a disabled journey, PingOne Advanced Identity Cloud returns a Tree does not exist error.

To enable or disable an authentication journey, set the enabled flag in the journey configuration:

To enable or disable an authentication journey, send a PUT request to update the journey’s configuration. Specify the journey ID, the nodes in the journey, and set the enabled flag:

Example 
$ curl \
--header "Content-Type: application/json" \
--header "<session-cookie-name>: AQIC5..." \
--header 'accept-api-version: protocol=2.1,resource=1.0' \
--header "If-Match: *" \
--request PUT \
--data '
  {
  "entryNodeId": "c11e9cf8-ef48-4740-876f-6300e2f46aef",
  "nodes": {
    "c11e9cf8-ef48-4740-876f-6300e2f46aef": {
      "displayName": "Page Node",
      "nodeType": "PageNode",
      "x": 147,
      "y": 25,
      "connections": {
        "outcome": "15839e1c-5085-4f58-bc94-c4cc848a0ae8"
      }
    },
    "15839e1c-5085-4f58-bc94-c4cc848a0ae8": {
      "displayName": "Data Store Decision",
      "nodeType": "DataStoreDecisionNode",
      "x": 349,
      "y": 25,
      "connections": {
        "true": "70e691a5-1e33-4ac3-a356-e7b6d60d92e0",
        "false": "e301438c-0bd0-429c-ab0c-66126501069a"
      }
    }
  },
  "enabled": false
}' \
'https://https://<tenant-env-fqdn>/am/json/realms/root/realms/alpha/realm-config/authentication/authenticationtrees/trees/myAuthTree'
{
  "_id": "myAuthTree",
  "_rev": "2070284866",
  "uiConfig": {},
  "entryNodeId": "c11e9cf8-ef48-4740-876f-6300e2f46aef",
  "nodes": {
    "c11e9cf8-ef48-4740-876f-6300e2f46aef": {
      "displayName": "Page Node",
      "nodeType": "PageNode",
      "x": 147,
      "y": 25,
      "connections": {
        "outcome": "15839e1c-5085-4f58-bc94-c4cc848a0ae8"
      }
    },
    "15839e1c-5085-4f58-bc94-c4cc848a0ae8": {
      "displayName": "Data Store Decision",
      "nodeType": "DataStoreDecisionNode",
      "x": 349,
      "y": 25,
      "connections": {
        "true": "70e691a5-1e33-4ac3-a356-e7b6d60d92e0",
        "false": "e301438c-0bd0-429c-ab0c-66126501069a"
      }
    }
  },
  "staticNodes": {
    "startNode": {
      "x": 50,
      "y": 25
    },
    "70e691a5-1e33-4ac3-a356-e7b6d60d92e0": {
      "x": 570,
      "y": 30
    },
    "e301438c-0bd0-429c-ab0c-66126501069a": {
      "x": 573,
      "y": 107
    }
  },
  "enabled": false
}

Disable direct access through a child journey

A child journey lets you nest authentication logic. There is no limit to the depth of nesting.

You configure a child journey like any other journey and call it from a parent journey using an Inner Tree Evaluator node.

You may want to hide child journeys as complete services. In other words, you may want to prevent users from authenticating directly through a child journey, either for security reasons or simply because the child journey is insufficient as a complete authentication service.

To prevent a journey from being used outside of its parent journey, send a PUT request to update the journey configuration, including the journey ID and all the nodes in the journey and set the innerTreeOnly property to true:

Example 
$ curl \
--header "Content-Type: application/json" \
--header "<session-cookie-name>: AQIC5..." \
--header 'accept-api-version: protocol=2.1,resource=1.0' \
--header "If-Match: *" \
--request PUT \
--data '
  {
  "entryNodeId": "c11e9cf8-ef48-4740-876f-6300e2f46aef",
  "nodes": {
    "c11e9cf8-ef48-4740-876f-6300e2f46aef": {
      "displayName": "Page Node",
      "nodeType": "PageNode",
      "x": 147,
      "y": 25,
      "connections": {
        "outcome": "15839e1c-5085-4f58-bc94-c4cc848a0ae8"
      }
    },
    "15839e1c-5085-4f58-bc94-c4cc848a0ae8": {
      "displayName": "Data Store Decision",
      "nodeType": "DataStoreDecisionNode",
      "x": 349,
      "y": 25,
      "connections": {
        "true": "70e691a5-1e33-4ac3-a356-e7b6d60d92e0",
        "false": "e301438c-0bd0-429c-ab0c-66126501069a"
      }
    }
  },
  "innerTreeOnly": true
}' \
'https://https://<tenant-env-fqdn>/am/json/realms/root/realms/alpha/realm-config/authentication/authenticationtrees/trees/myAuthTree"
{
  "_id": "myAuthTree",
  "_rev": "1081620278",
  "uiConfig": {},
  "entryNodeId": "c11e9cf8-ef48-4740-876f-6300e2f46aef",
  "innerTreeOnly": true,
  "nodes": {
    "c11e9cf8-ef48-4740-876f-6300e2f46aef": {
      "displayName": "Page Node",
      "nodeType": "PageNode",
      "x": 147,
      "y": 25,
      "connections": {
        "outcome": "15839e1c-5085-4f58-bc94-c4cc848a0ae8"
      }
    },
    "15839e1c-5085-4f58-bc94-c4cc848a0ae8": {
      "displayName": "Data Store Decision",
      "nodeType": "DataStoreDecisionNode",
      "x": 349,
      "y": 25,
      "connections": {
        "true": "70e691a5-1e33-4ac3-a356-e7b6d60d92e0",
        "false": "e301438c-0bd0-429c-ab0c-66126501069a"
      }
    }
  },
  "staticNodes": {
    "startNode": {
      "x": 50,
      "y": 25
    },
    "70e691a5-1e33-4ac3-a356-e7b6d60d92e0": {
      "x": 570,
      "y": 30
    },
    "e301438c-0bd0-429c-ab0c-66126501069a": {
      "x": 573,
      "y": 107
    }
  },
  "enabled": true
}

Configure authentication webhooks

Webhooks 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 journeys, by the Register Logout Webhook node.

  1. Under Native Consoles > Access Management, go to Realms > Realm Name > Authentication > Webhooks.

  2. Select Create Webhook, specify a Webhook Name, and select Create.

    The webhook configuration screen is displayed:

    Creating a new authentication webhook.

  3. Complete the fields as required:

    Url

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

    Body

    The body of the HTTP POST. To send different data formats, set 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

    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 Add (➕).

    To remove a header, click Delete (✖).

    The fields in a webhook support variables for retrieving values from the user’s session after successfully authenticating. Specify a variable in the following format: ${variable_name}.

    To access the type of webhook event, use the WebhookEventType parameter key to return one of the following possible values:

    • LOGOUT

    • UPGRADE

    • DESTROY

    • MAX_TIMEOUT

    • IDLE_TIMEOUT

    For example, to retrieve the event type as a query parameter: &event=${WebhookEventType}

    You can use a variable to access custom properties added to the session with the Set Session Properties node as well as the following default session properties:

    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 PingOne Advanced Identity Cloud access audit logs.

    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 journey 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, refer to Session upgrade with MFA.

    CharSet

    UTF-8

    The character set for the session, set to UTF-8.

    clientType

    genericHTML

    The type of client, set to genericHTML.

    FullLoginURL

    https://example.forgeblocks.com/platform/?realm=alpha

    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 PingOne Advanced Identity Cloud 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 journey 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. Refer to 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:

    Example authentication webhook.

    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.

Success and failure redirection URLs

PingOne Advanced Identity Cloud determines the redirection URL based on authentication success or failure.

You can configure success and failure URLs in a number of places in PingOne Advanced Identity Cloud. For each authentication outcome, the user is redirected to the URL with the highest precedence, which is determined by where it is defined in PingOne Advanced Identity Cloud.

Success URL precedence

When a user authenticates successfully, PingOne Advanced Identity Cloud evaluates the redirection URL according to the following order of precedence:

  1. The URL set in the authentication journey.

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

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

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

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

    Under Native Consoles > Access Management, go 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 takes precedence over a regular URL in the user’s profile.

  4. The URL set in the Default Success Login URL attribute in the realm.

    Under Native Consoles > Access Management, go to Realm Name > Authentication > Settings > Post Authentication Processing. In Default Success Login 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 takes precedence over a Default Success Login URL in the realm.

Failure URL precedence

When a user fails to authenticate, PingOne Advanced Identity Cloud evaluates the redirection URL according to the following order of precedence:

  1. The URL set in the authentication journey.

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

  2. The URL set in the gotoOnFail parameter. For example:

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

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

    Under Native Consoles > Access Management, go 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.

  4. The URL set in the Default Failure Login URL attribute in the realm.

    Under Native Consoles > Access Management, go to Realm Name > Authentication > Settings > Post Authentication Processing. In Default Failure Login 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 Default Failure Login URL in the realm.

Configure trusted URLs

Redirection URLs can be relative to PingOne Advanced Identity Cloud’s URL, or absolute.

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

To configure PingOne Advanced Identity Cloud to trust other absolute URLs, add them to the validation service. If they are not added, PingOne Advanced Identity Cloud will redirect to the user profile or to the administrator console on log in, and to the default logout page in the UI on log out.

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

Consider these example URLS for a tenant environment URL, https://openam-example-mytenant-usw1.id.forgerock.io:

URL Add to the validation service?

http://openam-example-mytenant-usw1.id.forgerock.io

Yes, the scheme is different.

https://openam-example-mytenant-usw1.id.forgerock.io:8080/login/?realm=/#/

Yes, the port is different.

/login/?authIndexType=service&authIndexValue=mytreename#/

No, the paths relative to the PingOne Advanced Identity Cloud URL are trusted.

http://mypage.example.com:443/app/logout.jsp

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

Add a URL to the validation service

  1. Under Native Consoles > Access Management, go to Realms > Realm Name > Services.

  2. If the Validation Service is not in the list of services, configure a new service:

    1. Click Add a Service.

    2. From the Choose a service type drop-down list, select Validation Service.

  3. In the Valid goto URL Resources field, enter one or more valid URL patterns to allow.

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

    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 https://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, PingOne Advanced Identity Cloud 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, PingOne Advanced Identity Cloud 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/.

    For more information on pattern matching and wildcard rules, refer to Specify resource patterns with wildcards.

  4. Click Create to save your settings.

Validate a goto URL

To validate a goto URL over REST, use the /json/realms/root/realms/Realm Name/users?_action=validateGoto endpoint. For example:

$ 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":"https://www.example.com/"}' \
'https://<tenant-env-fqdn>/am/json/realms/root/realms/alpha/users?_action=validateGoto'
{
    "successURL":"https://www.example.com/"
}

If the URL is valid, the endpoint returns the specified URL as the successURL response parameter.

A goto URL is considered valid if one of the following is true:

  • The URL is configured in the validation service

  • The URL is relative

  • The URL is encoded

Encoded URLs are treated as relative URLs for the purposes of validation. To be treated as an absolute URL, the URL must not be encoded.

If the specified URL is invalid, the endpoint returns the default success URL.

Note that a valid session is optional; you can still call the validateGoto endpoint with an expired session.

Realm authentication configuration

Advanced Identity Cloud users always authenticate to a realm. Each realm has a set of authentication settings that apply to all authentication performed to that realm. The settings are referred to as core authentication attributes.

To configure the default core authentication attributes for a realm, go to Native Consoles > Access Management > Realms > Realm Name > Authentication > Settings.

The core authentication attributes page is divided into seven tabs.
Figure 2. The core authentication attributes page

Edit the attributes on this page to configure authentication behavior, such as:

  • Account lockout settings for users authenticating to the realm

  • The default authentication locale

  • The duration of an authentication session

For more information, refer to Core authentication attributes.

Authenticate with a browser

When you authenticate to Advanced Identity Cloud using a browser, you can specify the realm and the authentication parameters in the URL, to customize the user’s authentication experience.

Specify the realm in the URL

Specify the realm as the value of the realm parameter in the URL. Preface the realm name with a forward slash (/); for example:

https://<tenant-env-fqdn>/am/login/?realm=/alpha

Authentication parameters

PingOne Advanced Identity Cloud accepts the following parameters in the URL query string.

arg=newsession

Request that PingOne Advanced Identity Cloud end the user’s current session and start a new session.

ForceAuth

If ForceAuth=true, request that PingOne Advanced Identity Cloud force the user to authenticate even if they already have a valid session.

On successful authentication, PingOne Advanced Identity Cloud 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 PingOne Advanced Identity Cloud redirect the user to the specified location. Values must be URL-encoded.

For details, refer to Success and failure redirection URLs.

gotoOnFail

On authentication failure, request that PingOne Advanced Identity Cloud redirect the user to the specified location. Values must be URL-encoded.

For details, refer to Success and failure redirection URLs.

locale

Request that PingOne Advanced Identity Cloud display the user interface in the specified, supported locale. The locale can also be set in the user’s profile, in the HTTP header from their browser, or configured in PingOne Advanced Identity Cloud.

realm

Request that PingOne Advanced Identity Cloud authenticate the user to the specified realm.

resource

Set this parameter to true to request resource-based authentication.

service

Request that PingOne Advanced Identity Cloud authenticate the user with the specified authentication journey.

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 1. Example UI Login URLs
Description Example URL

Log in to the alpha realm, requesting that PingOne Advanced Identity Cloud display the user interface in German.

https://<tenant-env-fqdn>/am/XUI/?realm=/alpha&locale=de#login

Log in to the alpha realm using the myJourney authentication journey, requesting that PingOne Advanced Identity Cloud display the user interface in German.

https://<tenant-env-fqdn>/am/XUI/?realm=/alpha&locale=de&service=myJourney#login

Authenticate using REST

PingOne Advanced Identity Cloud 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

Authenticate to PingOne Advanced Identity Cloud

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

Authenticate using REST

Use the session token

PingOne Advanced Identity Cloud returns a session token when you authenticate to a realm. Use this token in subsequent calls to PingOne Advanced Identity Cloud. For example, when using REST calls to create, modify, or delete configuration objects.

Session tokens after authentication

Log out of PingOne Advanced Identity Cloud

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

Log out using REST

Invalidate sessions

Invalidate specific sessions, or invalidate all sessions for a user to ensure they are logged out of PingOne Advanced Identity Cloud.

Invalidate sessions

Authenticate using REST

To authenticate using REST, send an HTTP POST request to the json/authenticate endpoint. You must specify the realm hierarchy. 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.

By default, you authenticate using the default authentication service configured for the realm. To override the default, specify authentication services and other options in the REST request.

PingOne Advanced Identity Cloud supports simple authentication methods, such as providing a username and password, and complex authentication journeys that might involve nested journey evaluations and multi-factor authentication.

For authentication journeys where providing a username and password is sufficient, you can log in by providing these credentials in headers. The following command logs in user bjensen with password Secret12!:

$ curl \
--request POST \
--header 'Content-Type: application/json' \
--header 'X-OpenAM-Username: bjensen' \
--header 'X-OpenAM-Password: Secret12!' \
--header 'Accept-API-Version: resource=2.0, protocol=1.0' \
'https://<tenant-env-fqdn>/am/json/realms/root/realms/alpha/authenticate'
{
    "tokenId":"AQIC5wM...TU3OQ*",
    "successUrl": "/enduser/?realm=/alpha",
    "realm":"/alpha"
}

This zero page login mechanism works only for username/password authentication.

Note that the POST body is empty. If you submit a POST body, PingOne Advanced Identity Cloud interprets the body as a continuation of an existing authentication attempt that uses a supported callback mechanism. Callback mechanisms support complex authentication journeys, such as those where the user must be redirected to a third party or interact with a device as part of multi-factor authentication.

After successful authentication, PingOne Advanced Identity Cloud returns a tokenId that applications can present as a cookie value for other operations that require authentication. The tokenId is known as the session token. For information about how applications can use session tokens, refer to Session tokens after authentication.

If HttpOnly cookies are enabled, and a client makes a call to the /json/authenticate endpoint with a valid SSO token, PingOne Advanced Identity Cloud returns the tokenId field empty. For example:

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

To authenticate a user without providing them with a session, use the noSession parameter. For details, refer to Authenticate endpoint parameters.

UTF-8 usernames and passwords

To use UTF-8 usernames and passwords in calls to the /json/authenticate endpoint, base64-encode the string, 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 Åström, follow these steps:

  1. Encode the string in base64 format: w4VzdHLDtm0=.

  2. Wrap the base64-encoded string, as per RFC 2047: =?UTF-8?B?w4VzdHLDtm0=?=.

  3. 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?w4VzdHLDtm0=?=' \
--header 'X-OpenAM-Password: Secret12!' \
--header 'Accept-API-Version: resource=2.0, protocol=1.0' \
'https://<tenant-env-fqdn>/am/json/realms/root/realms/alpha/authenticate'
{
  "tokenId": "DDZUA0Ellb4bOt...AIwMQ..*",
  "successUrl": "/enduser/?realm=/alpha",
  "realm": "/alpha"
}

Authenticate to specific authentication services

You can provide PingOne Advanced Identity Cloud with additional information about how a user is authenticating. For example, you can specify a particular authentication journey, or request a list of the authentication services that would satisfy an authentication condition.

The following example specifies the Login journey by using the authIndexType and authIndexValue parameters:

$ curl \
--request POST \
--header 'X-OpenAM-Username: bjensen' \
--header 'X-OpenAM-Password: Secret12!' \
--header 'Accept-API-Version: resource=2.0, protocol=1.0' \
'https://<tenant-env-fqdn>/am/json/realms/root/realms/alpha/authenticate?authIndexType=service&authIndexValue=Login'

You can replace the Login journey with any other journey configured in the realm.

For details about using the authIndexType parameter to authenticate to specific services, refer to Authenticate endpoint parameters.

Return callback information

The /json/authenticate endpoint supports callback mechanisms to perform complex authentication journeys. When PingOne Advanced Identity Cloud needs to return or request information, it returns a JSON object with the authentication step, the authentication identifier, and the related callbacks.

The following callback types are available:

Read-only callbacks

Read-only callbacks provide information to the user, such as text messages or the period of time a user must wait before continuing their authentication journey.

Interactive callbacks

Interactive callbacks request information from the user; for example, their username and password, or a request that they select between different configured options.

Backchannel callbacks

Backchannel callbacks let PingOne Advanced Identity Cloud access additional information from the user’s request; for example, a specific header or certificate.

Read-only and interactive callbacks have an array of output elements that can be displayed to the end user. The JSON returned in an interactive callback includes an array of input elements that must be completed and returned to PingOne Advanced Identity Cloud. 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, PingOne Advanced Identity Cloud may return several callbacks sequentially. Each must be completed and returned to PingOne Advanced Identity Cloud until authentication is successful.

The following example shows a request for authentication, and PingOne Advanced Identity Cloud’s response with the NameCallback and PasswordCallback:

$ curl \
--request POST \
--header "Content-Type: application/json" \
--header "Accept-API-Version: resource=2.0, protocol=1.0" \
'https://<tenant-env-fqdn>/am/json/realms/root/realms/alpha/authenticate'
{
  "authId": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJvdGsiOiJ...", (1)
  "callbacks": [
    {
      "type": "NameCallback", (2)
      "output": [ (3)
        {
          "name": "prompt",
          "value": " User Name: "
        }
      ],
      "input": [ (4)
        {
          "name": "IDToken1",
          "value": ""
        }
      ]
    },
    {
      "type": "PasswordCallback",
      "output": [
        {
          "name": "prompt",
          "value": " Password: "
        }
      ],
      "input": [
        {
          "name": "IDToken2",
          "value": ""
        }
      ]
    }
  ]
}
1 The JWT that uniquely identifies the authentication context to PingOne Advanced Identity Cloud.
2 The type of callback. It must be listed under Supported callbacks.
3 The information PingOne Advanced Identity Cloud offers about this callback. Usually, this information would be displayed to the user in the UI.
4 The information PingOne Advanced Identity Cloud is requesting. The user must complete the "value": "" field 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, returning the username (bjensen) and the password (Secret12!):

$ curl \
--request POST \
--header "Content-Type: application/json" \
--header "Accept-API-Version: resource=2.0, protocol=1.0" \
--data '{
  "authId":""eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJvdGsiOiJ...",
  "callbacks": [
    {
      "type": "NameCallback",
      "output": [
        {
          "name": "prompt",
          "value": "User Name"
        }
      ],
      "input": [
        {
          "name": "IDToken1",
          "value": "bjensen"
        }
      ],
      "_id": 0
    },
    {
      "type": "PasswordCallback",
      "output": [
        {
          "name": "prompt",
          "value": "Password"
        }
      ],
      "input": [
        {
          "name": "IDToken2",
          "value": "Secret12!"
        }
      ],
      "_id": 1
    }
  ],
}' \
'https://<tenant-env-fqdn>/am/json/realms/root/realms/alpha/authenticate'
{
  "tokenId": "lWY23F4fuC7cu4Fq4GQa5u6drlQ...*",
  "successUrl": "/enduser/?realm=/alpha",
  "realm": "/alpha"
}

In complex authentication journeys, PingOne Advanced Identity Cloud may send several callbacks sequentially. Each must be completed and returned to PingOne Advanced Identity Cloud until authentication is successful.

For details about the callbacks PingOne Advanced Identity Cloud can return, refer to Supported callbacks.

Session tokens after authentication

After successful authentication, PingOne Advanced Identity Cloud returns a tokenId that applications can present as a cookie value for other operations that require authentication. The tokenId contains a session token—​a representation of the exchange of information and credentials between PingOne Advanced Identity Cloud and the user or identity.

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

The following is a common scenario when accessing PingOne Advanced Identity Cloud by using REST API calls:

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

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

    $ curl \
--request POST \
--header 'Content-Type: application/json' \
--header 'X-OpenAM-Username: bjensen' \
--header 'X-OpenAM-Password: Secret12!' \
--header 'Accept-API-Version: resource=2.0, protocol=1.0' \
'https://<tenant-env-fqdn>/am/json/realms/root/realms/alpha/authenticate'
{
    "tokenId":"AQIC5wM...TU3OQ*",
    "successUrl": "/enduser/?realm=/alpha",
    "realm":"/alpha"
}

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

  2. Call one or more additional REST APIs on behalf of the authenticated user.

    Each REST API call passes the user’s tokenID back to PingOne Advanced Identity Cloud 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 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, refer to How do I view the tenant session cookie name?

    Once a user has authenticated, you do not need 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 PingOne Advanced Identity Cloud functionality using the REST API.

  3. Use the REST API to log the user out of PingOne Advanced Identity Cloud, as described in Log out using REST.

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

Log out using REST

Authenticated users can log out with the token cookie value and an HTTP POST request 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-env-fqdn>/am/json/realms/root/realms/alpha/sessions/?_action=logout'
{
    "result":"Successfully logged out"
}

Single sign-on

Single sign-on (SSO) lets users who have authenticated to Advanced Identity Cloud access multiple independent services from a single login session by storing user sessions as HTTP cookies.

Cross-domain single sign-on (CDSSO) provides SSO inside the same organization within a single domain or across domains. For example, CDSSO lets servers in the DNS domain .internal.net provide authentication and authorization to web and Java agents from the .internal.net domain and other DNS domains, such as .example.net.

Because 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 PingOne Advanced Identity Cloud’s federation capabilities, such as OAuth 2.0 or SAML 2.0.

  • Web agents and Java agents both support CDSSO.

    PingOne Advanced Identity Cloud also supports CDSSO with PingGateway version 6 or later. For details, refer to Single sign-on and cross-domain single sign-on in the PingGateway 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:

Web and Java agents CDSSO flow
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. Logging in to a new realm means logging out of the current realm.

When a user interactively changes realms, PingOne Advanced Identity Cloud 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, PingOne Advanced Identity Cloud first logs the user out of the current realm 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

Also known as the cookie domain, this is the domain with which the cookie is associated. The default value is the current domain. To work with multiple subdomains, set the Domain to a URL such as Domain=server.example.net.

Path

The directory in the URL to which the cookie applies. If Path=/openam, the cookie applies to the /openam subdirectory of the URL, and lower level directories, including openam/XUI.

Expires

You can limit the lifetime of a cookie with an Expires property set to a time based on UTC (GMT).

Do not take a shortcut with a top-level domain. Web browser clients are designed to ignore cookies set to top-level domains including com, net, and co.uk. In addition, a cookie with a value such as Domain=app1.example.net will not work for similar subdomains, such as `app2.example.net.

Implement CDSSO

Cross-domain single sign-on (CDSSO) provides SSO capabilities for PingOne Advanced Identity Cloud and web or Java agents within a single domain or across domains in the same organization.

CDSSO is the only mode of operation for web and Java agents, so no additional configuration is required to make it work.

PingGateway also supports CDSSO with PingOne Advanced Identity Cloud. For details, refer to the PingGateway 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 PingOne Advanced Identity Cloud, 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.

Social authentication

PingOne Advanced Identity Cloud supports delegated authentication through third-party identity providers, such as Facebook and Google. This lets users register and log in to PingOne Advanced Identity Cloud using an account they have through another trusted service.

To configure social authentication, refer to Social authentication.

Suspended authentication

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

Any input provided during authentication is saved when the authentication journey is suspended and restored when the authentication journey is resumed. This lets the authentication journey continue if the user closes their browser, uses a different browser, or uses a different device.

When you suspend an authentication journey, you give the user a URL they must visit to resume their authentication. The 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 journey lets a user authenticate if they have forgotten their username:

The example

After obtaining the user’s email address in the Attribute Collector node, the journey attempts to identify the user. The journey then attempts to email the user and suspends itself.

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

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

Configure suspended authentication timeouts

You can configure the length of time an authentication session can last so that resources can be freed up if authentication is not completed. You can also configure the length of time that a journey can be suspended.

Set these values 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 as or less than the maximum duration of the journey.

To configure these timeouts, under Native Consoles > Access Management, go to Authentication > Settings > Trees. Set the Max duration and Suspended authentication duration properties. For information about these properties, refer to Trees.

Multi-factor authentication (MFA)

MFA: Authenticate using a device with WebAuthn

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

The user’s browser communicates with the authenticator device. PingOne Advanced Identity Cloud can request that the browser activates authenticator devices with specified criteria. Example criteria are that the authenticator device must be built-in, not a USB device that the user can eject, or that the device must verify the user’s identity, not just the user’s presence.

To use WebAuthn with PingOne Advanced Identity Cloud, users must first register their authenticators. If recovery codes are enabled, users should copy their codes on successful registration.

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

When authenticating with WebAuthn, the authenticator device locks data with its stored private key and sends it to PingOne Advanced Identity Cloud. PingOne Advanced Identity Cloud verifies the data using the public key stored in the user’s profile. If the data verification succeeds and passes any attestation checks, PingOne Advanced Identity Cloud considers the authentication successful.

The user must connect over HTTPS to use WebAuthn.

PingOne Advanced Identity Cloud supports WebAuthn for the following user agents on the specified platforms:

Table 2. Browsers and platforms supported for WebAuthn
Browser(1) Platform

Google Chrome

Desktop

Android

Safari

Desktop

iOS

Microsoft Edge

Desktop

Mozilla Firefox

Desktop

(1) Latest stable versions are supported.

Create journeys for WebAuthn

The example journey that follows registers the user’s device if necessary, and authenticates the user with the device. If the user has already registered their device, they only need to enter their username, and then perform the authorization gesture with their registered device to complete authentication.

If the user does not have a registered device, they must provide both their username and their password. The Data Store Decision node confirms their identity before allowing them to register their device. The user then authenticates with the new device to complete authentication.

The journey created here does not include user-friendly features, such as letting the user retry their password if they mistype it.

Configure the WebAuthn Profile Encryption service

Configure the WebAuthn Profile Encryption service for the realm where you create the journey.

This service configures how PingOne Advanced Identity Cloud stores registered device metadata.

  1. Under Native Consoles > Access Management > Realms > Realm Name, click Services > Add a Service.

  2. Select WebAuthn Profile Encryption Service in the service type drop-down list, and create the new service configuration.

  3. Accept the default configuration unless you must encrypt the device metadata in user profiles:

    Profile Storage Attribute

    webauthnDeviceProfiles (default)

    Device Profile Encryption Scheme

    If you choose an encryption scheme, also edit the settings to access the keys. For details, read Use ESVs for signing and encryption keys.

    Default: No encryption of device settings.

    You can find detailed information about the available properties in WebAuthn Profile Encryption Service.

Create the WebAuthn journey

  1. Configure the WebAuthn Profile Encryption service for the realm if you have not already done so.

  2. In the Advanced Identity Cloud admin UI, start a custom journey for WebAuthn.

    Learn more in Custom journeys.

  3. In the Advanced Identity Cloud admin UI, add the following nodes to your journey:

  4. Connect the nodes as demonstrated in the following figure:

    A journey for WebAuthn authentication.

  5. On the WebAuthn Authentication node, select Allow recovery codes.

  6. On the WebAuthn Registration node, select Generate recovery codes.

  7. Save your changes.

Test the WebAuthn journey

  1. Register a test user account unless you have already done so.

  2. In an incognito browser window, browse to the WebAuthn journey. The URL looks something like:

    https://<tenant-env-fqdn>/am/XUI/?realm=alpha&authIndexType=service&authIndexValue=myWebAuthnJourney

    A login screen prompts for the username.

  3. Enter the username for the test user account.

  4. If the user does not have a registered device:

    1. Enter the test user’s password when prompted.

    2. Register a WebAuthn authenticator by performing an authorization gesture.

      For example, press the button on a connected YubiKey or scan your fingerprint.

      WebAuthn registration waiting for an authenticator

      The browser may present a consent pop-up to allow access to the available authenticators.

      When you grant consent, the browser activates the relevant authenticators, ready for registration.

      If the device registration is successful, the journey returns to the WebAuthn Authentication node.

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

    The UI displays the user profile page.

  6. Browse to Edit Your Profile > 2-Step Verification > Change.

    The UI displays a list of the registered devices that you can rename or delete.

    The default name for a new WebAuthn 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 need 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 journey to associate a device that supports resident keys with a user. The registration journey is similar to that described in Create journeys for WebAuthn.

Create a second journey that lets users authenticate to PingOne Advanced Identity Cloud without entering their username or password, by using ForgeRock Go.

The journeys created here do not include user-friendly features, such as allowing retries or redirecting for further help on failures.

Create the ForgeRock Go registration journey

  1. Configure the WebAuthn Profile Encryption service for the realm if you have not already done so.

  2. In the Advanced Identity Cloud admin UI, start a custom journey for ForgeRock Go registration.

    Learn more in Custom journeys.

  3. In the Advanced Identity Cloud admin UI, add the following nodes to your journey:

    • Identity Store Decision node

    • Page node

    • Platform Username node

    • Platform Password node

    • WebAuthn Registration node

    • (Optional) Scripted Decision node

      When configured for ForgeRock Go, by default the WebAuthn Registration node stores the journey’s shared state variable username on the device. During authentication, this value later identifies the user.

      Use a Scripted Decision node to customize the display name or string to be saved in the shared state.

      Script to set the display name

      • Next-generation

      • Legacy

      var user = nodeState.get('username');
var identity = idRepository.getIdentity(user);

var displayName = '';

var givenName = identity.getAttributeValues('givenName')[0];
var surname = identity.getAttributeValues('sn')[0];
var email = identity.getAttributeValues('mail')[0];

if (givenName) {
  displayName += givenName;
}

if (surname) {
  displayName += ' ' + surname;
}

if (email) {
  displayName += ' (' + email + ')';
}

if (displayName) {
  nodeState.putShared('displayName', displayName);
} else {
  nodeState.putShared('displayName', user);
}
action.goTo("true");
      var fr = JavaImporter(org.forgerock.openam.auth.node.api.Action);

var user = nodeState.get('username').asString();
var displayName = '';

var givenName = idRepository.getAttribute(user, 'givenName');
var surname = idRepository.getAttribute(user, 'sn');
var email = idRepository.getAttribute(user, 'mail');

if (givenName) {
  displayName += givenName.toArray()[0];
}

if (surname) {
  displayName += ' ' + surname.toArray()[0];
}

if (email) {
  displayName += ' (' + email.toArray()[0] + ')';
}

if (displayName) {
  nodeState.putShared('displayName', displayName.toString());
} else {
  nodeState.putShared('displayName', user.toString());
}

outcome = 'true';
action = fr.Action.goTo("true").build();

  4. Connect the nodes as demonstrated in the following figure:

    A journey for ForgeRock Go device registration.

    If you do not use the Scripted Decision node, connect the Identity Store Decision node True output directly to the WebAuthn Registration node.

  5. On the Identity Store Decision node, select Username as Universal Identifier.

  6. If you use the Scripted Decision node:

    1. Select your script in the Script list.

    2. Add the outcome of your script, true in this example, in the Outcomes field.

  7. On the WebAuthn Registration node:

    1. Select Username to device.

    2. If you do not use the Scripted Decision node, add userName in the Shared state attribute for display name field.

    3. If you use the Scripted Decision node, add the shared state variable name, such as displayName, in the Shared state attribute for display name field.

  8. Save your changes.

Create the ForgeRock Go authentication journey

  1. Configure the WebAuthn Profile Encryption service for the realm if you have not already done so.

  2. In the Advanced Identity Cloud admin UI, start a custom journey for ForgeRock Go authentication.

    Learn more in Custom journeys.

  3. In the Advanced Identity Cloud admin UI, add a WebAuthn Authentication node to your journey.

  4. Connect the nodes as demonstrated in the following figure:

    A journey for ForgeRock Go device authentication.

  5. On the WebAuthn Authentication node, ensure Username from device is enabled.

  6. Save your changes.

Register with ForgeRock Go

Follow these steps to register a device for usernameless authentication, and then authenticate with no username or password, only an authorization gesture.

  1. Register a test user account unless you have already done so.

  2. In an incognito browser window, browse to the ForgeRock Go registration journey. The URL looks something like:

    https://<tenant-env-fqdn>/am/XUI/?realm=alpha&authIndexType=service&authIndexValue=myForgeRockGoRegistrationJourney

    A login screen prompts for your credentials.

  3. Sign in with the username and password of the test user.

  4. If you are authenticating from a FIDO2-enabled device, it prompts you for the method to verify your identity.

    For example, you might use a USB security key or a built-in biometric sensor.

    Select the option to associate with the user.

  5. Perform the authorization gesture of the chosen option when asked to do so.

    For example, press the button on your USB security key or scan your fingerprint.

    The UI displays the user profile page.

  6. Browse to Edit Your Profile > 2-Step Verification > Change.

    The UI displays a list of the registered devices that you can rename or delete.

    The default name for the WebAuthn device is New Security Key.

  7. (Optional) Click the ellipsis icon, , select Edit Name, and give a suitable name to the new WebAuthn device, such as MacBook Touch ID.

Authenticate with ForgeRock Go

After registering, authenticate with ForgeRock Go without your username or password:

  1. Sign out.

  2. In the same browser window, browse to the ForgeRock Go authentication journey. The URL looks something like:

    https://<tenant-env-fqdn>/am/XUI/?realm=alpha&authIndexType=service&authIndexValue=myForgeRockGoAuthenticationJourney

  3. Perform the authorization gesture of the chosen option when prompted.

    A list of the accounts associated with the authentication device displays:

    Google Chrome presenting the accounts associated with Touch ID on the device.

    In this example, the user’s full name and email address appear. The Scripted Decision node gathered them during registration.

  4. Select the account to sign in.

    The UI displays the user profile page without you having to enter your username or password.

To design simple user journeys that invoke biometric sensors on FIDO2-enabled devices to add biometrics to your authentication journeys, refer to the Community blog Use case: Configure biometric authentication in PingOne Advanced Identity Cloud.

MFA: Authenticate using push notification

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

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

About push

The following steps occur as a user completes a push notification journey:

  1. The user provides credentials to let PingOne Advanced Identity Cloud locate the user profile and determine if they have a registered mobile device.

  2. PingOne Advanced Identity Cloud prompts the user to register a mobile device if they have not done so already.

    The user registers their device through the ForgeRock Authenticator app. The app supports a variety of methods to respond to push notifications from tapping a button to biometrics if the device supports them.

    Registering a device stores device metadata in the user profile that is required for push notifications. PingOne Advanced Identity Cloud uses the configured ForgeRock Authenticator (Push) service, which supports encrypting the metadata.

    For more information, refer to Manage devices for MFA.

  3. When the user has a registered device, PingOne Advanced Identity Cloud creates a push message specific to the device.

    The message has a unique ID that PingOne Advanced Identity Cloud stores while waiting for the response.

    PingOne Advanced Identity Cloud writes a pending record with the same message ID to the CTS store for redundancy should an individual server go offline during the authentication process.

  4. PingOne Advanced Identity Cloud sends the push message to the registered device, using the configured push notification service.

    Depending on the registered device, PingOne Advanced Identity Cloud uses either Apple Push Notification Services (APNS) or Google Cloud Messaging (GCM) to deliver the message.

    PingOne Advanced Identity Cloud begins to poll the CTS for an accepted response from the registered device.

  5. The user responds to the notification through the ForgeRock Authenticator app on the device, for example, approving or rejecting the notification.

    The app responds to the push notification message with the user’s choice.

  6. PingOne Advanced Identity Cloud verifies the message is from the correct registered device and has not been tampered with, and marks the pending record as accepted if valid.

    PingOne Advanced Identity Cloud detects the accepted record and redirects the user to their profile page, completing the authentication.

Implement push

The following table summarizes the tasks to perform to implement push authentication in your environment:

Task Resources

Configure authentication

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

Push authentication journeys

Test push authentication

After configuring the ForgeRock Authenticator (Push) service, the push notification service, and a push authentication journey, download the ForgeRock Authenticator app and test your configuration.

Test push authentication

Push authentication journeys

Configure authentication journeys for passwordless authentication and to receive push notifications.

When configured for passwordless authentication, the authentication flow requires the user to enter their user ID, but not their password. A push notification is then sent to their registered device to complete authentication with the ForgeRock Authenticator app.

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

Configure the ForgeRock Authenticator (Push) service

Configure the ForgeRock Authenticator (Push) service for the realm where you create the journey.

This service specifies the user profile attribute that stores registered device metadata.

  1. Under Native Consoles > Access Management > Realms > Realm Name, click Services > Add a Service.

  2. Select ForgeRock Authenticator (Push) Service in the service type drop-down list, and create the new service configuration.

  3. Accept the default configuration unless you must encrypt the device metadata in user profiles:

    Profile Storage Attribute

    pushDeviceProfiles (default)

    Device Profile Encryption Scheme

    If you choose an encryption scheme, also edit the settings to access the keys.

    For details, read Use ESVs for signing and encryption keys.

    Default: No encryption of device settings.

    ForgeRock Authenticator (Push) Device Skippable Attribute Name

    push2faEnabled (default)

    For details, read the reference documentation, ForgeRock Authenticator (Push) Service.

Configure the Push Notification service

Under Native Consoles > Access Management, configure the Push Notification service for the realm.

PingOne Advanced Identity Cloud uses an external AWS service to send push notifications. Its configuration requires access keys and other metadata. As a Ping Identity customer, you have streamlined access to the required metadata:

Before you start, log in to Backstage, then follow the instructions in How To Configure Service Credentials (Push Auth, Docker) in Backstage.

Download the AWS credential data in JSON format and refer to that as you configure the service.

  1. Under Native Consoles > Access Management > Realms > Realm Name, click Services > Add a Service.

  2. Select Push Notification Service in the service type drop-down list.

  3. Update the following fields with the data you generated on Backstage, then create the new service configuration:

    SNS Access Key ID

    The generated Key ID; the "accessKeyId" in the JSON

    SNS Access Key Secret

    The generated Secret; the "accessKeySecret" in the JSON

    SNS Endpoint for APNS

    The generated APNS; the "APNS" in the JSON

    SNS Endpoint for GCM

    The generated GCM; the "GCM" in the JSON

    You can also store the Access Key Secret in a secret store. For additional details, refer to the reference documentation, Push Notification Service.

Create a push authentication journey

The procedure assumes the following:

  • Users provide user IDs and passwords as the first step of multi-factor authentication (MFA).

  • PingOne Advanced Identity Cloud sends the push notification to the device as an additional factor to complete authentication.

  • You have prepared the prerequisite services, described in Configure the ForgeRock Authenticator (Push) service and Configure the Push Notification service.

    1. In the Advanced Identity Cloud admin UI, create a custom journey for push notification.

      Learn more in Custom journeys.

    2. Add the following nodes to your journey:

    3. Connect the nodes as demonstrated in the following figure:

      Example push authentication journey
      Figure 4. Example Push Authentication Journey
      Node connections
      Table 3. List of node connections
      Source node Outcome path Target node

      Page Node containing:

      • Platform Username

      • Platform Password

      →

      Data Store Decision

      Data Store Decision

      True

      Push Sender

      False

      Failure

      Push Sender

      Sent

      Push Wait

      Not Registered

      MFA Registration Options

      Push Wait

      Done

      Push Result Verifier

      Exit

      Recovery Code Collector Decision

      Push Result Verifier

      Success

      Success

      Failure

      Failure

      Expired

      Push Sender

      Waiting

      Push Wait

      MFA Registration Options

      Register

      Push Registration

      Get App

      Get Authenticator App

      Skip

      Success

      Opt-out

      Opt-out Multi-Factor Authentication

      Recovery Code Collector Decision

      True

      Success

      False

      Retry Limit Decision

      Push Registration

      Success

      Recovery Code Display Node

      Failure

      Failure

      Time Out

      MFA Registration Options

      Get Authenticator App

      →

      MFA Registration Options

      Opt-out Multi-Factor Authentication

      →

      Success

      Retry Limit Decision

      Retry

      Recovery Code Collector Decision

      Reject

      Failure

      Recovery Code Display Node

      →

      Push Sender

    4. Save your changes.

    5. Test your authentication journey as follows:

      1. Copy and paste the Preview URL into a browser in incognito mode. The URL will look something like:

        https://<tenant-env-fqdn>/am/XUI/?realm=alpha&authIndexType=service&authIndexValue=myPushAuthJourney

        A login screen prompting you to enter your user ID and password appears.

      2. Verify that you can use the ForgeRock Authenticator app to perform MFA.

        If the authentication journey is correctly configured, authentication is successful and PingOne Advanced Identity Cloud displays the user profile page. For details, refer to Test push authentication.

Create a passwordless authentication journey

The procedure assumes the following:

  • Users provide only their user IDs as the first step of MFA.

  • Users have pre-registered a device for push authentication.

  • PingOne Advanced Identity Cloud sends the push notification to the device as an additional factor to complete authentication, without needing the user’s password.

  • You have prepared the prerequisite services, described in Configure the ForgeRock Authenticator (Push) service and Configure the Push Notification service.

    1. In the Advanced Identity Cloud admin UI, create a custom journey for push notification.

      For details, refer to Custom journeys.

    2. Add the following nodes to your journey:

    3. Connect the nodes as demonstrated in the following figure:

      An authentication journey setup for passwordless push authentication.
      Figure 5. Passwordless Push Authentication Example

    4. Save your changes.

    5. Test your authentication journey as follows:

      1. Copy and paste the Preview URL into a browser in incognito mode. The URL will look something like:

        https://<tenant-env-fqdn>/am/XUI/?realm=alpha&authIndexType=service&authIndexValue=myPasswordlessAuthJourney

        A login screen appears, prompting you to enter your user ID.

      2. Verify that you can use the ForgeRock Authenticator app to perform MFA.

        If the authentication journey is correctly configured, authentication is successful and PingOne Advanced Identity Cloud displays the user profile page without the user entering their password.

        For details, refer to Test push authentication.

Test push authentication

PingOne Advanced Identity Cloud presents you with a page for entering only your user ID, or user ID and password. After you provide those credentials, PingOne Advanced Identity Cloud verifies them. If your credentials are valid and the account has a device registered for push notifications, PingOne Advanced Identity Cloud sends a push notification to the registered device.

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

The device needs access to the Internet to receive push notifications, and PingOne Advanced Identity Cloud must be able to receive responses from the device.

Receive push notifications

On your registered device, you will receive a push notification from PingOne Advanced Identity Cloud. Depending on the state of the device and the ForgeRock Authenticator application, respond to the notification as follows:

  • Unlock the device, if necessary, when you receive a device notification from the application.

    The ForgeRock Authenticator application opens and displays the push notification.

  • If the device is unlocked, but the ForgeRock Authenticator application is not open, select the device notification to open the application and display the push notification.

  • Open the ForgeRock Authenticator application to respond quickly to notifications.

Approve requests

How you approve requests depends on the ForgeRock Authenticator application settings, and on what the device supports.

Default settings for push notifications use a simple pop up in the application, similar to the following:

Approve the request by clicking Accept.

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

If you do not approve or deny the request on the registered device, the Push Authentication page times out and authentication fails.

You can configure this through the Message Timeout in the Push Sender node for the journey.

Register

If your credentials are valid but your profile is missing the metadata for a registered device registered, the MFA Registration Options node of the journey governs what happens:

Default text of the MFA Registration Options node.
Register Device

Configure the journey to continue to the Push Registration node.

When completing the journey, scan the QR code it displays with the ForgeRock Authenticator application.

For additional details, refer to Register the ForgeRock Authenticator for multi-factor authentication.

Get the application

Configure the journey to continue to the Get Authenticator App node.

When completing the journey, follow the link needed to obtain the ForgeRock Authenticator application for your device.

Skip this step

(Optional) In the example journey, skipping is linked to the Success node.

Opt-out

Configure the journey to continue to the Opt-out Multi-Factor Authentication node and let the user not use push.

In the example journey, opting out is linked to the Success node.

Configure successful registration to return to the Push Sender node, which starts the actual push notification stage of the journey, and the user can Receive push notifications.

Limitations of passwordless push authentication

When authenticating to a passwordless push authentication journey, the user enters their user ID, but not their password. PingOne Advanced Identity Cloud sends a push notification to their device to complete the authentication.

Be aware of the following limitations when you implement passwordless push authentication:

  • Unsolicited push messages can be sent to a user’s registered device by anyone who knows (or is able to guess) their user ID.

  • If a malicious user attempts 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’s 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: Use codes from ForgeRock app using 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.

About one-time password support

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.

PingOne Advanced Identity Cloud resynchronizes 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 PingOne Advanced Identity Cloud 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 log in to PingOne Advanced Identity Cloud. 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 log in until you reset the counter in PingOne Advanced Identity Cloud to match their device. For more information, refer to 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.

Create a journey for one-time password authentication

The following example journey uses TOTP, the default:

  1. In the Advanced Identity Cloud admin UI, start a custom OATH journey.

    Learn more in Custom journeys.

  2. In the Advanced Identity Cloud admin UI, add the following nodes to your journey:

  3. On the first OATH Token Verifier node, select Allow recovery codes.

  4. On the OATH Registration node, select Generate Recovery Codes.

    The value for OATH Algorithm must be the same for the registration and verification nodes.

  5. Connect the nodes as shown:

    Connect the nodes to gather user credentials.

  6. Save your changes.

This journey demonstrates OATH authentication. In a production environment, you could include additional nodes, such as:

Get Authenticator App node

Displays links to the ForgeRock Authenticator app for Android and iOS.

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.

Authenticate using a one-time password

After creating the journey, try it:

  1. Register a test user account unless you have already done so.

  2. In an incognito browser window, browse to the journey. The URL looks something like:

    https://<tenant-env-fqdn>/am/XUI/?realm=alpha&authIndexType=service&authIndexValue=myOathTotpJourney

    A login screen prompts for your credentials.

  3. Sign in with the username and password of the test user.

    A registration screen prompts to display a QR code.

  4. Register an authenticator, such as the ForgeRock Authenticator app, by scanning the QR code.

    The journey registers your one-time password app and displays recovery codes.

  5. Save the recovery codes and click Done to proceed to one-time password authentication.

  6. Enter the one-time password from your app, and click Submit:

    The prompt to enter a one-time password.

    If the animated timer indicates the one-time password is close to expiry, wait for the app to generate a new one.

    The UI displays the user profile page.

  7. Browse to Edit Your Profile > 2-Step Verification > Change.

    The UI displays your registered devices.

    The one-time password app you registered is named OATH Device.

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 PingOne Advanced Identity Cloud.

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 PingOne Advanced Identity Cloud.

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 PingOne Advanced Identity Cloud.

Reset registered devices

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

List registered devices

Learn how to list devices registered to a user.

MFA details are stored in the following profile attributes:

  • OATH: oathDeviceProfiles

  • Push: pushDeviceProfiles

  • WebAuthn: webauthnDeviceProfiles

  • Bound: boundDevices

You can access these attributes in scripts in the same way you access other profile attributes.

The ForgeRock Authenticator application

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

Download and install the ForgeRock Authenticator application to perform multi-factor authentication. The application is available for both Android and iOS devices, and is free to download from:

To build your own authenticator application, integrate the ForgeRock Authenticator module using Ping Identity SDKs.

Refer to the instructions for Android or iOS.

Register the ForgeRock Authenticator for MFA

Register the ForgeRock Authenticator application to use it as an additional factor when logging in.

The ForgeRock Authenticator application 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 PingOne Advanced Identity Cloud, refer to Create journeys for WebAuthn.

You register the ForgeRock Authenticator application once per authentication method with an identity provider. For example, if one journey uses push notifications and another uses one-time passwords, you must register the application separately for push notifications and one-time passwords.

The ForgeRock Authenticator application must access the internet to register to receive push notifications. Registering for one-time password authentication does not require a connection to the internet.

  1. When accessing a protected resource that requires multi-factor authentication, PingOne Advanced Identity Cloud prompts you to register a device, and displays a QR code screen:

    QR code to register your device

    • If you are logging in on the device and cannot scan the screen, click the On a mobile device? link to launch the application and register the device, bypassing the QR code.

    • If you are logging in on a computer, start the ForgeRock Authenticator application and click its plus icon () to register the device.

      The screen on the device changes to an interface similar to your camera app.

      Scan the QR code with the ForgeRock Authenticator app.

    The application displays the account you registered in the list of accounts.

  2. After registering your device, you MUST make a copy of the recovery codes for the account.

    Recovery codes screen

    Store the recovery codes separately from your device. The recovery codes will never be displayed again. They serve as one time verification codes to log in if your registered device is lost, stolen, or broken.

    When you have safely stored the recovery codes for your newly registered push device, click Done.

  3. If prompted, respond to the push notification or enter a one-time password from the app.

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

Recover after replacing a lost device

If you register a device with PingOne Advanced Identity Cloud and then lose it, you must authenticate to PingOne Advanced Identity Cloud using a recovery code. After deleting the lost device, you can register a new device.

  1. Access the list of recovery codes you saved when registering the lost device.

    If you did not save the recovery codes when you registered the device, contact your administrator to remove the device from your user profile instead of following these steps.

    Administrators can refer to Reset registered devices using REST for details.

  2. Begin to sign in as you normally would.

    When prompted to use a multi-factor option, click the Use Recovery Code link.

  3. Enter the recovery code when prompted.

    Single use recovery code

    Because recovery codes are valid for a single use only, remove the code you used from your list.

    PingOne Advanced Identity Cloud lets you sign in to access your profile page.

  4. Browse to Edit Your Profile > 2-Step Verification > Change.

    The UI displays the list of the registered devices.

    Delete the lost device from your profile.

  5. Register your new device by signing out, then accessing the protected resource that requires MFA.

    When registering for push notifications or one-time passwords, refer to The ForgeRock Authenticator application.

Recover after a device becomes out of sync

A device that generates one-time passwords can get out of sync with the OATH authentication service in some cases. If you repeatedly enter valid one-time passwords that appear to be valid passwords, but PingOne Advanced Identity Cloud rejects the passwords as unauthorized, your device is likely out of sync.

To resynchronize your device, you must authenticate with a recovery code, and register the device again. Follow the steps in Recover after replacing a lost device.

If you did not save the recovery codes when you registered the device, contact your administrator to remove the device from your user profile instead.

Reset registered devices using REST

As described in Recover after replacing a lost device, a user who has lost a mobile phone registered with PingOne Advanced Identity Cloud can register a replacement device by authenticating using a recovery code, deleting their existing device, and then registering a new device.

Additional support is required for users who lose mobile devices but did not save their recovery codes when they initially registered the device, and for users who have used up all their recovery codes.

PingOne Advanced Identity Cloud provides a REST API to reset a device profile by deleting information about a user’s registered device. Both the user and administrator accounts can use the REST API to reset a device profile. Administrators can:

  • Provide authenticated users with a self-service page that calls the REST API to reset their devices.

  • Call the REST API themselves to reset a user’s device profiles.

  • Call the REST API themselves to reset a device that is out of sync, where the HOTP counter exceeds the HOTP threshold window and requires a reset.

When making a REST API call, specify the realm in the path component of the endpoint. You must specify the entire hierarchy of the realm. Prefix each realm in the hierarchy with the realms/ keyword. For example, /realms/root/realms/alpha.

The following examples assume that you have obtained an access token with the appropriate scopes.

The API calls reference the user by _id. You can get this ID from the raw JSON for the user’s profile.

Reset OATH devices

To reset a user’s OATH device profile, send an HTTP POST request to the /users/user/devices/2fa/oath?_action=reset endpoint.

The following example resets the OATH devices for a user in the alpha realm. The user’s _id in this example is 014c54bd-6078-4639-8316-8ce0e7746fa4.

$ curl \
--request POST \
--header "Content-Type: application/json" \
--header "Accept-API-Version: resource=1.0" \
--header "authorization: Bearer access-token" \
--data '{}' \
'https://<tenant-env-fqdn>/am/json/realms/root/realms/alpha/users/014c54bd-6078-4639-8316-8ce0e7746fa4/devices/2fa/oath?_action=reset'
{
  "result":true
}

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 push devices

To reset push devices over REST, send an HTTP POST request to the /users/user/devices/2fa/push?_action=reset endpoint.

The following example resets the push devices for a user in the alpha realm. The user’s _id in this example is 014c54bd-6078-4639-8316-8ce0e7746fa4.

$ curl \
--request POST \
--header "Content-Type: application/json" \
--header "Accept-API-Version: resource=1.0" \
--header "authorization: Bearer access-token" \
--data '{}' \
'https://<tenant-env-fqdn>/am/json/realms/root/realms/alpha/users/014c54bd-6078-4639-8316-8ce0e7746fa4/devices/2fa/push?_action=reset'
{
  "result":true
}

Delete WebAuthn devices

The reset action is not implemented on the webauthn endpoint.

You can delete a WebAuthn device over REST as follows:

  1. Retrieve a list of WebAuthn devices associated with a user by querying the users/user/devices/2fa/webauthn endpoint.

    The following example retrieves a list of WebAuthn devices for a user in the alpha realm. The user’s _id in this example is 014c54bd-6078-4639-8316-8ce0e7746fa4.

    $ curl \
--request GET \
--header "authorization: Bearer access-token" \
'https://<tenant-env-fqdn>/am/json/realms/root/realms/alpha/users/014c54bd-6078-4639-8316-8ce0e7746fa4/devices/2fa/webauthn?_queryFilter=true'
{
  "result": [
    {
      "_id": "ff1db8bf-d2d7-46e1-926a-568b877f87a5",
      "_rev": "163664231",
      "deviceName": "New Security Key",
      "uuid": "ff1db8bf-d2d7-46e1-926a-568b877f87a5",
      "deviceManagementStatus": false
    }
  ],
  "resultCount": 1,
  "pagedResultsCookie": null,
  "totalPagedResultsPolicy": "NONE",
  "totalPagedResults": -1,
  "remainingPagedResults": -1
}

  2. Delete the required WebAuthn device from the user by sending an HTTP DELETE request to the users/user/devices/2fa/webauthn/device-id endpoint, including the ID of the WebAuthn device you want to delete:

    $ curl \
--request DELETE \
--header "Accept-API-Version: resource=1.0" \
--header "authorization: Bearer access-token" \
'https://<tenant-env-fqdn>/am/json/realms/root/realms/alpha/users/014c54bd-6078-4639-8316-8ce0e7746fa4/devices/2fa/webauthn/ff1db8bf-d2d7-46e1-926a-568b877f87a5'
{
  "_id": "ff1db8bf-d2d7-46e1-926a-568b877f87a5",
  "_rev": "1642022518",
  "uuid": "ff1db8bf-d2d7-46e1-926a-568b877f87a5",
  "recoveryCodes": [
    ...
  ],
  "credentialId": "XGJpYNYv4AHG9sHHgxFfTw",
  "algorithm": "SHA256withECDSA",
  "deviceName": "New Security Key",
  "key": {
    "kty": "EC",
    "x": "zMDAfFwRQR_5HIGfK1iJQ0kYwtudesx_UXocoBVrWbo",
    "y": "UgRBOBlpq6QYsXlqfHDzY8XNv-5DEMajRp9_3klkhDU",
    "crv": "P-256"
  }
}

  3. Repeat step 2 to delete additional WebAuthn devices for the user, if needed.

Reset bound devices

To delete all bound devices for a user, send an HTTP POST request to the /users/user/devices/2fa/binding?_action=reset endpoint. For details on binding devices to a user profile, refer to /sdks/latest/sdks/use-cases/how-to-bind-devices.html[device binding^].

The following example deletes bound devices for a user in the alpha realm. The user’s _id in this example is 014c54bd-6078-4639-8316-8ce0e7746fa4.

$ curl \
--request POST \
--header "Content-Type: application/json" \
--header "Accept-API-Version: resource=1.0" \
--header "authorization: Bearer access-token" \
--data '{}' \
'https://<tenant-env-fqdn>/am/json/realms/root/realms/alpha/users/014c54bd-6078-4639-8316-8ce0e7746fa4/devices/2fa/binding?_action=reset'
{
  "result":true
}

Deleting a bound device on the server does not remove the private keys from the device.

Instead, use the ForgeRock SDKs to remove the bound device from the server, and then remove the keys from the device. Learn more in /sdks/latest/sdks/use-cases/how-to-bind-devices.html#unbind[Unbind devices by deleting keys^].

List registered devices over REST

PingOne Advanced Identity Cloud provides a REST API to retrieve information about MFA devices registered to a user.

When making a REST API call, specify the realm in the path component of the endpoint. You must specify the entire hierarchy of the realm. Prefix each realm in the hierarchy with the realms/ keyword. For example, /realms/root/realms/alpha.

The following examples assume that you have obtained an access token with the appropriate scopes.

The API calls reference the user by _id. You can get this ID from the raw JSON for the user’s profile.

List OATH devices

To return a list of OATH devices registered to a user, query the users/user/devices/2fa/oath endpoint.

The following example lists the OATH devices for a user in the alpha realm. The user’s _id in this example is 014c54bd-6078-4639-8316-8ce0e7746fa4.

$ curl \
--request GET \
--header "authorization: Bearer access-token" \
'https://<tenant-env-fqdn>/am/json/realms/root/realms/alpha/users/014c54bd-6078-4639-8316-8ce0e7746fa4/devices/2fa/oath?_queryFilter=true'
{
  "result" : [ {
    "_id" : "ff1db8bf-d2d7-46e1-926a-568b877f87a5",
    "_rev" : "172031596",
    "deviceName" : "OATH Device",
    "uuid" : "ff1db8bf-d2d7-46e1-926a-568b877f87a5",
    "deviceManagementStatus" : false
  } ],
  "resultCount" : 1,
  "pagedResultsCookie" : null,
  "totalPagedResultsPolicy" : "NONE",
  "totalPagedResults" : -1,
  "remainingPagedResults" : -1
}

List push devices

To return a list of push devices registered to a user, query the users/user/devices/2fa/push endpoint.

The following example lists the push devices for a user in the alpha realm. The user’s _id in this example is 014c54bd-6078-4639-8316-8ce0e7746fa4.

$ curl \
--request GET \
--header "authorization: Bearer access-token" \
'https://<tenant-env-fqdn>/am/json/realms/root/realms/alpha/users/014c54bd-6078-4639-8316-8ce0e7746fa4/devices/2fa/push?_queryFilter=true'
{
  "result" : [ {
    "_id" : "ff1db8bf-d2d7-46e1-926a-568b877f87a5",
    "_rev" : "172031596",
    "deviceName" : "Push Device",
    "uuid" : "ff1db8bf-d2d7-46e1-926a-568b877f87a5",
    "deviceManagementStatus" : false
  } ],
  "resultCount" : 1,
  "pagedResultsCookie" : null,
  "totalPagedResultsPolicy" : "NONE",
  "totalPagedResults" : -1,
  "remainingPagedResults" : -1
}

List WebAuthn devices

To return a list of WebAuthn devices registered to a user, query the users/user/devices/2fa/webauthn endpoint.

The following example lists the WebAuthn devices for a user in the alpha realm. The user’s _id in this example is 014c54bd-6078-4639-8316-8ce0e7746fa4.

$ curl \
--request GET \
--header "authorization: Bearer access-token" \
'https://<tenant-env-fqdn>/am/json/realms/root/realms/alpha/users/014c54bd-6078-4639-8316-8ce0e7746fa4/devices/2fa/webauthn?_queryFilter=true'
{
  "result": [
    {
      "_id": "ff1db8bf-d2d7-46e1-926a-568b877f87a5",
      "_rev": "163664231",
      "deviceName": "New Security Key",
      "uuid": "ff1db8bf-d2d7-46e1-926a-568b877f87a5",
      "deviceManagementStatus": false
    }
  ],
  "resultCount": 1,
  "pagedResultsCookie": null,
  "totalPagedResultsPolicy": "NONE",
  "totalPagedResults": -1,
  "remainingPagedResults": -1
}

List bound devices

To return a list of bound devices for a user, query the users/user/devices/2fa/binding endpoint. Learn more about binding devices to a user profile in /sdks/latest/sdks/use-cases/how-to-bind-devices.html[device binding^].

The following example lists the bound devices for a user in the alpha realm. The user’s _id in this example is 014c54bd-6078-4639-8316-8ce0e7746fa4.

$ curl \
--request GET \
--header "authorization: Bearer access-token" \
'https://<tenant-env-fqdn>/am/json/realms/root/realms/alpha/users/014c54bd-6078-4639-8316-8ce0e7746fa4/devices/2fa/binding?_queryFilter=true'
{
  "result": [
    {
      "_id": "ff1db8bf-d2d7-46e1-926a-568b877f87a5",
      "_rev": "192142989",
      "createdDate": 1715182923119,
      "lastAccessDate": 1715182923183,
      "deviceId": "e2e84b5d2a927abdcb85570bac9701c390a92751",
      "deviceName": "iOS Device",
      "uuid": "ff1db8bf-d2d7-46e1-926a-568b877f87a5",
      "key": {
        ...
      },
      "deviceManagementStatus": false
    }
  ],
  "resultCount": 1,
  "pagedResultsCookie": null,
  "totalPagedResultsPolicy": "NONE",
  "totalPagedResults": -1,
  "remainingPagedResults": -1
}

Account lockout

Account lockout is a security mechanism that locks a user account after repeated failed login attempts. It is used to slow down brute-force attacks and compensate for weak password policies.

You can configure account lockout in one of the following ways:

Persistent lockout

Persistent (physical) lockout locks the user account indefinitely. A tenant administrator can release the lock by setting the account status to active.

For persistent lockout, Advanced Identity Cloud sets the user account status to inactive. This makes it easy for a tenant administrator to search for user accounts with a persistent lockout set. It also means that if you synchronize your user accounts from Advanced Identity Cloud to another datastore, you can track locked accounts in the downstream datastore.

This is the default type of account lockout and Ping Identity recommends it as the best way to mitigate brute force attacks.

Duration lockout

Duration lockout locks the user account for a specified duration. The lock is automatically released after the specified duration.

Unlike persistent lockout, the user account status remains active. Instead, Advanced Identity Cloud tracks the locked state internally. This makes it harder for a tenant administrator to search for user accounts with a duration lockout set. It also means that if you synchronize your user accounts from Advanced Identity Cloud to another datastore, you cannot track locked accounts in the downstream datastore. However, it is possible to configure the Invalid Attempts Data Attribute Name to persist metadata about failed authentication attempts to a specified user account attribute — refer to Configure account lockout.

Failed login attempts during the transactional authorization flow do not increment account lockout counters.

Configure account lockout

  1. In the Advanced Identity Cloud admin UI, select Native Consoles > Access Management.

  2. Go to Realms > Realm Name > Authentication > Settings > Account Lockout.

  3. Enable lockout by checking Login Failure Lockout Mode, then set the number of attempts and the lockout interval. You can also opt to warn users after several consecutive failures.

  4. To configure persistent lockout:

    1. Set Login Failure Lockout Duration to 0.

    2. Check Store Invalid Attempts in Data Store.

  5. To configure duration lockout:

    1. Set Login Failure Lockout Duration to a positive integer value representing number of minutes. Set a value of at least 15. Optionally, configure a multipier to increase the lockout duration on each successive lockout.

    2. Check Store Invalid Attempts in Data Store.

    3. Set Invalid Attempts Data Attribute Name to sunAMAuthInvalidAttemptsData. Alternatively, to persist invalid attempts metadata to the user account, set Invalid Attempts Data Attribute Name to a valid attribute; for example, fr-attr-istr1. For a list of valid attributes, refer to the User identity attributes and properties reference.

  6. Click Save Changes.

Success and Failure nodes

If you enable account lockout in a realm, the Success and Failure nodes play a key role in modifying journey behavior. The Success node resets the number of invalid attempts to zero. The Failure node increments the number of invalid attempts and triggers Warn User After N Failures messages.

Success node

This node does the following:

  • Checks the Status property of the user profile, when reached. If the account is marked as Inactive, the node fails the authentication with an error message:

    Account locked error when reaching Success node.

    The error message is returned in the JSON response if authenticating to the journey over REST:

    {
    "code":401,
    "reason":"Unauthorized",
    "message":"User Locked Out.",
    "detail":
    {
        "failureUrl":""
    }
}

  • If the User Status property is set to Active, the node resets the failure count in the user profile, when reached.

Failure node

This node does the following:

  • If you select Authentication > Settings > Account Lockout > Login Failure Lockout Mode for the realm (under Native Consoles > Access Management), the node checks the invalid attempts property of the user profile. It returns a warning message if the number of failed attempts is equal to or greater than the configured Warn User After N Failures value:

    Invalid attempts limit warning when reaching Failure node.

    The error message is returned in the JSON response if authenticating to the journey over 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:

    Account locked error when reaching Failure node.

    The error message is returned in the JSON response if authenticating to the journey over REST:

    {
    "code":401,
    "reason":"Unauthorized",
    "message":"User Locked Out.",
    "detail":
    {
        "failureUrl":""
    }
}

Lockout-specific nodes

Authentication journeys also provide lockout-specific nodes for checking and changing the status of a user:

Account Active Decision node

Use this node to determine whether an account is considered locked or unlocked.

  • The account is considered locked under these conditions:

    • The status is inactive.

    • The status is active and a duration lockout is set on the account.

  • The account is considered unlocked under this condition:

    • The status is active and no duration lockout is set on the account.

Account Lockout node

Use this node to change the account’s status to inactive or active.

When setting an account to inactive, the node does not consider the realm’s account lockout settings, so effectively sets a persistent lockout on the account.

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

Additional reference for auth and SSO

This reference covers settings and the scripting API for authentication in PingOne Advanced Identity Cloud.

Core authentication attributes

Each realm has a set of properties that applies to all authentication performed to that realm. These properties are the core authentication attributes of the realm.

To edit a realm’s authentication configuration, go to Native Consoles > Access Management > Realms > Realm Name > Authentication > Settings.

Core

The following properties are available under the Core tab:

Administrator Authentication Configuration

The default authentication journey used when an administrative user authenticates.

Organization Authentication Configuration

The default authentication journey used when a non-administrative user authenticates.

amster attribute: orgConfig

User Profile

The following properties are available under the User Profile tab:

User Profile

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, PingOne Advanced Identity Cloud creates a user profile if one does not already exist. PingOne Advanced Identity Cloud then issues the SSO token. PingOne Advanced Identity Cloud creates the user profile in the user data store configured for the realm.

createAlias. Dynamic with User Alias.

After successful authentication, PingOne Advanced Identity Cloud 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, PingOne Advanced Identity Cloud 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 PingOne Advanced Identity Cloud to issue an SSO token.

User Profile Dynamic Creation Default Roles

This property does not apply to Advanced Identity Cloud.
Alias Search Attribute Name

After a user is successfully authenticated, the user’s profile is retrieved. PingOne Advanced Identity Cloud first searches for the user based on the data store settings. If that fails to find the user, PingOne Advanced Identity Cloud uses 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, PingOne Advanced Identity Cloud 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

The number of attempts 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

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

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

The number of authentication failures after which PingOne Advanced Identity Cloud 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

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

amster attribute: lockoutAttributeName

Lockout Attribute Value

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

amster attribute: lockoutAttributeValue

Invalid Attempts Data Attribute Name

The LDAP attribute used to hold the number of failed authentication attempts towards Login Failure Lockout Count. Although the field appears empty in the UI, PingOne Advanced Identity Cloud 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, PingOne Advanced Identity Cloud 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.

amster attribute: storeInvalidAttemptsInDataStore

General

The following properties are available under the General tab:

Default Authentication Locale

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

amster attribute: locale

Identity Types

This property does not apply to Advanced Identity Cloud.
Pluggable User Status Event Classes

This property does not apply to Advanced Identity Cloud.

+

Use Client-Side Sessions

When enabled, PingOne Advanced Identity Cloud assigns client-side sessions to users authenticating to this realm. Otherwise, PingOne Advanced Identity Cloud users authenticating to this realm are assigned server-side sessions.

amster attribute: statelessSessionsEnabled

External Login Page URL

The URL of the external login user interface, if the authentication user interface is hosted separately from PingOne Advanced Identity Cloud.

When set, PingOne Advanced Identity Cloud uses the provided URL as the base of the resume URI, rather than using the Base URL Source Service to obtain the base URL. PingOne Advanced Identity Cloud uses this URL when constructing the resume URI if authentication is suspended in an authentication journey.

amster attribute: externalLoginPageUrl

Default Authentication Level

This property does not apply to Advanced Identity Cloud.
Trees

The following properties are available under the Trees tab:

Authentication session state management scheme

The location where PingOne Advanced Identity Cloud stores authentication sessions.

Possible values are:

  • CTS. PingOne Advanced Identity Cloud stores authentication sessions server-side, in the CTS token store.

  • JWT. PingOne Advanced Identity Cloud sends the authentication session to the client as a JWT.

  • In-Memory. PingOne Advanced Identity Cloud stores authentication sessions in its memory.

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

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

amster attribute: authenticationSessionsStateManagement

Max duration (minutes)

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)

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 Allowlisting

When enabled, PingOne Advanced Identity Cloud 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

This property doesn’t apply to Advanced Identity Cloud.
Persistent Cookie Encryption Certificate Alias

The key pair alias in the PingOne Advanced Identity Cloud keystore to use for encrypting persistent cookies.

This property is deprecated. Use the rotatable secret mapping am.authentication.nodes.persistentcookie.encryption instead.

If PingOne Advanced Identity Cloud finds a matching secret in the secret store for am.authentication.nodes.persistentcookie.encryption, this alias is ignored.

Learn more about mapping and rotating secrets in Use ESVs for signing and encryption keys.

Default: test

amster attribute: keyAlias

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

Zero Page Login

This property does not apply to Advanced Identity Cloud.
Zero Page Login Referer Allowlist

This property does not apply to Advanced Identity Cloud.
Zero Page Login Allowed Without Referer?

This property does not apply to Advanced Identity Cloud.
Add clear-site-data Header on Logout

This property does not apply to Advanced Identity Cloud.
Organization Authentication Signing Secret

Specifies a cryptographically-secure random-generated HMAC shared secret for signing RESTful authentication requests. When users attempt to authenticate, PingOne Advanced Identity Cloud 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

This property does not apply to Advanced Identity Cloud.
Generate UserID Mode

This property does not apply to Advanced Identity Cloud.
Pluggable User Name Generator Class

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

This property does not apply to Advanced Identity Cloud.

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

Supported callbacks

For an example using callbacks to authenticate, refer to Return callback information to PingOne Advanced Identity Cloud.

PingOne Advanced Identity Cloud supports the following callback types.

Callback type Use

Interactive

Request information.

Read-only

Return information to the client application, potentially for display to the user.

Backchannel

Recover additional information from the user’s request.

Interactive callbacks

Nodes return the following callbacks to request information.

BooleanAttributeInputCallback

Collects a boolean-style confirmation, such as yes/no or true/false.

The Attribute Collector node uses this instead of a ConfirmationCallback to apply IDM policies and validate the response.

Callback output field Description

failedPolicies

An array of JSON objects describing validation policies that the input failed. The object is empty until the input is provided and validation fails.

name

A string containing the name of the attribute in the user profile.

policies

An array of JSON objects describing IDM validation policies the input must pass. An empty JSON object if the node does not require validation.

prompt

A string containing the description of the information required from the user.

required

A boolean indicating whether input is required for this attribute.

validateOnly

When the node requires validation, this boolean indicates whether to apply validation policies only, or to validate the input and continue to the next node. When true, the node only performs input validation and does not continue to the next node.

When true, this lets the UI validate input as the user types instead of validating the input once and continuing the journey to the next 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
    }]
  }]
}

In the input, return the value and a boolean to set validateOnly.

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

Learn more in BooleanAttributeInputCallback.

ChoiceCallback

Provides a list of choices and collects the selected choice.

In the input, return 0 if the user selected the first choice, 1 for the second choice, 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 in scripts: javax.security.auth.callback.ChoiceCallback

Learn more in ChoiceCallback.

ConfirmationCallback

Collects a boolean-style confirmation, such as yes/no or true/false with an optional "Cancel" choice.

Callback output field Description

defaultOption

A number identifying the default option in the array of options, counting from 0.

messageType

A number indicating the severity of the message:

  • 0: Information

  • 1: Warning

  • 2: Error

optionType

A number indicating the type of confirmation:

  • -1: Unspecified

  • 0: Yes/no

  • 1: Yes/no/cancel

  • 2: OK/cancel

options

An array of strings containing the option text for display to the user.

prompt

A string containing the description of the choice to display to the user.
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
    }]
  }]
}

In the input, return 0 if the user selected the first choice, 1 for the second choice, and so forth.

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

Learn more in ConfirmationCallback.

ConsentMappingCallback

Provides profile attributes that require user consent and collects consent from the user.

Callback output field Description

accessLevel

A string containing the access level description for display to the user.

displayName

A string containing the name for display to the user.

fields

An array containing names of the attributes to share.

icon

A string containing an icon specification for the privacy and consent notice.

isRequired

A boolean indicating whether consent is required.

message

A string containing the privacy and consent notice for display to the user.

name

A string containing the name of the mapping.
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; in the input, return a single boolean value.

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

Learn more in ConsentMappingCallback.

DeviceBindingCallback

Binds a client device to a user.

Callback output field Description

userId

The ID of the user to bind the device to.

username

The username of the user to bind the device to.

authenticationType

Specifies how the client secures access to the private key. Available options are:

BIOMETRIC

Request that the client secures access to the cryptography keys with biometric security, such as a fingerprint.

BIOMETRIC_ALLOW_FALLBACK

Request that the client secures access to the cryptography keys with biometric security, such as a fingerprint, but allow use of the device PIN if biometric is unavailable.

APPLICATION_PIN

Request that the client secures access to the cryptography keys with an application-specific PIN.

NONE

Request that the client generates a keypair, but does not secure access to them.

challenge

A string containing the challenge the client should sign with the private key and return for validation.

title

A string containing an optional title to display when requesting biometric authentication to secure access to the keypair.

subtitle

A string containing an optional subtitle to display when requesting biometric authentication to secure access to the keypair.

description

A string containing optional descriptive text to display when requesting biometric authentication to secure access to the keypair.

timeout

An integer specifying the number of seconds to wait for device binding to complete before reporting a timeout error.
Example response data
{
  "authId": "...",
  "callbacks": [
    {
      "type": "DeviceBindingCallback",
      "output": [
        {
          "name": "userId",
          "value": "id=demo,ou=user,dc=openam,dc=forgerock,dc=org"
        },
        {
          "name": "username",
          "value": "demo"
        },
        {
          "name": "authenticationType",
          "value": "BIOMETRIC_ALLOW_FALLBACK"
        },
        {
          "name": "challenge",
          "value": "6IBkTEPcMQ0xCghIclmDLost2ssGO5cPDs0AjUhmDTo="
        },
        {
          "name": "title",
          "value": "Authentication required"
        },
        {
          "name": "subtitle",
          "value": "Cryptography device binding"
        },
        {
          "name": "description",
          "value": "Please authenticate with biometrics to proceed"
        },
        {
          "name": "timeout",
          "value": 60
        }
      ],
      "input": [
        {
          "name": "IDToken1jws",
          "value": ""
        },
        {
          "name": "IDToken1deviceName",
          "value": ""
        },
        {
          "name": "IDToken1deviceId",
          "value": ""
        },
        {
          "name": "IDToken1clientError",
          "value": ""
        }
      ]
    }
  ]
}

The client device should perform the following high-level steps to fulfil this callback:

  1. Generate a keypair and secure access to it as defined by the authenticationType field.

  2. Generate a JSON web token (JWT) that has the ID of the user in the subject (sub) field and the original value of the challenge.

    For example:

    {
    "sub": "id=demo,ou=user,dc=openam,dc=forgerock,dc=org",
    "challenge": "6IBkTEPcMQ0xCghIclmDLost2ssGO5cPDs0AjUhmDTo="
}

  3. Sign the JWT using the RS512 algorithm to create a JSON Web Signature (JWS).

  4. Complete the callback, returning the JWS, the key ID (KID) of the keypair, the public key, and the name and the unique ID of the device.

The server verifies the returned information and persists it in the user’s profile if correct.

Example response data
{
  "authId": "...",
  "callbacks": [
    {
      "type": "DeviceBindingCallback",
      "output": [...],
      "input": [
        {
          "name": "IDToken1jws",
          "value": "eyJhbGciOiJIUzI1NiI....JV_adQssw5cB6aDS6m_kwIiw"
        },
        {
          "name": "IDToken1deviceName",
          "value": "Example Brand Version Android Device"
        },
        {
          "name": "IDToken1deviceId",
          "value": "ae9573dbbf442e7f-8e0c8b428409e0f1c"
        },
        {
          "name": "IDToken1clientError",
          "value": ""
        }
      ]
    }
  ]
}

Class to import in scripts: org.forgerock.openam.authentication.callbacks.DeviceBindingCallback

Learn more in DeviceBindingCallback.

DeviceProfileCallback

Collects information about the device used to authenticate.

Callback output field Description

metadata

A boolean indicating whether to collect device metadata.

location

A boolean indicating whether to collect the device location.

message

A string containing optional text to display while collecting device information.
Example
{
  "callbacks": [{
    "type": "DeviceProfileCallback",
    "output": [{
      "name": "metadata",
      "value": true
    }, {
      "name": "location",
      "value": true
    }, {
      "name": "message",
      "value": "Collecting....."
    }],
    "input": [{
      "name": "IDToken1",
      "value": ""
    }]
  }]
}

In the input, return escaped JSON resembling the following example response data.

Example response data
{
  "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
  }
}

The location and metadata fields are required when their values are true in the output. The alias and identifier fields are optional and provided when the client uses the Ping Identity SDKs.

alias

A friendly name for the device often derived from the make and model.

identifier

A unique identifier string that can be used to later match the device.

location

Latitude and longitude of the device.

metadata

Refer to the example response data for details.

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

Learn more in DeviceProfileCallback.

DeviceSigningVerifierCallback

Verifies the signature of data from a registered device.

Callback output field Description

userId

The ID of the user authenticating, if already determined by the authentication journey.

challenge

A string containing the challenge the client should sign with the private key and return for validation.

title

A string containing an optional title to display when requesting biometric authentication to access the keypair.

subtitle

A string containing an optional subtitle to display when requesting biometric authentication to access the keypair.

description

A string containing optional descriptive text to display when requesting biometric authentication to access the keypair.

timeout

An integer specifying the number of seconds to wait for device signing to complete before reporting a timeout error.
Example response data
{
  "authId": "...",
  "callbacks": [
    {
      "type": "DeviceSigningVerifierCallback",
      "output": [
        {
          "name": "userId",
          "value": ""
        },
        {
          "name": "challenge",
          "value": "Kc4dc14on98DYFzr5SoP2n3TC/JWAcAqTJMjCM+T27Y="
        },
        {
          "name": "title",
          "value": "Authentication required"
        },
        {
          "name": "subtitle",
          "value": "Cryptography device binding"
        },
        {
          "name": "description",
          "value": "Please complete with biometric to proceed"
        },
        {
          "name": "timeout",
          "value": 60
        }
      ],
      "input": [
        {
          "name": "IDToken1jws",
          "value": ""
        },
        {
          "name": "IDToken1clientError",
          "value": ""
        }
      ]
    }
  ]
}

The client device should perform the following high-level steps to fulfill this callback:

  1. Generate a JSON web token (JWT) that has the ID of the user in the subject (sub) field) and the original value of the challenge.

    For example:

    {
    "sub": "id=demo,ou=user,dc=openam,dc=forgerock,dc=org",
    "challenge": "6IBkTEPcMQ0xCghIclmDLost2ssGO5cPDs0AjUhmDTo="
}

  2. Sign the JWT using the RS512 algorithm to create a JSON Web Signature (JWS).

  3. Complete the callback, returning the JWS.

The server verifies the signature against the stored public key.

Example response data
{
  "authId": "...",
  "callbacks": [
    {
      "type": "DeviceSigningVerifierCallback",
      "output": [...],
      "input": [
        {
          "name": "IDToken1jws",
          "value": "eyJhbGciOiJIUzI1NiI....JV_adQssw5cB6aDS6m_kwIiw"
        },
        {
          "name": "IDToken1clientError",
          "value": ""
        }
      ]
    }
  ]
}

Class to import in scripts: org.forgerock.openam.authentication.callbacks.DeviceSigningVerifierCallback

Learn more in DeviceSigningVerifierCallback.

HiddenValueCallback

Provides form values that are to remain hidden from the 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 in scripts: com.sun.identity.authentication.callbacks.HiddenValueCallback

Learn more in HiddenValueCallback.

IdPCallback

Collects the result of a native OAuth 2.0 or OIDC request to a social identity provider.

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

The output provides the information required to perform the request. Clients built using the Ping SDKs for Android or iOS use this to authenticate to the social identity provider with the mobile OS native APIs.

Callback output field Description

acrValues

An array containing the Authentication Context Class Reference values for the native authentication request.

clientId

A string containing the identifier for the native authentication request.

nonce

A string containing the nonce for the native authentication request.

provider

A string containing a name for the provider.

redirectUri

A string containing the redirection URI for the native authentication request.

request

A string containing the Request Object for the native authentication request.

requestUri

A string containing a URL that references a resource containing the Request Object for the native authentication request.

scopes

An array containing the scopes for the native authentication request.
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": ""
    }]
  }]
}

In the input, return a JWT id_token, access_token or authorization code for the token, and id_token, access_token or authorization_code for the token type.

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

Learn more in IdPCallback.

KbaCreateCallback

Collects knowledge-based authentication (KBA) answers to questions defined in the user profile, or user-defined question and answer pairs.

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": ""
    }]
  }]
}

In the input, return an empty IDTokenNumberquestion value when IDTokenNumberanswer corresponds to predefinedQuestions[Number]. For user-provided questions, return both.

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

Learn more in KbaCreateCallback.

NameCallback

Collects a string entered by the user, such as a username.

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

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

Learn more in NameCallback.

NumberAttributeInputCallback

Collects a numeric attribute, such as size or age.

The Attribute Collector node uses this to apply IDM policies and validate the response.

Callback output field Description

failedPolicies

An array of JSON objects describing validation policies that the input failed. The object is empty until the input is provided and validation fails.

name

A string containing the name of the attribute in the user profile.

policies

An array of JSON objects describing IDM validation policies the input must pass. An empty JSON object if the node does not require validation.

prompt

A string containing the description of the information required from the user.

required

A boolean indicating whether input is required for this attribute.

validateOnly

When the node requires validation, this boolean indicates whether to apply validation policies only, or to validate the input and continue to the next node. When true, the node only performs input validation and does not continue to the next node.

When true, this lets the UI validate input as the user types instead of validating the input once and continuing the journey to the next node.

value

A string containing a default value for the attribute, if required.

In the input, return the value and a boolean to set validateOnly.

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

Learn more in NumberAttributeInputCallback.

PasswordCallback

Collects a password value.

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

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

Learn more in PasswordCallback.

PingOneProtectEvaluationCallback

Instructs the client to return the data captured by the PingOne Signals (Protect) SDK so that a risk evaluation can be completed.

Callback output field Description

pauseBehavioralData

A boolean indicating whether to stop collecting behavioral data after returning the existing data.
Example
{
  "callbacks":[
    {
      "type":"PingOneProtectEvaluationCallback",
      "output":[
        {
          "name":"pauseBehavioralData",
          "value":true
        }
      ],
      "input":[
        {
          "name":"IDToken1signals",
          "value":""
        },
        {
          "name":"IDToken1clientError",
          "value":""
        }
      ]
    }
  ]
}

In the input:

  • In IDToken1signals, return the data captured by the PingOne Signals SDK.

  • In IDToken1clientError, return an empty string to signal success, or an error string to indicate that the client was unable to process the request.

Class to import

org.forgerock.openam.authentication.callbacks.PingOneProtectEvaluationCallback

Learn more in PingOneProtectEvaluationCallback.

PingOneProtectInitializeCallback

Instructs the client to initialize the PingOne Signals (Protect) SDK to gather information during a transaction.

Callback output field Description

envId

A string containing the PingOne environment ID.

consoleLogEnabled

A boolean indicating whether to output SDK log messages to the developer console.

deviceAttributesToIgnore

An array of device attributes to ignore when collecting device signals.

customHost

A string containing a custom host URL from which to retrieve a "Pong" token.

Not currently used.

lazyMetadata

A boolean indicating whether to calculate metadata on demand.

When false, metadata is calculated automatically after initialization.

behavioralDataCollection

A boolean indicating whether to collect behavioral data.

disableHub

A boolean indicating whether the client stores device data in the browser’s localStorage only.

When false, the client uses an iframe if supported.

deviceKeyRsyncIntervals

An integer indicating the number of days that device attestation can rely upon the device fallback key.

enableTrust

A boolean indicating whether to tie the device payload to a non-extractable crypto key stored in the browser for content authenticity verification.

disableTags

A boolean indicating whether to collect tag data.
Example
{
  "type":"PingOneProtectInitializeCallback",
  "output":[
    {
      "name":"envId",
      "value":"3072206d-c6ce-4c19-a366-f87e972c7cc3"
    },
    {
      "name":"consoleLogEnabled",
      "value":false
    },
    {
      "name":"deviceAttributesToIgnore",
      "value":[
        "field1",
        "field2"
      ]
    },
    {
      "name":"customHost",
      "value":""
    },
    {
      "name":"lazyMetadata",
      "value":false
    },
    {
      "name":"behavioralDataCollection",
      "value":true
    },
    {
      "name":"deviceKeyRsyncIntervals",
      "value":14
    },
    {
      "name":"enableTrust",
      "value":false
    },
    {
      "name":"disableTags",
      "value":false
    },
    {
      "name":"disableHub",
      "value":false
    }
  ],
  "input":[
    {
      "name":"IDToken1clientError",
      "value":""
    }
  ]
}

In the input IDToken1clientError field, return an empty string to signal success, or define any error string to indicate initialization of the SDK failed.

Class to import

org.forgerock.openam.authentication.callbacks.PingOneProtectInitializeCallback

Learn more in PingOneProtectInitializeCallback.

SelectIdPCallback

Collects a choice of an enabled social identity provider or local authentication.

The Select Identity Provider node returns this callback when multiple social identity providers are enabled, or when Local Authentication is enabled alongside at least one provider.

In the input, return the provider name, such as amazon or localAuthentication.

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 in scripts: org.forgerock.openam.authentication.callbacks.SelectIdPCallback

Learn more in SelectIdPCallback.

StringAttributeInputCallback

Collects string attributes, such as city names, telephone numbers, and postcodes.

The Attribute Collector node uses this instead of a TextInputCallback to apply IDM policies and validate the response.

Callback output field Description

failedPolicies

An array of JSON objects describing validation policies that the input failed. The object is empty until the input is provided and validation fails.

name

A string containing the name of the attribute in the user profile.

policies

An array of JSON objects describing IDM validation policies the input must pass. An empty JSON object if the node does not require validation.

prompt

A string containing the description of the information required from the user.

required

A boolean indicating whether input is required for this attribute.

validateOnly

When the node requires validation, this boolean indicates whether to apply validation policies only, or to validate the input and continue to the next node. When true, the node only performs input validation and does not continue to the next node.

When true, this lets the UI validate input as the user types instead of validating the input once and continuing the journey to the next 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
    }]
  }]
}

When input validation is not required, the policies contain an empty object:

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

In the input, return the value and a boolean to set validateOnly.

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

Learn more in StringAttributeInputCallback.

TermsAndConditionsCallback

Displays the current terms and conditions and collects the user’s agreement to them.

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

In the input, return true if the user agrees to the terms and conditions.

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

Learn more in TermsAndConditionsCallback.

TextInputCallback

Collects text input from the user.

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

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

Learn more in TextInputCallback.

ValidatedCreatePasswordCallback

Collects a password value.

The Platform Password node uses this instead of a PasswordCallback to apply IDM policies and validate the response.

Callback output field Description

failedPolicies

An array of JSON objects describing validation policies that the input failed. The object is empty until the input is provided and validation fails.

name

A string containing the name of the attribute in the user profile.

policies

An array of objects describing IDM validation policies the input must pass. An empty JSON object if the node does not require validation.

prompt

A string containing the description of the information required from the user.

validateOnly

When the node requires validation, this boolean indicates whether to apply validation policies only, or to validate the input and continue to the next node. When true, the node only performs input validation and does not continue to the next node.

When true, this lets the UI validate input as the user types instead of validating the input once and continuing the journey to the next node.
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
    }]
  }]
}

In the input, return the value and a boolean to set validateOnly.

Class to import in scripts: org.forgerock.openam.authentication.callbacks.ValidatedPasswordCallback

Learn more in ValidatedPasswordCallback.

ValidatedCreateUsernameCallback

Collects a username.

The Platform Username node uses this instead of a NameCallback to apply IDM policies and validate the response.

Callback output field Description

failedPolicies

An array of JSON objects describing validation policies that the input failed. The object is empty until the input is provided and validation fails.

name

A string containing the name of the attribute in the user profile.

policies

An array of objects describing IDM validation policies the input must pass. An empty JSON object if the node does not require validation.

prompt

A string containing the description of the information required from the user.

validateOnly

When the node requires validation, this boolean indicates whether to apply validation policies only, or to validate the input and continue to the next node. When true, the node only performs input validation and does not continue to the next node.

When true, this lets the UI validate input as the user types instead of validating the input once and continuing the journey to the next node.
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
    }]
  }]
}

In the input, return the value and a boolean to set validateOnly.

Class to import in scripts: org.forgerock.openam.authentication.callbacks.ValidatedUsernameCallback

Learn more in ValidatedUsernameCallback.

Read-only callbacks

Nodes use these callbacks to return information to the client application or to display information to the user.

MetadataCallback

Injects key-value pairs into the authentication process.

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

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

Learn more in MetadataCallback.

PollingWaitCallback

Indicates the number of milliseconds 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 in scripts: org.forgerock.openam.authentication.callbacks.PollingWaitCallback

Learn more in PollingWaitCallback.

RedirectCallback

Redirects the user-agent.

The Social Provider Handler node returns this callback when its Client Type is set to BROWSER, and the client must redirect the user to the social 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
    }]
  }]
}

PingOne Advanced Identity Cloud uses a trackingCookie to store the authentication identifier that reflects the client’s place in the authentication process.

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

Learn more in RedirectCallback.

SuspendedTextOutputCallback

Provides a message to display to the user when the authentication journey is suspended.

Callback output field Description

message

A string containing a message to display to the user.

messageType

A number indicating the severity of the message:

  • 0: Information

  • 1: Warning

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

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

Learn more in SuspendedTextOutputCallback.

TextOutputCallback

Provides a message to display to the user.

Callback output field Description

message

A string containing a message to display to the user.

messageType

A number indicating the severity of the message:

  • 0: Information

  • 1: Warning

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

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

Learn more in TextOutputCallback.

Backchannel callbacks

Nodes use these callbacks to recover additional information from the request, such as a header or a certificate.

HttpCallback

Accesses user credentials sent in the Authorization header:

Authorization: Basic bXlDbGllbnQ6Zm9yZ2Vyb2Nr

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

Learn more in HttpCallback.

LanguageCallback

Retrieves the locale from the request header for localizing text presented to the user.

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

Learn more in LanguageCallback.

ScriptTextOutputCallback

Inserts a script into the page presented to the user; for example, to collect data about the user’s environment.

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

Learn more in ScriptTextOutputCallback.

X509CertificateCallback

Retrieves an X.509 certificate, for example, from a header.

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

Learn more in X509CertificateCallback.

Authenticate endpoint parameters

To authenticate to Advanced Identity Cloud using REST, send an HTTP POST request to the json/authenticate endpoint. Specify the realm hierarchy, starting at the root; for example, /realms/root/realms/alpha.

The following list describes the json/authenticate endpoint parameters:

authIndexType

The authIndexType specifies the type of authentication the user will perform. Always use this parameter in conjunction with the authIndexValue to provide additional information about how the user is authenticating.

If not specified, PingOne Advanced Identity Cloud authenticates the user against the default journey configured for the realm.

The authIndexType can be one of the following:

composite_advice

When the authIndexType is composite_advice, the authIndexValue must be a URL-encoded composite advice string.

Use the composite_advice type to indicate which authentication services to use when logging in a user.

This example indicates that the user should authenticate through the myExampleJourney:

$ 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="AuthenticateToServiceConditionAdvice"/>
        <Value>myExampleJourney</Value>
      </AttributeValuePair>
</Advices>' \
'https://<tenant-env-fqdn>/am/json/realms/root/realms/alpha/authenticate'
This curl command URL-encodes the XML values. The --get option appends them as query string parameters to the URL.

Possible options for Advices are:

  • AuthenticateToServiceConditionAdvice. Requires the name of an authentication journey. For example:

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

  • AuthenticateToTreeConditionAdvice. Also requires the name of an authentication journey. For example:

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

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

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

  • 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, refer to Authorize one-time access with transactional authz.

You can specify multiple advice conditions. For example:

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

When the authIndexType is resource, the authIndexValue must be a URL protected by an PingOne Advanced Identity Cloud policy.

For example, to log into PingOne Advanced Identity Cloud using a policy matching the https://www.example.com resource, you could use the following:

$ curl \
--request POST \
--header 'Accept-API-Version: resource=2.0, protocol=1.0' \
'https://<tenant-env-fqdn>/am/json/realms/root/realms/alpha/authenticate?authIndexType=resource&authIndexValue=https%3A%2F%2Fwww.example.com'

Note that the resource must be URL-encoded. Authentication will fail if no policy matches the resource.

service

When the authIndexType is service, the authIndexValue is the journey PingOne Advanced Identity Cloud must use to authenticate the user.

For example, to authenticate using the built-in login authentication journey, you could use the following:

$ curl \
--request POST \
--header 'Accept-API-Version: resource=2.0, protocol=1.0' \
'https://<tenant-env-fqdn>/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.

If there are several authentication services that satisfy the authentication requirements, PingOne Advanced Identity Cloud presents them as a choice callback to the user. Return the required callbacks to PingOne Advanced Identity Cloud to authenticate.

Required: No.

authIndexValue

This parameter sets a value for the specific authIndexType.

Required: Yes, when using the authIndexType parameter.

noSession

When set to true, this parameter specifies that PingOne Advanced Identity Cloud 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: bjensen" \
--header "X-OpenAM-Password: Secret12!" \
'https://<tenant-env-fqdn>/am/json/realms/root/realms/alpha/authenticate?noSession=true'
{
  "successUrl": "/enduser/?realm=/alpha",
  "realm": "/alpha"
}

Required: No.

Client configuration reference

Enabled

Whether the provider is enabled.

Required: Yes.

Auth ID Key

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

Required: Yes.

Client ID

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

Required: Yes.

Client Secret

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

This property is deprecated. Use the Client Secret Label Identifier instead.

If you set a Client Secret Label Identifier and PingOne Advanced Identity Cloud finds a matching secret in a secret store, the Client Secret is ignored.

Required: No.

Client Secret Label Identifier

An identifier used to create a secret label for mapping to a secret in a secret store.

PingOne Advanced Identity Cloud uses this identifier to create a specific secret label for this service instance, using the template am.social.providers.identifier.secret where identifier is the value of Client Secret Label Identifier.

The identifier can only contain alphanumeric characters a-z, A-Z, 0-9, and periods (.). It can’t start or end with a period.

If you set a Client Secret Label Identifier and PingOne Advanced Identity Cloud finds a matching secret in a secret store, the Client Secret is ignored.

Required: No.

Authentication Endpoint URL

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

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

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

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 PingOne Advanced Identity Cloud; for example, https://<tenant-env-fqdn>/am?_realm=alpha. The URL is also registered in the identity provider’s service.

If you’re using an app built with the ForgeRock SDKs for Android or iOS, you can also use a custom URI scheme as the redirect 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. Refer to 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:

    • Incorrect:

      https://<tenant-env-fqdn>/am/oauth2/client/form_post/...

    • Correct:

      https://<tenant-env-fqdn>/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’s used as a redirect URL, you don’t have to specify the realm because Advanced Identity Cloud implicitly knows which realm to use.

Required: Yes.

Redirect after form post URL

The URL of a custom login page or application. Advanced Identity Cloud 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 Advanced Identity Cloud /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 Advanced Identity Cloud using custom login pages, such as apps using the Ping Identity SDKs, instead of the Advanced Identity Cloud admin UI.

    Required: No.

Scope Delimiter

The delimiter used to separate scope values. For example, a blank space (), or a comma character (,).

Most providers use a blank space.

Required: Yes.

OAuth Scopes

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

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 JWT Signing Algorithm field, enter the signing algorithm that PingOne Advanced Identity Cloud 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 PingOne Advanced Identity Cloud to sign authentication JWTs.

    Now you are ready to configure PingOne Advanced Identity Cloud 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.

    PingOne Advanced Identity Cloud 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:

    1. If you chose Direct AES Encryption method, select NONE in the JWT Signing Algorithm field. Signing is redundant with this encryption method.

    2. If you chose an encryption method different from the Direct AES Encryption method, configure signing. For more information, refer to How do I configure JWT authentication with signed JWTs?.

Required: Yes.

PKCE Method

Specifies the PKCE transformation method PingOne Advanced Identity Cloud 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

(OIDC providers only) Specifies whether PingOne Advanced Identity Cloud should provide a request object JWT to the provider. Possible values are:

NONE

PingOne Advanced Identity Cloud does not send a request object to the provider.

REFERENCE

The request object JWT is stored in PingOne Advanced Identity Cloud’s CTS token store, and PingOne Advanced Identity Cloud 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 PingOne Advanced Identity Cloud contains the 443 port. For example, https://platform.example.com:443/am.

To do this, configure the Base URL Source service:

  1. Under Native Consoles > Access Management, go to Realms > Realm Name > Services.

  2. Add a Base URL Source service (if one isn’t already configured) or select it to change its properties:

    A screenshot showing itsme example configuration details for the Base URL Source service.
VALUE

PingOne Advanced Identity Cloud 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 PingOne Advanced Identity Cloud 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 PingOne Advanced Identity Cloud to send signed request objects.

    Now you are ready to configure PingOne Advanced Identity Cloud 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.

    PingOne Advanced Identity Cloud 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:

    1. If you chose Direct AES Encryption method, select NONE in the JWT Signing Algorithm field. Signing is redundant with this encryption method.

    2. If you chose an encryption method different from the Direct AES Encryption method, configure signing. For more information, refer to 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

(OIDC providers only) A space-separated list, in order of preference, of the client’s acr values.

Required: No.

Well Known Endpoint

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

Leave this field empty for the LINE (Browser) configuration.

Required: No.

Request Object Audience

(OIDC providers only) 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

(OIDC providers only) Whether the provider encrypts ID Tokens.

How do I configure PingOne Advanced Identity Cloud to receive encrypted tokens?

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

(OIDC providers only) The issuer of ID Tokens.

Either specify a regular expression or a string value that must exactly match the value returned in the ID token, depending on the configuration of the Issuer comparison check setting.

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

Required: Yes.

Enable Native Nonce

(OIDC 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

(OIDC providers only) 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?

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

    PingOne Advanced Identity Cloud 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?

  1. Follow the steps in How do I configure the client to receive signed userinfo JWTs? to configure PingOne Advanced Identity Cloud to receive signed JWTs.

    Now you are ready to configure PingOne Advanced Identity Cloud to receive encrypted JWTs.

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

The URI that contains the public keys of the identity provider. PingOne Advanced Identity Cloud 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

The signing algorithm supported by the provider that Advanced Identity Cloud uses to sign the following:

  • Client authentication JWTs when Client Authentication Method is set to PRIVATE_KEY_JWT.

  • (OIDC 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

The encryption algorithm supported by the provider that PingOne Advanced Identity Cloud should use to encrypt client authentication JWTs when Client Authentication Method is set to PRIVATE_KEY_JWT, and (OIDC providers only) request JWTs when Request Parameter JWT Option is set to VALUE or REFERENCE.

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

Required: No.

JWT Encryption Method

The encryption algorithm supported by the provider that PingOne Advanced Identity Cloud should use to encrypt the following:

  • Client authentication JWTs when Client Authentication Method is set to PRIVATE_KEY_JWT.

  • (OIDC 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 PingOne Advanced Identity Cloud 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

(OIDC providers only) Specify the way the provider will return ID tokens to PingOne Advanced Identity Cloud. 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 journey 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.

Certificate Revocation Checking Options

Specify one or more options to be used by the TLS certificate revocation checking mechanism.

The possible values are:

  • ONLY_END_ENTITY: Only check the revocation status of end-entity certificates.

  • PREFER_CRLS: Prefer certificate revocation lists (CRLs) to Online Certificate Status Protocol (OCSP).

  • NO_FALLBACK: Disable the fallback mechanism.

  • SOFT_FAIL: Allow revocation check to succeed if the revocation status cannot be determined due to a network error.

  • DISABLE_REVOCATION_CHECKING: Disable all revocation checking.

Including DISABLE_REVOCATION_CHECKING as one of the options will prevent any revocation checking. For further details of the other options, refer to: PKIXRevocationChecker.Option.

If no options are selected, the default behavior is to enable revocation checking with SOFT_FAIL.

If the certificate does not specify any OCSP or CRL endpoints, the revocation checking will hard fail even if the SOFT_FAIL option is enabled. In this case, an administrator could disable revocation checking.

Use custom trust store

Specifies whether a custom truststore is used to verify the server certificate of the .well-known endpoint or JWKs URI of an OpenID provider (OP) in a TLS handshake.

If enabled, a secret label is generated dynamically using the alphanumeric characters of the client configuration name. For example, a client configuration called sampleOidcConfig results in a secret label named am.services.oidc.reliant.party.sampleOidcConfig.truststore.

Note that an administrator must map the generated secret label to an alias that exists in the realm secret store.

If this setting is not enabled, the default truststore is used to verify the server certificate.

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 by 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 to assess whether userinfo is provided.

How do I use a Scripted Decision node to check userinfo?

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

Add a Scripted Decision node to your journey that evaluates the flag and sets the outcome accordingly; for example:

  • Next-generation

  • Legacy

if (nodeState.get('nameEmptyOrNull')) {
  action.goTo("true");
} else {
  action.goTo("false");
}
var fr = JavaImporter(org.forgerock.openam.auth.node.api.Action);

if (nodeState.get('nameEmptyOrNull')) {
  action = fr.Action.goTo("true").build();
} else {
action = fr.Action.goTo("false").build();
}

You can now configure your journey to patch the userinfo object based on the outcome of the Scripted Decision node. 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 aren’t 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 more information, refer to 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.

PingOne Advanced Identity Cloud 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

A script to convert the provider’s raw profile object into a normalized object.

Each social identity provider returns different user profile information using their own attribute names.

For example, Google’s OIDC /userinfo endpoint returns claims, which PingOne Advanced Identity Cloud stores in a rawProfile object. The following google-profile-normalization.js script maps the attributes of this object to PingOne Advanced Identity Cloud profile attributes:

(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 containing normalized attributes in the following format: ("<platformAttributeName>", rawProfile.<providerAttributeName>)

Even if field names are the same, such as email and rawProfile.email, they still need to be mapped for them to be included in the returned JSON object.

PingOne Advanced Identity Cloud provides default scripts for other preconfigured identity providers. To view the bindings and expected return values, find the <identity provider>-profile-normalization.* scripts in Sample scripts.

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

When a user authenticates, the social authentication journey calls another transformation script set in the Social Provider Handler node to convert the attributes again; this time into an identity object that PingOne Advanced Identity Cloud can process.

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, or the 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 returns null as the value of the familyName for the identity, and social authentication fails.

Ensure all users have their social profiles configured correctly, or modify the transformation scripts so that they don’t collect null or empty attributes.

Required: Yes

Issuer comparison check

(OIDC providers only) Determines how the expected issuer value should match the actual value of the iss claim:

  • EXACT: PingOne Advanced Identity Cloud performs a string comparison between the expected and actual issuer values, which must result in an exact match.

  • REGEX: PingOne Advanced Identity Cloud evaluates the expected issuer value as a regular expression, against which the actual value must match.

    This lets social identity providers use a common issuer value for multiple tenants, which is replaced with a unique value during the OIDC authentication flow. For example, ^https://login.microsoftonline.com/(.*)/v2.0$ is successfully matched against https://login.microsoftonline.com/tenant-d5c6a592-eec6-47f0/v2.0.

    Consider the performance impact when constructing regular expressions as the comparison is performed for each social identity provider interaction.

    Also, ensure the regular expression is as specific as possible to avoid matching against incorrect issuer values.