User self-service overview
User self-service lets end users create and manage their own accounts, while you control the available features. You manage features and end-user journeys through the Advanced Identity Cloud admin console.
Nodes for self-service journeys
The following nodes are designed for self-service journeys, although you can use them in any journey.
User self-service journeys are further extensible through Marketplace nodes.
Journey templates for user self-service
The following journey templates are included with Advanced Identity Cloud:
- Registration
-
The Registration journey describes a basic registration flow, where Advanced Identity Cloud prompts the end user to provide several profile attributes, then attempts to create and sign-on the end user.
Learn more in User self-registration.
Learn more about configuring registration to include social identity providers in Social authentication.
- Login
-
The Login journey describes a basic sign-on flow, where the end user is prompted to provide a username and password, then passed to a progressive profile journey before being signed on.
Learn more in Sign-on (login).
Learn more about including social identity providers in a sign-on journey in Social authentication.
- ProgressiveProfile
-
The ProgressiveProfile journey is called by the Login journey. It checks whether the successful sign-on count has reached a specified number. If it has reached the specified number, and end-user preferences have not been set, the end user is prompted to set those preferences. If it has not reached the specified number, the end user is returned to the Login journey to complete signing on.
Learn more in Progressive profile.
- ResetPassword
-
The ResetPassword journey lets end users reset their password by providing their email and answering security questions. If the questions are answered correctly, the end 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.
Learn more in Password reset.
- ForgottenUsername
-
The ForgottenUsername journey lets end users 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 end user. The email includes a link to sign on, which will take the end user through the Login journey.
Learn more in Username recovery.
- UpdatePassword
-
The Update Password journey lets end users change their passwords. The journey assumes that the end user has already logged in successfully. It checks the end user’s session data and, if the session is valid, prompts the end user to update their password.
Learn more in Password update.
Sign-on (login)
The PingOne Advanced Identity Cloud sign-on flow is designed for self-service, as demonstrated in the Login journey template. This journey lets end users sign on using their Advanced Identity Cloud credentials and increments the login counter. A separate retry-limit counter tracks failed authentications and locks the end-user account if the number of retries exceeds a specified limit. End users who successfully authenticate are sent through a separate progressive profile journey.
| The Login journey template can be extended to include other features, such as support for identity providers. Learn more in Social authentication. |
The following nodes are associated with sign-on journeys:
- Platform Username node
-
The Platform Username node is used in both sign-on and registration journeys. It collects the end user’s username.
- Platform Password node
-
The Platform Password node is used in both sign-on and registration journeys. It collects the end user’s password.
- Identity Store Decision node
-
The Identity Store Decision node takes a username and password and validates they match an existing end user in the identity store.
- Retry Limit Decision node
-
The Retry Limit Decision node tracks failed authentications. If the number of failed authentications is below a specified Retry Limit, the end user can attempt authentication again. Otherwise, the node forwards to the Account Lockout node to lock the end-user account.
- Account Lockout node
-
The Account Lockout node sets the lock state of the end-user account. In this case, it is configured to lock the account. The node can also be used in a separate unlock journey to unlock the end-user account.
Configure social identity providers
To include social identity providers as a method of authentication, configure the Social Identity Provider service to include some form of social registration or social account claiming. Learn more in Social authentication. After this is set up, add social identity provider support to your sign-on journey.
To get started with social sign ons, you can create a new journey, modify an existing sign-on journey, or duplicate the Login journey template and modify that.
Example social sign-on journey
This example uses the following nodes:
-
A Page node containing:
To create the journey:
-
Connect the starting node to the Page node.
-
Connect the Social Authentication output on the Page node to the Social Provider Handler node.
-
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.
-
On the Page node, connect the Local Authentication node to the Data Store Decision node.
-
On the Data Store Decision node, connect the True output to the Increment Login Count node. Connect the False output to the Failure node.
-
Connect the Increment Login Count node to the Inner Tree Evaluator node node.
-
The Inner Tree Evaluator node points to another journey, letting you chain multiple journeys together.
By default, this is set to point to the
ProgressiveProfilejourney. Learn more about progressive profiles in Progressive profile.Connect the Inner Tree Evaluator node node to the Success node.
The resulting journey looks similar to this:
Example login REST output
Calling a login self-service endpoint returns a JSON object containing callbacks for each of the nodes included in the 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>"
}Username recovery
Username recovery lets end users recover their usernames using other information they remember, such as their email address.
PingOne Advanced Identity Cloud includes a ForgottenUsername journey template. This journey collects an end user’s email address and then uses it to search for a user identity with that address. It then emails the username associated with that email address to the end user.
|
When reviewing the journey template, notice that both Identify Existing User node outputs connect to the Email Suspend node. This is recommended behavior for security reasons. Returning different outcomes potentially exposes which end users have accounts in your system. |
An alternative journey sends a verification link, then uses the Display Username node once the end user returns from the email.
Example forgotten username REST output
When calling a username recovery self-service endpoint, you’ll 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 reset
Password reset lets end users reset their password without assistance from an administrator.
PingOne Advanced Identity Cloud includes a ResetPassword journey template, which requests an end user’s email address, checks if an end user with that email exists, and if so, emails a reset link to the end user. The journey then waits until the end user clicks the link before presenting a password reset prompt.
Make sure the Patch Object node's Patch As Object field is not selected (set 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>"
}Password update
Password update lets end users update their passwords without assistance from an administrator.
PingOne Advanced Identity Cloud includes an UpdatePassword journey template. Unlike the other self-service journey templates, the update password journey assumes the end user is already signed on and gets the end user’s current session data to identify the end user. It then presents a prompt to update the end user’s password and uses a Patch Object node to update the password. An example of where you might use a journey like this is in an update password link placed in the end user’s profile or settings.
Make sure that the Patch Object node's Patch As Object field is not selected (equivalent to false).
|
To let end users update their password through the Advanced Identity Cloud end-user UI profile page using the Reset link, you set a self-service tree for the password update journey. The default journey is UpdatePassword.
To change the journey for password updates:
-
In the Advanced Identity Cloud admin console, select Native Consoles > Access Management.
-
In the left navigation pane, click Services.
-
Select Self Service Trees.
-
In the updatePassword field, update the name of the journey.
-
Click Save Changes.
User self-registration
User self-registration lets your end users create their own accounts without assistance from an administrator.
PingOne Advanced Identity Cloud includes a Registration journey template that lets end users create their own account for an app or service.
To configure self-registration in Advanced Identity Cloud, your registration journey requires at least the following nodes:
- Platform Username node
-
If you have changed the
userNameattribute to something else, you must configure this node to use the new attribute, for example, if you changed your configuration to use themailattribute instead. - Attribute Collector node
-
This collects information from the end user for any attributes that are required to create the end user profile.
By default, required attributes include
userName,givenName,sn(surname), andmail(email). The node can collect optional attributes as well, as long as any required attributes are collected. - Create Object node
-
This creates the end user in Advanced Identity Cloud.
All other nodes are optional. Some are strongly encouraged. For example, if you don’t include a Platform Password node, the end user won’t be able to enter a password to sign on. This node isn’t always necessary, like when you provide another authentication method such as a social identity provider or when you generate a password for the end 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:
-
Only add nodes that require interaction with the end user to a Page node.
-
At most, add one node with multiple possible outcomes in a Page node.
-
Do not add the Email Suspend node or the Social Provider Handler node to a Page node.
Common nodes in a registration journey include:
-
The CAPTCHA node. Learn more in CAPTCHA services.
-
The KBA Definition node. Learn more in Security questions.
-
The Accept Terms and Conditions node. Learn more in Terms and conditions.
-
The Consent Collector node. Learn more in Privacy and consent.
CAPTCHA services
CAPTCHA is a way to challenge an end 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’ll 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 an end 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:
-
In the Advanced Identity Cloud admin console, select Security > Security Questions. From here, you can configure the questions that are presented to end users and how they should be handled.
-
Click Add Question to set additional questions for the end user.
-
On the Add a Security Question modal:
-
Select a locale, provide the question text for that locale, and click Done.
-
To provide the question for different locales, click Add locale and repeat the previous step.
-
Click Save.
-
-
On the Settings tab, set the following:
-
Must define refers to the minimum number of security questions the end user must set up during registration.
-
Must answer refers to the minimum number of questions the end user must answer to satisfy a security prompt.
-
| After you deploy these security questions, don’t remove or change existing questions because end users might already 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 end user to select security questions from a list and define answers to these questions for use during identity verification. The list includes an option for end users to define their own questions.
- KBA Verification node
-
The KBA Verification node is used to verify an end 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 end user has defined answers for more questions than required, the displayed questions are randomized.
- KBA Decision node
-
The KBA Decision node is primarily used in cases of a Progressive Profile journey, where you ensure an end user has defined answers to the minimum number of questions required. This can be useful if the number of questions changes, so the end user can be prompted to complete additional questions when they next sign on. In this case, the KBA Decision node is used together with the KBA Definition node. If the KBA Decision node evaluates false, the end user is directed to the KBA Definition node.
Terms and conditions
Terms and conditions display the terms and conditions for using your service. Configure the terms and conditions for using your service. These are not considered optional, and end users must accept the terms and conditions before they can progress in the account creation process.
Configuration
To configure terms and conditions:
-
In the Advanced Identity Cloud admin console, select Terms & Conditions, and click + New Version.
-
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. -
Enter the locale for which these terms and conditions apply, expressed as its ISO 639-1 code (for example,
enorfr), then click Add. -
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. Learn more in Terms and conditions content formatting.
When using HTML formatting,
idandstyleattributes are stripped out when Advanced Identity Cloud converts the HTML formatting to Markdown. However, you can use the following techniques to emulateidandstyleattributes:-
To link to different parts of the terms and conditions content, use the formatted header IDs in the HTML output. Learn more in 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 end users.
-
-
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 end 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. The node uses the currently active version of the terms and conditions by default, so you don’t 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 end user has accepted the currently active terms and conditions. If you’ve updated the terms and conditions version, the decision evaluates to
false. Connect this outcome to a Accept Terms and Conditions node to give the end 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 lowercase, and then removes spaces and special characters (except underscores).
Here are some examples:
| Markdown | Formatted header ID | HTML output |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
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, privacy and consent lets end users determine which external resources their information can be shared with, such as sales and marketing services. Advanced Identity Cloud manages these external resources as applications and lets you configure consent per application or mapping. The end user’s information is mapped to the corresponding fields in the external service and is then synchronized. Learn more in Resource mapping.
Configuration
To enable consent for a mapping:
-
In the Advanced Identity Cloud admin console, select Native Consoles > Identity Management.
-
Select Configure > Mappings, then select Edit on the mapping that you want to configure.
-
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 end user with a list of all their mappings the user is affected by that have privacy and consent enabled. The end user can select or disable specific mappings. 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’ll need to use the Query Filter Decision node to check for the presence of your desired mappings in the end user’s
consentedMappingsattribute.
Example registration REST output
When calling a registration self-service endpoint, you’ll 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 end users register and sign on to 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
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 |
|
Apple |
OIDC |
|
OAuth 2.0 |
|
|
OIDC |
|
|
OAuth 2.0 |
|
|
LINE (Browser) |
OIDC |
|
LINE (Native) |
OIDC |
|
LinkedIn (Legacy) (2) |
OAuth 2.0 |
|
OIDC |
|
|
Microsoft |
OAuth 2.0 |
|
Salesforce |
OAuth 2.0 |
|
OAuth 2.0 |
|
|
VK (Vkontakte) |
OAuth 2.0 |
|
OAuth 2.0 |
|
|
WordPress |
OAuth 2.0 |
|
Yahoo |
OIDC |
|
itsme(1) |
OIDC |
|
(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 |
|
Any social identity provider that implements the OIDC specification. |
OIDC |
|
Add identity providers
-
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 Advanced Identity Cloud where the identity provider redirects the end 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 Advanced Identity Cloud client configuration must match.
Some providers require you to enable a specific setting or API in their service:
-
Enable the
Gmail APIin 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 Applein the Apple Developer site. - LINE
-
You must apply for permission for your LINE channel to access a user’s email address using OIDC:
-
In the LINE Developers console, enable Email address permission.
-
Agree to the terms and conditions, and follow the steps to complete the application.
-
The console displays
Appliedwhen your application is accepted.
If you don’t have email permission, the registration will fail with an
Invalid Attribute Syntaxerror. -
-
In the Advanced Identity Cloud admin console, go to Native Consoles > Access Management > Realm Name > Services.
-
Click Social Identity Provider Service.
-
Go to the Secondary Configurations tab.
Advanced Identity Cloud includes scripts and configurations for several common identity providers.
-
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
-
-
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.
-
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
acrvalues, PKCE-related settings, and more.Keep their documentation close while configuring the client profile.
-
Visit the provider’s
.well-knownendpoint.OAuth 2.0/OpenID Connect-compliant providers will display much of the information you need to configure the identity provider client in their
.well-knownendpoint. For example, the endpoint should expose their endpoint URLs, and the signing and encryption algorithms they support.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 Advanced Identity Cloud .
Find more information in 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.
Find more information in /oauth2/connect/rp/jwk_uri.
Learn more about client configuration settings in Client configuration reference.
-
-
-
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 end user to select a social identity provider for registration or sign on or (optionally) to continue with local registration or sign on.
When the end 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 end user has authorized the service. It runs the provider’s configured normalization script to map the information into a format that Advanced Identity Cloud can consume.
Next, the node uses a transformation script provided by Advanced Identity Cloud called
Normalized Profile to Managed Userto transform the profile information into a managed object.The node then queries the identity store available for the realm to check whether the end user already exists. If the user exists, they are signed on. If the user does not exist, the user must be created.
Set up a basic social registration journey
-
In your realm, go to Journeys.
You can create a new journey, modify an existing journey, or duplicate an existing journey.
-
Decide whether end users can sign on with their local credentials, and add the relevant nodes to the journey:
-
Social authentication journeys allowing local authentication might look like the following:
-
Social authentication journeys enforcing social authentication sign on might look like the following:
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.
-
-
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 Advanced Identity Cloud can use.Find information on the script and the available bindings in normalized-profile-to-managed-user.js.
-
In Client Type, select
BROWSERwhen using Advanced Identity Cloud admin console or Ping SDKs for JavaScript, orNATIVEwhen using the ForgeRock SDKs for Android or iOS.
-
-
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 Native Consoles > Identity Management, and open the Manage drop-down list.
Identity managed object types are preceded by the icon.
-
Configure the Attribute Collector node adding at least the
mail,givenName, andsnattributes.
Configure social registration with account claiming
If your end users have one or more social identity provider accounts, they can link them to the same Advanced Identity Cloud account.
The following example builds on the basic social registration journey shown in Set up a basic social registration journey:
The journey uses the Identify Existing User node to determine if the end user is already registered in 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 end users connect to social identity providers through the End User UI profile page, add a mapping for your social authentication journey:
-
From the Advanced Identity Cloud admin console, select Native Consoles > Access Management.
-
From the left navigation pane, click Services.
-
Select Self Service Trees.
-
Set a new key and value and click + Add:
- Key
-
connectSocial - Value
-
The name of the journey
-
Click Save Changes.
Progressive profile
Progressive profiling lets end users provide additional profile information over time or update existing information when needed.
PingOne Advanced Identity Cloud includes a ProgressiveProfile journey template that checks the number of sign ons, and prompts the end user to add their marketing preferences if they haven’t already. However, there are many other ways to configure a progressive profile flow to suit your needs.
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.
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 doesn’t 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 the following 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 doesn’t work on private attributes.
-
- KBA Decision node
-
The KBA Decision node is primarily used in a progressive profile journey where you want to ensure an end 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 end 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 end user would then be taken to the KBA Definition node.
- Login Count Decision node
-
The Login Count Decision node checks whether the end user has signed on the specified number of times. It can be triggered once (using the
ATinterval) or triggered repeatedly after a set number of sign ons (using theEVERYinterval). The sign-on count is not automatically incremented: be sure to include the Increment Login Count node in your sign-on journey if you plan to use this node. - Profile Completeness Decision node
-
The Profile Completeness Decision node checks how complete an end 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 an end 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 example, you can use this in progressive profile journeys to check if marketing preferences are set on an end user’s profile. Learn more about constructing effective query filters in Construct queries.
- Terms and Conditions Decision node
-
The Terms and Conditions Decision node verifies the end user has accepted the currently active set of terms and conditions. Use this node when you want to verify the end 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 end user’s creation date against a specified amount of time. This is used when you want to have a time-based reminder for end users to check an attribute. Once the specified amount of time has elapsed, the node evaluates to
Truethe next time the node is triggered, for example, by the end user signing on and going through a progressive profile journey.
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 objectAttributes 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();Find information on accessing IDM properties in scripts and the shared state in auth scripting.