Advanced Identity Cloud

Self-service reference

User self-service overview

User self-service lets users create and manage their own accounts, while you control the available features. You manage features and user journeys through the Advanced Identity Cloud admin UI.

Nodes for self-service journeys

The following nodes are designed for self-service journeys, although you can use them in any journey.

Accept Terms and Conditions node

Attribute Collector node

Attribute Present Decision node

Attribute Value Decision node

Consent Collector node

Create Object node

Display Username node

Email Suspend node

Email Template node

Identify Existing User node

Increment Login Count node

KBA Decision node

KBA Definition node

KBA Verification node

Login Count Decision node

Patch Object node

Platform Password node

Platform Username node

Profile Completeness Decision node

Query Filter Decision node

Required Attributes Present node

Select Identity Provider node

Social Provider Handler node

Terms and Conditions Decision node

Time Since Decision node

User self-service journeys are further extensible through ForgeRock Marketplace nodes.

The following journeys are explored in this section:

Registration

The sample Registration journey describes a basic registration flow, where Ping Identity Platform prompts the user to provide several profile attributes, then attempts to create the user and log the user in. For details, refer to User self-registration. For more information about configuring registration to include social identity providers, refer to Social authentication.

Login

The sample Login journey describes a basic login flow, where the user is prompted to provide a username and password, then passed to a progressive profile journey before being logged in. For details, refer to Login with self-service. For more information about including social identity providers in a login journey, refer to Social authentication.

Progressive Profiles

The sample Progressive Profile journey is called by the Login journey sample. It checks the login count to check whether further action is needed. If no action is required, it returns to the Login journey to complete logging in. If the specified number of logins is reached, it instead checks whether user preferences have been set, and if not, prompts the user to set those preferences. It then returns to the Login journey to finish logging in. For more information about using progressive profiling, refer to Progressive profile.

Password Reset

The Password Reset sample journey provides a method for users to reset their password by providing their email and answering some security questions. If the questions are answered correctly, the user is emailed a password reset link, which they must click to proceed. They are then presented with a password prompt to enter a new password. For more information, refer to Password reset.

Forgotten Username

The Forgotten Username sample journey gives users a method to recover their username by entering an email address. If the email address is associated with a user account, the account’s username will be emailed to the user. The email includes a link to log in, which will take the user through the Login journey. For more information, refer to Username recovery.

Update Password

The Update Password sample journey lets users change their passwords. The journey assumes that the user has already logged in successfully. It checks the user’s session data and, if the session is valid, prompts the user to update their password. For more information, refer to Password updates.

User self-registration

User self-registration lets your users create their own accounts. To configure registration, your registration journey requires at least the following nodes:

Platform Username node

If you have changed the userName attribute to something else, you must configure this node to use the new attribute; for example, if you changed your configuration to use the mail attribute instead.

Attribute Collector node

This collects information from the user for any attributes that are required to create the user profile.

By default, required attributes include userName, givenName, sn (surname), and mail (email). The node can collect optional attributes as well, as long as any required attributes are collected.

Create Object node

This creates the user in IDM.

All other nodes are technically optional. Some are strongly encouraged; for example, if you don’t include a Platform Password node, the user won’t have a password to sign in. The Platform Password node isn’t necessary, however, when you provide some other authentication method, such as social identity providers, or you generate a password for the user.

Nodes that present or collect information each display on their own page by default. To collect multiple nodes into one page, place these nodes in a Page node. There are some limitations to consider when adding nodes to a Page node:

Example registration journey

Common nodes in a registration journey include:

CAPTCHA services

CAPTCHA is a way to challenge a user to verify that they are human, and includes a number of different services. Choose the CAPTCHA service that best suits your requirements. The default configuration in the CAPTCHA node is for Google’s reCAPTCHA service. The node has been tested for use with reCAPTCHA v2 and hCaptcha v1. Other services should work, as long as they follow a similar configuration pattern.

You will need to provide a CAPTCHA Site Key and CAPTCHA Secret Key. The rest of CAPTCHA configuration is done through the service that you are using.

Security questions

Security questions let a user provide answers to questions that can later be used to verify their identity. This process is also called Knowledge-Based Authentication (KBA).

Configuration

To configure security questions, select Security > Security Questions. From here, you can configure the questions that are presented to users, and how they should be handled.

  1. Click Add Question to set additional questions for the user.

    On the Add a Security Question form, select a locale, and provide the question text for that locale. When you have added the localized text for your question, click Add, then repeat for each locale. When you have completed the new question, click Done.

  2. On the Settings tab, set the following:

    • Must define refers to the minimum number of security questions the user must set up during registration.

    • Must answer refers to the minimum number of questions the user must answer to satisfy a security prompt.

    • Lockout specifies the number of failed attempts to answer a security question before the user is unable to try again.

Once you deploy these security questions, never remove or change existing security questions, as users might have included those questions during the user self-registration process.

Associated nodes

There are three nodes associated with KBA:

KBA Definition node

The KBA Definition node is used during registration. It prompts the user to choose security questions, and define answers to these questions for use during identity verification. The questions are selectable from a list. The list also includes an option to define their own question, if they want.

KBA Verification node

The KBA Verification node is used to verify a user’s identity using security questions, such as during a Reset Password journey. It displays the number of questions set in the Must Answer field in the Security Questions settings. If the user has defined answers for more questions than is required, which questions will be displayed are randomized.

KBA Decision node

The KBA Decision node is primarily used in cases of a Progressive Profile journey, where you ensure a user has defined answers to the minimum number of questions required by the system. This can be useful if the number of questions changes, so the user can be prompted to fill out any necessary additional questions when they next log in. In this case, the KBA Decision node would be used together with the KBA Definition node; if the KBA Decision node evaluates false, the user would then be taken to the KBA Definition node.

Terms and conditions

Terms and conditions display the terms and conditions for using your service. Terms and conditions are not considered optional; users must accept the terms before they are able to progress in the account creation process.

Configuration

To set up terms and conditions:

  1. Select Terms & Conditions and click + New Version.

  2. Enter a version number for the new terms and conditions, then click Next.

    Terms and conditions are tracked using versioning. The default placeholder set of terms and conditions has a version of 0.0, but the versioning can follow other patterns, such as dates.

  3. Enter the locale for which these terms and conditions apply, expressed as its ISO 639-1 code (for example, en or fr), then click Add.

  4. Enter the text of your terms and conditions:

    • Terms and conditions content is formatted using Markdown. You can also use HTML formatting, which is converted into Markdown when you save or publish. Refer to Terms and conditions content formatting.

      When using HTML formatting, id and style attributes are stripped out when Advanced Identity Cloud converts the HTML formatting to Markdown. However, you can use the following techniques to emulate id and style attributes:

      • To link to different parts of the terms and conditions content, use the formatted header IDs in the HTML output. Refer to Link to terms and conditions content.

      • To apply CSS styles to the terms and conditions content, use the styles editor.

    • Click Styles to switch to the styles editor. Then, enter additional CSS styles to apply to the HTML that is rendered from the Markdown.

    • The text supports localization. When you have added the terms and conditions for this locale, click Locale: locale-name, then click + Add locale to add the text for another locale.

    • Click Try it out to check how your terms and conditions appear to users.

  5. Save or publish the new version.

    When you have published a version, the terms and conditions cannot be edited. Be sure to proofread your text before publishing.

    • Click Save as Draft to save this version for future publication. You can edit a draft version.

    • Click Publish to publish this version.

      Select Set as Active Version to make this the active version of your terms and conditions. Only one version of terms and conditions can be active at a time, for each locale. Selecting this option will deactivate the currently active version, and make this version active instead.

Associated nodes

There are two nodes associated with terms and conditions:

Accept Terms and Conditions node

The Accept Terms and Conditions node presents the user with a notice that continuing means they agree with the terms and conditions you have set, along with a link to view the terms and conditions, and a button to continue. Because this node includes a button to continue by default, it should generally be the last node in a Page node, or on its own page. It will automatically make use of the terms and conditions version that is currently active; you do not need to specify the version in the node.

Terms and Conditions Decision node

The Terms and Conditions Decision node is used in progressive profile journeys, where you want to confirm that the user has accepted the currently active terms and conditions. If the terms and conditions version has been updated, the decision will evaluate to false, which when connected to the Accept Terms and Conditions node, will present the user an opportunity to accept the new terms and conditions.

Terms and conditions content formatting

The editor primarily uses Markdown to format the terms and conditions content.

You can also use HTML to add formatting to all or part of the content, but HTML is only a convenient input method, and the editor converts it to Markdown when you save or publish the content. This strips out any attributes in your HTML formatting, including id and style attributes.

Some HTML elements, such as definition lists, cannot be converted into Markdown, as there is no Markdown equivalent. These HTML elements are not converted and remain as HTML in the terms and conditions content.

Link to terms and conditions content

To display the terms and conditions content to the end user, the UI renders it from Markdown into HTML. When it renders the HTML output, it creates id attributes, but only on the header elements. To create a formatted value for each id attribute, it starts with the header element value, converts it to lower case, and then removes spaces and special characters (except underscores).

Here are some examples:

Markdown Formatted header ID HTML output

# Example 123

example123

<h1 id="example123">Example 123</h1>

# Example!

example

<h1 id="example">Example!</h1>

# Example -/=()%^&\*@£

example

<h1 id="example">Example -/=()%^&\*@£</h1>

# Example_1

example_1

<h1 id="example_1">Example_1</h1>

# Example -/=()%^&\*@£_ Example

example_example

<h1 id="example_example">Example -/=()%^&\*@£_ Example</h1>

To link to different parts of the terms and conditions content, you must therefore find the formatted header IDs in the HTML output and use them in your HTML anchors.

Privacy and consent, in the context of registration and self-service, refers to presenting users with information about which external resources their information may be shared with, such as sales and marketing services. The Ping Identity Platform manages these connections in IDM, where consent is configured per external connection, or mapping. A mapping refers to the user’s information, mapped to related fields in an external service, which is then synchronized by IDM. For more information, refer to Resource mapping.

Configuration

To enable consent for a mapping:

  1. Select Configure > Mappings, then select Edit on the mapping that you want to configure.

  2. Select the Advanced tab, then enable Enable Privacy & Consent.

The above steps assume you have already created at least one mapping. You can also enable privacy and consent when creating the mapping: the same Enable Privacy & Consent switch is present when you click Create Mapping during the mapping creation process.

Associated nodes

There is one node associated with privacy and consent:

Consent Collector node

The Consent Collector node presents the user with a list of all the mappings the user is affected by that have privacy and consent enabled. Each mapping can be individually selected or disabled; if you require all mappings to be allowed, there is an option in the node to make all mappings required.

The node can be used during registration or during progressive profile journeys. If using this node in a progressive profile journey, you will need to use the Query Filter Decision node to check for the presence of your desired mappings in the user’s consentedMappings attribute.

Example registration REST output

When calling a registration self-service endpoint, you will receive a JSON object back, containing callbacks for each of the nodes included in the registration journey.

Sample JSON callbacks 
{
  "authId": "<omitted for length>",
  "callbacks": [
    {
      "type": "ValidatedCreateUsernameCallback",
      "output": [
        {
          "name": "policies",
          "value": {
            "policyRequirements": [
              "REQUIRED",
              "MIN_LENGTH",
              "VALID_TYPE",
              "UNIQUE",
              "CANNOT_CONTAIN_CHARACTERS"
            ],
            "fallbackPolicies": null,
            "name": "userName",
            "policies": [
              {
                "policyRequirements": [
                  "REQUIRED"
                ],
                "policyId": "required"
              },
              {
                "policyRequirements": [
                  "REQUIRED"
                ],
                "policyId": "not-empty"
              },
              {
                "policyRequirements": [
                  "MIN_LENGTH"
                ],
                "policyId": "minimum-length",
                "params": {
                  "minLength": 1
                }
              },
              {
                "policyRequirements": [
                  "VALID_TYPE"
                ],
                "policyId": "valid-type",
                "params": {
                  "types": [
                    "string"
                  ]
                }
              },
              {
                "policyId": "unique",
                "policyRequirements": [
                  "UNIQUE"
                ]
              },
              {
                "policyId": "no-internal-user-conflict",
                "policyRequirements": [
                  "UNIQUE"
                ]
              },
              {
                "policyId": "cannot-contain-characters",
                "params": {
                  "forbiddenChars": [
                    "/"
                  ]
                },
                "policyRequirements": [
                  "CANNOT_CONTAIN_CHARACTERS"
                ]
              }
            ],
            "conditionalPolicies": null
          }
        },
        {
          "name": "failedPolicies",
          "value": []
        },
        {
          "name": "validateOnly",
          "value": false
        },
        {
          "name": "prompt",
          "value": "Username"
        }
      ],
      "input": [
        {
          "name": "IDToken1",
          "value": ""
        },
        {
          "name": "IDToken1validateOnly",
          "value": false
        }
      ],
      "_id": 0
    },
    {
      "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": "IDToken2",
          "value": ""
        },
        {
          "name": "IDToken2validateOnly",
          "value": false
        }
      ],
      "_id": 1
    },
    {
      "type": "StringAttributeInputCallback",
      "output": [
        {
          "name": "name",
          "value": "sn"
        },
        {
          "name": "prompt",
          "value": "Last Name"
        },
        {
          "name": "required",
          "value": true
        },
        {
          "name": "policies",
          "value": {
            "policyRequirements": [
              "REQUIRED",
              "VALID_TYPE"
            ],
            "fallbackPolicies": null,
            "name": "sn",
            "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": "IDToken3",
          "value": ""
        },
        {
          "name": "IDToken3validateOnly",
          "value": false
        }
      ],
      "_id": 2
    },
    {
      "type": "StringAttributeInputCallback",
      "output": [
        {
          "name": "name",
          "value": "mail"
        },
        {
          "name": "prompt",
          "value": "Email Address"
        },
        {
          "name": "required",
          "value": true
        },
        {
          "name": "policies",
          "value": {
            "policyRequirements": [
              "REQUIRED",
              "VALID_TYPE",
              "VALID_EMAIL_ADDRESS_FORMAT"
            ],
            "fallbackPolicies": null,
            "name": "mail",
            "policies": [
              {
                "policyRequirements": [
                  "REQUIRED"
                ],
                "policyId": "required"
              },
              {
                "policyRequirements": [
                  "VALID_TYPE"
                ],
                "policyId": "valid-type",
                "params": {
                  "types": [
                    "string"
                  ]
                }
              },
              {
                "policyId": "valid-email-address-format",
                "policyRequirements": [
                  "VALID_EMAIL_ADDRESS_FORMAT"
                ]
              }
            ],
            "conditionalPolicies": null
          }
        },
        {
          "name": "failedPolicies",
          "value": []
        },
        {
          "name": "validateOnly",
          "value": false
        },
        {
          "name": "value",
          "value": ""
        }
      ],
      "input": [
        {
          "name": "IDToken4",
          "value": ""
        },
        {
          "name": "IDToken4validateOnly",
          "value": false
        }
      ],
      "_id": 3
    },
    {
      "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": "IDToken5",
          "value": false
        },
        {
          "name": "IDToken5validateOnly",
          "value": false
        }
      ],
      "_id": 4
    },
    {
      "type": "BooleanAttributeInputCallback",
      "output": [
        {
          "name": "name",
          "value": "preferences/updates"
        },
        {
          "name": "prompt",
          "value": "Send me news and updates"
        },
        {
          "name": "required",
          "value": true
        },
        {
          "name": "policies",
          "value": {}
        },
        {
          "name": "failedPolicies",
          "value": []
        },
        {
          "name": "validateOnly",
          "value": false
        },
        {
          "name": "value",
          "value": false
        }
      ],
      "input": [
        {
          "name": "IDToken6",
          "value": false
        },
        {
          "name": "IDToken6validateOnly",
          "value": false
        }
      ],
      "_id": 5
    },
    {
      "type": "ValidatedCreatePasswordCallback",
      "output": [
        {
          "name": "echoOn",
          "value": false
        },
        {
          "name": "policies",
          "value": {
            "policyRequirements": [
              "REQUIRED",
              "MIN_LENGTH",
              "VALID_TYPE",
              "AT_LEAST_X_CAPITAL_LETTERS",
              "AT_LEAST_X_NUMBERS",
              "CANNOT_CONTAIN_OTHERS"
            ],
            "fallbackPolicies": null,
            "name": "password",
            "policies": [
              {
                "policyRequirements": [
                  "REQUIRED"
                ],
                "policyId": "not-empty"
              },
              {
                "policyRequirements": [
                  "MIN_LENGTH"
                ],
                "policyId": "minimum-length",
                "params": {
                  "minLength": 8
                }
              },
              {
                "policyRequirements": [
                  "VALID_TYPE"
                ],
                "policyId": "valid-type",
                "params": {
                  "types": [
                    "string"
                  ]
                }
              },
              {
                "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": "IDToken7",
          "value": ""
        },
        {
          "name": "IDToken7validateOnly",
          "value": false
        }
      ],
      "_id": 6
    },
    {
      "type": "KbaCreateCallback",
      "output": [
        {
          "name": "prompt",
          "value": "Select a security question"
        },
        {
          "name": "predefinedQuestions",
          "value": [
            "What's your favorite color?",
            "Who was your first employer?"
          ]
        }
      ],
      "input": [
        {
          "name": "IDToken8question",
          "value": ""
        },
        {
          "name": "IDToken8answer",
          "value": ""
        }
      ],
      "_id": 7
    },
    {
      "type": "KbaCreateCallback",
      "output": [
        {
          "name": "prompt",
          "value": "Select a security question"
        },
        {
          "name": "predefinedQuestions",
          "value": [
            "What's your favorite color?",
            "Who was your first employer?"
          ]
        }
      ],
      "input": [
        {
          "name": "IDToken9question",
          "value": ""
        },
        {
          "name": "IDToken9answer",
          "value": ""
        }
      ],
      "_id": 8
    },
    {
      "type": "TermsAndConditionsCallback",
      "output": [
        {
          "name": "version",
          "value": "0.0"
        },
        {
          "name": "terms",
          "value": "Example terms..."
        },
        {
          "name": "createDate",
          "value": "2019-10-28T04:20:11.320Z"
        }
      ],
      "input": [
        {
          "name": "IDToken10",
          "value": false
        }
      ],
      "_id": 9
    }
  ],
  "header": "Sign Up",
  "description": "Signing up is fast and easy.<br>Already have an account? <a href='#/service/Login'>Sign In</a>"
}

Social authentication

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

These topics describe the high-level steps to configure social authentication.

Configure social identity providers

PingOne Advanced Identity Cloud supports social identity providers that are OAuth 2.0 or OpenID Connect (OIDC) 1.0-compliant.

Default social identity provider configurations

A number of social identity providers are configured by default:

Identity provider Specification Configuration ID

Amazon

OAuth 2.0

amazonConfig

Apple

OIDC

appleConfig

Facebook

OAuth 2.0

facebookConfig

Google

OIDC

googleConfig

Instagram

OAuth 2.0

instagramConfig

LINE (Browser)

OIDC

lineBrowserConfig

LINE (Native)

OIDC

lineNativeConfig

LinkedIn (Legacy) (2)

OAuth 2.0

linkedInConfig

LinkedIn

OIDC

linkedInV2Config

Microsoft

OAuth 2.0

microsoftConfig

Salesforce

OAuth 2.0

salesforceConfig

Twitter

OAuth 2.0

twitterConfig

VK (Vkontakte)

OAuth 2.0

vkConfig

WeChat

OAuth 2.0

weChatConfig

WordPress

OAuth 2.0

wordpressConfig

Yahoo

OIDC

yahooConfig

itsme(1)

OIDC

itsmeConfig

(1) To integrate with itsme, you must obtain an Organization Validation (OV) certificate.

(2) The OAuth 2.0 version of the profile is deprecated by LinkedIn.

Custom social identity provider configurations

You can add providers that aren’t configured by default, as long as these providers use OAuth 2.0 or OpenID Connect:

Identity provider Specification Configuration ID

Any social identity provider that implements the OAuth 2.0 specification.

OAuth 2.0

oauth2Config

Any social identity provider that implements the OIDC specification.

OIDC

oidcConfig

Add identity providers

  1. Register a service in the identity provider, and keep the provider’s documentation within reach. You will use it during this procedure.

    At minimum, you must have a client ID and a redirect URL.

    A redirect URL is a path in PingOne Advanced Identity Cloud (AM) where the identity provider redirects the user on successful authentication; for example, https://<tenant-env-fqdn>/am.

    Depending on the social identity provider and on your environment, you change the redirect URL later.

    The redirect URL in the identity provider service and in the PingOne Advanced Identity Cloud client configuration must match.

    Some providers require you to enable a specific setting or API in their service:

    Google

    Enable the Gmail API in the Google Cloud Platform.

    Apple

    You must have access to the Apple Development Program (Enterprise program isn’t eligible), and you must enable Sign In With Apple in the Apple Developer site.

    LINE

    You must apply for permission for your LINE channel to access a user’s email address using OIDC:

    1. In the LINE Developers console, enable Email address permission.

    2. Agree to the terms and conditions, and follow the steps to complete the application.

    3. The console displays Applied when your application is accepted.

    If you don’t have email permission, the registration will fail with an Invalid Attribute Syntax error.

  2. In the AM admin UI, go to Realms > Realm Name > Services.

  3. Click Social Identity Provider Service.

  4. Go to the Secondary Configurations tab.

    PingOne Advanced Identity Cloud includes scripts and configurations for several common identity providers.

  5. In the Add a Secondary Configuration drop-down list, select the required identity provider.

    If the required provider doesn’t appear, select one of the following to add a custom identity provider client:

    • Client Configuration for providers that implement the OAuth2 specification

    • Client Configuration for providers that implement the OpenID Connect specification

  6. Provide the client’s required configuration details, such as the Client ID, Client Secret (for confidential clients), the Scope Delimiter (usually an empty space), and the Redirect URL.

    For OAuth 2.0 social identity providers, store the client secret in a secret store for greater security.

    Use the Client Secret Label Identifier to create a dynamic secret label to map to an alias for the secret.

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

    Don’t worry if some details are missing. You can edit the configuration later after saving the client profile for the first time.

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

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

    To find the required identity provider information:

    • Refer to the provider’s documentation.

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

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

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

      Keep their documentation close while configuring the client profile.

    • Visit the provider’s .well-known endpoint.

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

      PingOne Advanced Identity Cloud is preconfigured, but you must make sure the settings for the provider haven’t changed. Key preconfigured fields include:

      • The provider’s URLs.

        For example, Authentication Endpoint URL, Access Token Endpoint URL, and User Profile Service URL.

      • The OAuth Scopes field.

      • The Well Known Endpoint for retrieving information about the provider.

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

      • The configuration in the UI Config Properties section.

      • The script selected in the Transform Script drop-down list.

        This script is responsible for mapping attributes provided by the identity providers to a profile format compatible with PingOne Advanced Identity Cloud.

        For details, refer to Transform Script.

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

      • Several capabilities in the identity provider client share the same secret IDs. For example, signing request objects and signing client authentication JWTs.

      • Every identity provider client in a realm shares the same secrets.

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

      For more information, refer to the page about the /oauth2/connect/rp/jwk_uri endpoint.

      For details about client configuration settings, refer to Client configuration reference.

  8. Save your changes.

    Proceed to Configure basic social registration journeys.

Configure basic social registration journeys

There are two nodes associated with identity providers:

Select Identity Provider node

The Select Identity Provider node prompts the user to select a social identity provider for registration or sign in, or (optionally) to continue with local registration or sign in.

When the user selects a provider, the journey continues to the Social Provider Handler node.

Social Provider Handler node

The Social Provider Handler node communicates with the selected provider and collects the information provided after the user has authorized the service. It runs the provider’s configured normalization script to map the information into a format that PingOne Advanced Identity Cloud can consume.

Next, the node uses a transformation script provided by PingOne Advanced Identity Cloud called Normalized Profile to Managed User to transform the profile information into a managed object.

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

Set up a basic social registration journey

  1. In your realm, go to Journeys.

    You can create a new journey, modify an existing journey, or duplicate an existing journey.

  2. Decide whether users can log in with their local credentials, and add the relevant nodes to the journey:

    • Social authentication journeys allowing local authentication might look like the following:

      Example social authentication with local authentication

    • Social authentication journeys enforcing social authentication login might look like the following:

      Example social authentication enforcing social login

    To configure either option, set Include local authentication in the Select Identity Provider node. To support both local and social authentication in the same page, use the Page node as shown in the example.

  3. Configure the Social Provider Handler node:

    • In the Transformation Script field, select Normalized Profile to Managed User. This script transforms the normalized identity provider’s profile object into a format that PingOne Advanced Identity Cloud can use.

      To view the script and the available bindings, refer to normalized-profile-to-managed-user.js.

    • In Client Type, select BROWSER when using the PingOne Advanced Identity Cloud UI or ForgeRock SDK for JavaScript, or NATIVE when using the ForgeRock SDKs for Android or iOS.

  4. Configure the Required Attributes Present node and the Create Object node:

    In the Identity Resource fields of each, configure the relevant managed identity resource type, such as managed/alpha_user.

    To check for the available managed identity resource types, go to the IDM admin UI, and open the Manage drop-down list.

    Identity managed object types are preceded by the icon.

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

Configure social registration with account claiming

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

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

Example social registration with account claiming
Figure 1. Example social registration with account claiming

The journey uses the Identify Existing User node to determine if the user is already registered in PingOne Advanced Identity Cloud. By default, the node checks that the email address associated with the account is already registered in PingOne Advanced Identity Cloud.

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

Refer to Set up a basic social registration journey for tips.

Let users connect through their profile page

To let users connect to social identity providers through the End User UI profile page, add a mapping for your social authentication journey:

  1. From the left navigation pane, click Services.

  2. Select Self Service Trees.

  3. Set a new key and value and click + Add:

    Key

    connectSocial

    Value

    The name of the journey

  4. Click Save Changes.

Login with self-service

Configure social identity providers

To include social identity providers as a method of authentication, configure the Social Identity Provider Service in AM to include either some form of social registration or social account claiming. For more information, refer to Social authentication. Once this is set up, add social identity provider support to your login journey.

  1. To get started with social logins, you can create a new journey, modify the existing login journey, or duplicate the login journey and modify that.

    This example uses the following nodes:

  2. Connect the starting node to the Page node.

  3. Connect the Social Authentication output on the Page node to the Social Provider Handler node.

  4. On the Social Provider Handler node, connect the Account Exists output to the Increment Login Count node. Connect the No Account Exists output to the Failure node.

  5. On the Page node, connect the Local Authentication node to the Data Store Decision node.

  6. On the Data Store Decision node, connect the True output to the Increment Login Count node. Connect the False output to the Failure node.

  7. Connect the Increment Login Count node to the Inner Tree Evaluator node node.

  8. The Inner Tree Evaluator node node points to another journey, letting you chain multiple journeys together.

    By default, this is set to point to the ProgressiveProfile journey. For more information about progressive profiles, refer to Progressive profile.

    Connect the Inner Tree Evaluator node node to the Success node.

The resulting login journey will look something like this:

Example login journey with social identity providers enabled

Example login REST output

When calling a login self-service endpoint, you will receive a JSON object back, containing callbacks for each of the nodes included in the login journey.

Sample JSON callbacks 
{
  "authId": "<omitted for length>",
  "callbacks": [
    {
      "type": "ValidatedCreateUsernameCallback",
      "output": [
        {
          "name": "policies",
          "value": {}
        },
        {
          "name": "failedPolicies",
          "value": []
        },
        {
          "name": "validateOnly",
          "value": false
        },
        {
          "name": "prompt",
          "value": "Username"
        }
      ],
      "input": [
        {
          "name": "IDToken1",
          "value": ""
        },
        {
          "name": "IDToken1validateOnly",
          "value": false
        }
      ],
      "_id": 0
    },
    {
      "type": "ValidatedCreatePasswordCallback",
      "output": [
        {
          "name": "echoOn",
          "value": false
        },
        {
          "name": "policies",
          "value": {}
        },
        {
          "name": "failedPolicies",
          "value": []
        },
        {
          "name": "validateOnly",
          "value": false
        },
        {
          "name": "prompt",
          "value": "Password"
        }
      ],
      "input": [
        {
          "name": "IDToken2",
          "value": ""
        },
        {
          "name": "IDToken2validateOnly",
          "value": false
        }
      ],
      "_id": 1
    }
  ],
  "header": "Sign In",
  "description": "New here? <a href=\"#/service/Registration\">Create an account</a><br><a href=\"#/service/ForgottenUsername\">Forgot username?</a> <a href=\"#/service/ResetPassword\">Forgot password?</a>"
}

Progressive profile

Progressive profile refers to the ability to ask users to provide additional profile information over time, or to update existing information when needed. The sample Progressive Profile journey checks the number of logins, and prompts the user to add their marketing preferences if they haven’t already. There are a wide variety of other ways you can configure a progressive profile flow, however.

Progressive profile journeys generally aren’t directly linked. Instead, they are included inside other journeys, using the Inner Tree Evaluator node. You can connect multiple Inner Tree Evaluator nodes together, which can help you keep different progressive profile behaviors organized into their own journeys.

Sample progressive profile journey

The following nodes are associated with progressive profiles:

Attribute Present Decision node

The Attribute Present Decision node checks whether the specified attribute is present. It does not check the value of the attribute, only that the attribute exists. This can include attributes that might otherwise be private. A common use case for this node is when you want to check for the presence of a password.

Attribute Value Decision node

The Attribute Value Decision node checks the value of the specified attribute, and determines if it satisfies the conditions configured in the node. It can perform two types of comparison operations:

  • Check whether an attribute is present.

  • Check whether the value of an attribute equals a value specified in the node.

Like the Attribute Present Decision node, one of the possible conditions you can set is whether an attribute is present. Unlike the Attribute Present Decision node, this will not work on private attributes.

KBA Decision node

The KBA Decision node is primarily used in a progressive profile journey where you want to ensure a user has defined answers to the minimum number of questions required by the system. This can be useful if the number of questions changes, so the user can be prompted for any necessary additional responses when they next log in. In this case, the KBA Decision node would be used together with the KBA Definition node: if the KBA Decision node evaluates false, the user would then be taken to the KBA Definition node.

Login Count Decision node

The Login Count Decision node checks whether the user has logged in the specified number of times. It can either be triggered once (using the AT interval), or triggered repeatedly after a set number of logins (using the EVERY interval). The login count is not automatically incremented: be sure to include the Increment Login Count node in your login journey if you plan to use this node.

Profile Completeness Decision node

The Profile Completeness Decision node checks how complete a user’s profile is, and compares that amount with a percentage value set in the node. The value for profile completeness is based on the number of visible, user-editable attributes in their profile that have been filled out.

Query Filter Decision node

The Query Filter Decision node uses a query filter to check a user’s profile for specific information. Use this to check whether a particular field has been filled out, or that the contents of a field match a specific pattern. For instance, you can use this in progressive profile journeys to check if marketing preferences are set on a user’s profile. For more information on constructing effective query filters, refer to Construct queries.

Terms and Conditions Decision node

The Terms and Conditions Decision node verifies the user has accepted the currently active set of terms and conditions. Use this node when you want to verify the user has accepted your current terms and conditions before proceeding. Use this with the Accept Terms and Conditions node: connect the Terms and Conditions Decision node False output to an Accept Terms and Conditions node.

Time Since Decision node

The Time Since Decision node checks the user’s creation date against a specified amount of time. This is used when you want to have a time-based reminder for users to check an attribute. Once the specified amount of time has elapsed, the node evaluates to True the next time the node is triggered, for example, by the user logging in and going through a progressive profile journey.

Password reset

Password reset lets users reset their password without assistance from an administrator. The Ping Identity Platform includes a sample reset password journey, which requests a user’s email address, checks if a user with that email exists, and if so, emails a reset link to the user. The journey then waits until the user clicks the link before presenting a password reset prompt.

Sample reset password journey

Make sure the Patch Object node's Patch As Object field is not selected (equivalent to false).

Example reset password REST output

When calling a reset password self-service endpoint, you will receive a JSON object back, containing callbacks for each of the nodes included in the reset password journey.

Sample JSON callbacks 
{
  "authId": "<omitted for length>",
  "callbacks": [
    {
      "type": "StringAttributeInputCallback",
      "output": [
        {
          "name": "name",
          "value": "mail"
        },
        {
          "name": "prompt",
          "value": "Email Address"
        },
        {
          "name": "required",
          "value": true
        },
        {
          "name": "policies",
          "value": {}
        },
        {
          "name": "failedPolicies",
          "value": []
        },
        {
          "name": "validateOnly",
          "value": false
        },
        {
          "name": "value",
          "value": ""
        }
      ],
      "input": [
        {
          "name": "IDToken1",
          "value": ""
        },
        {
          "name": "IDToken1validateOnly",
          "value": false
        }
      ],
      "_id": 0
    }
  ],
  "header": "Reset Password",
  "description": "Enter your email address or <a href=\"#/service/Login\">Sign in</a>"
}

Username recovery

Username recovery lets the user recover their username, using other information they remember, such as their email address. The Ping Identity Platform includes a sample Forgotten Username journey that is used for this purpose. It collects a user’s email address, then uses that to search for a user with that address. It then emails the user the username associated with that email address. An alternative journey is to send a verification link, then use the Display Username node once the user returns from the email.

When reviewing the sample journey, notice that both Identify Existing User node outputs connect to the Email Suspend node.

This is recommended behavior for security reasons. If you return different outcomes, you can potentially expose which users have accounts in your system.
Sample forgotten username journey

Example forgotten username REST output

When calling a username recovery self-service endpoint, you will receive a JSON object back, containing callbacks for each of the nodes included in the username recovery journey.

Sample JSON callbacks 
{
  "authId": "<omitted for length>",
  "callbacks": [
    {
      "type": "StringAttributeInputCallback",
      "output": [
        {
          "name": "name",
          "value": "mail"
        },
        {
          "name": "prompt",
          "value": "Email Address"
        },
        {
          "name": "required",
          "value": true
        },
        {
          "name": "policies",
          "value": {}
        },
        {
          "name": "failedPolicies",
          "value": []
        },
        {
          "name": "validateOnly",
          "value": false
        },
        {
          "name": "value",
          "value": ""
        }
      ],
      "input": [
        {
          "name": "IDToken1",
          "value": ""
        },
        {
          "name": "IDToken1validateOnly",
          "value": false
        }
      ],
      "_id": 0
    }
  ],
  "header": "Forgotten Username",
  "description": "Enter your email address or <a href=\"#/service/Login\">Sign in</a>"
}

Password updates

Password updates provide a method for the user to update their password without assistance from an administrator. The Ping Identity Platform includes a sample Update Password journey. Unlike the other sample self-service journeys, the update password journey assumes the user is already logged in, and gets the user’s current session data to identify the user. It then presents a prompt to update the user’s password, and uses a Patch Object node to update the password in IDM. An example of where you might use a journey like this is in an update password link placed in the user’s profile or settings.

Sample update password journey

Make sure that the Patch Object node's Patch As Object field is not selected (equivalent to false).

Scripting tips

Access IDM properties in scripts

User self-service journeys primarily use PingIDM nodes.

Nodes save data in the shared state of journeys. PingIDM nodes save data in the shared state differently than other nodes.

You can extend the functionality of journeys using scripts you write in the Scripted Decision node.

When you use a Scripted Decision node node to access properties saved in the shared state by PingIDM nodes, you must reference the IDM properties using the objectAttrbutes object.

For example, to access the first name (givenName) from the shared state, returned from an PingIDM node, you would use the syntax:

var firstName = objectAttributes.get("givenName").asString();

For information on how to access IDM properties in scripts and the shared state, refer to auth scripting.