Authentication and SSO
These topics cover concepts, implementation, and customization of the authentication and single sign-on (SSO) features of PingOne Advanced Identity Cloud.
Configure PingOne Advanced Identity Cloud for authentication
Learn about PingOne Advanced Identity Cloud’s authentication mechanisms.
Multi-factor authentication
Require that users provide multiple forms of identification when logging in to services.
Single sign-On
Enable single sign-on (SSO) so that users can log in once with a single set of credentials.
Social authentication
Allow users to authenticate to your services by using third-party identity providers.
Name changes for ForgeRock products
Product names changed when ForgeRock became part of Ping Identity. Learn more in New name for ForgeRock Identity Cloud.
Introduction to authentication
Authentication is the act of confirming a user’s identity, for example, by providing a set of credentials.
As part of an access management strategy, authentication is tightly coupled with authorization; usually, not only is it important to confirm that a user is who they say they are, but also to ensure that they can only access a subset of information.
Consider a user who wants to access an online shop. As the owner of the shop, you want to ensure the user identity is confirmed (as it’s tied to their shipping and email addresses and payment information). You also want to ensure that they can only access their own information.
You can deploy a web agent on the web server hosting the online shop. The agent redirects the user’s request to an PingOne Advanced Identity Cloud login page, where the user enters their credentials, such as username and password. PingOne Advanced Identity Cloud determines who the user is, and whether the user has the right to access the protected page. PingOne Advanced Identity Cloud then redirects the user back to the protected page with authorization credentials that can be verified by the agent. The agent allows the user authorized by PingOne Advanced Identity Cloud to access the page.
In the same way, you can also use PingOne Advanced Identity Cloud to protect physical devices connected on the Internet of Things (IoT). For example, a delivery van tracking system could have its proxying gateway authenticate to a brokering system using an X.509 certificate to allow it to enable an HTTPS protocol and then connect to sensors in its delivery trucks. If the X.509 certificate is valid, the brokering system can monitor a van’s fuel consumption, speed, mileage, and overall engine condition to maximize each van’s operating efficiency.
PingOne Advanced Identity Cloud uses authentication nodes and journeys to implement authentication.
PingOne Advanced Identity Cloud creates an authentication session to track the user’s progress through an authentication journey. After the user has authenticated, PingOne Advanced Identity Cloud creates a session to manage the user’s access to resources. To learn more about sessions, refer to Sessions.
Multi-factor authentication
Multi-factor authentication (MFA) is an authentication technique that requires users to provide multiple forms of identification when logging in to PingOne Advanced Identity Cloud.
Multi-factor authentication provides a more secure method for users to access their accounts with the help of a device. Note that the word device is used in this section to mean a piece of equipment that can display a one-time password or that supports push notifications using protocols supported by PingOne Advanced Identity Cloud multi-factor authentication (MFA). Devices are most commonly mobile phones with authenticator applications that support the OATH protocol or push notifications, but could also include other equipment.
The following is an example scenario of multi-factor authentication in PingOne Advanced Identity Cloud:
-
In the Advanced Identity Cloud admin UI, configure an authentication journey to capture the user’s username and password and to create one-time passwords.
-
An end user authenticates to PingOne Advanced Identity Cloud using that authentication journey.
-
PingOne Advanced Identity Cloud prompts the user to enter the username and password—the first factor in multi-factor authentication.
-
If the user ID and password were correct, PingOne Advanced Identity Cloud sends the user an email with a one-time password.
-
The user provides the one-time password to PingOne Advanced Identity Cloud to successfully complete authentication—the second factor in multi-factor authentication.
PingOne Advanced Identity Cloud supports the following multi-factor authentication protocols:
-
MFA: Use codes from ForgeRock app using OATH to enable one-time password authentication.
-
MFA: Authenticate using push notification to receive push notifications in a device as part of the authentication process.
-
MFA: Authenticate using a device with WebAuthn to enable authentication using an authenticator device, such as a fingerprint scanner.
Configure PingOne Advanced Identity Cloud for authentication
PingOne Advanced Identity Cloud uses authentication nodes and journeys to authenticate users and provides a large variety of authentication nodes. Based on your authentication requirements, you connect these nodes to create a journey that guides users through the authentication process.
Authentication journeys are extremely flexible, and can be adapted to suit your specific deployment. Although the number of choices can seem daunting, once you understand the basic process, you will be able to configure multiple journeys to protect access to most applications in your organization.
Self-managed AM deployments can also use a legacy authentication mechanism, with modules and chains. Modules and chains are not supported in PingOne Advanced Identity Cloud, even though it might appear that you can configure them in the UI. All authentication to Advanced Identity Cloud must use an authentication journey. |
Authentication is configured per realm. The following table summarizes the high-level tasks required to configure authentication in a realm:
Task | Resources |
---|---|
Configure the required authentication mechanisms You need to decide how your users are going to log in. For example, you may require your users to provide multiple credentials, or to log in using third-party identity providers, such as Facebook or Google. |
|
Configure the success and failure URLs for the realm By default, PingOne Advanced Identity Cloud redirects users to the UI after successful authentication. No failure URL is defined by default. |
Authentication nodes and journeys
Authentication journeys provide fine-grained authentication by allowing multiple paths and decision points throughout the authentication flow. Use them to build complex authorization scenarios, while offering a streamlined login experience to users.
Authentication journeys are made up of authentication nodes, which define actions taken during authentication. Each node performs a single task during authentication; for example, collecting a username or making a simple decision based on a cookie.
Nodes can have multiple outcomes rather than just success or failure. These outcomes let you create complex yet user-friendly authentication experiences by linking nodes together, creating loops and sections for different authentication scenarios, and nesting nodes within a journey.
For greater control of the authentication process, you can assign authentication levels to sections of a journey, with higher levels typically allowing access to more restricted resources.
Authentication levels
When a user authenticates successfully, PingOne Advanced Identity Cloud creates a session which allows PingOne Advanced Identity Cloud to manage the user’s access to resources. The session is assigned an authentication level. The authentication level is often used as a measure of the strength of the authentication performed. For example, a simple username and password might be assigned a low authentication level, while multi-factor authentication with push and WebAuthn might be assigned a high level.
Authorization policies might require a particular authentication level to access protected resources. When an authenticated user tries to access a protected resource without satisfying the authentication level requirement, PingOne Advanced Identity Cloud denies access to the resource and returns an advice indicating that the user must reauthenticate at the required level to access the resource.
The policy enforcement point, such as an agent, sends the user back to PingOne Advanced Identity Cloud for a session upgrade.
PingOne Advanced Identity Cloud provides the following nodes to manage authentication levels:
-
The Auth Level Decision node checks that the current authentication level is equal to or greater than the level specified in the node.
-
The Modify Auth Level node can raise or lower the authentication level.
Position these nodes to alter the authentication level, depending on the route taken through the authentication flow.
Account lockout
Use account lockout to limit the number of times an end-user can attempt to authenticate with invalid credentials before rendering their account inactive. Limiting the number of attempts helps to prevent password-guessing and brute-force attacks.
Authentication journeys have built-in support for account lockout. They also provide nodes for checking and changing the status of a user.
For more information refer to Account lockout.
Configure authentication journeys
The following table summarizes the high-level tasks required to configure authentication journeys:
Task | Resources |
---|---|
Design your user authentication journey Authentication journeys are flexible. For example, the same journey can branch for different use cases, or users can be forced to loop though branches until they’re able to present the required credentials. It’s easy to create a massive journey that’s difficult to understand, read, and maintain in the UI. To avoid this, PingOne Advanced Identity Cloud lets you nest journeys within journeys. The best way to tackle the design decision is to write down a list of required steps users would need to take to log in to your environment, and then check the list of nodes available in PingOne Advanced Identity Cloud. |
|
Configure your authentication journeys Use the journey editor to put together your journeys quickly. |
|
Configure webhooks, if required If you have configured the |
Specify the identity object type for a journey
Each authentication journey assumes a specific identity object type. The nodes in the journey use this object type to
verify the identity, for example, users, roles, or organizations. The default journeys provided with Advanced Identity Cloud assume
the identity object using the journey to authenticate is a realm-name user, for example Alpha realm - Users
or
Bravo realm - Users
.
When you create a new journey, you select the object type in the Identity Object list.
To change the object type of an existing journey:
-
In the Advanced Identity Cloud admin UI select Journeys > Journey name > Edit.
-
On the journey page, click the ellipses () at the top right of the page, then click Edit details.
-
Select a new object type in the Identity Object list.
Enable and disable an authentication journey
Custom authentication journeys are enabled by default, when they are saved. For security purposes, you can disable custom authentication journeys during development and testing, to prevent accidentally allowing access through these journeys. Rather than having unused authentication journeys enabled, you should disable the default authentication journeys until you need them.
When a user attempts to authenticate through a disabled journey, PingOne Advanced Identity Cloud returns a Tree does not exist
error.
To enable or disable an authentication journey, set the enabled
flag in the journey configuration:
To enable or disable an authentication journey, send a PUT request to update the journey’s configuration.
Specify the journey ID, the nodes in the journey, and set the enabled
flag:
Example
$ curl \
--header "Content-Type: application/json" \
--header "<session-cookie-name>: AQIC5..." \
--header 'accept-api-version: protocol=2.1,resource=1.0' \
--header "If-Match: *" \
--request PUT \
--data '
{
"entryNodeId": "c11e9cf8-ef48-4740-876f-6300e2f46aef",
"nodes": {
"c11e9cf8-ef48-4740-876f-6300e2f46aef": {
"displayName": "Page Node",
"nodeType": "PageNode",
"x": 147,
"y": 25,
"connections": {
"outcome": "15839e1c-5085-4f58-bc94-c4cc848a0ae8"
}
},
"15839e1c-5085-4f58-bc94-c4cc848a0ae8": {
"displayName": "Data Store Decision",
"nodeType": "DataStoreDecisionNode",
"x": 349,
"y": 25,
"connections": {
"true": "70e691a5-1e33-4ac3-a356-e7b6d60d92e0",
"false": "e301438c-0bd0-429c-ab0c-66126501069a"
}
}
},
"enabled": false
}' \
'https://https://<tenant-env-fqdn>/am/json/realms/root/realms/alpha/realm-config/authentication/authenticationtrees/trees/myAuthTree'
{
"_id": "myAuthTree",
"_rev": "2070284866",
"uiConfig": {},
"entryNodeId": "c11e9cf8-ef48-4740-876f-6300e2f46aef",
"nodes": {
"c11e9cf8-ef48-4740-876f-6300e2f46aef": {
"displayName": "Page Node",
"nodeType": "PageNode",
"x": 147,
"y": 25,
"connections": {
"outcome": "15839e1c-5085-4f58-bc94-c4cc848a0ae8"
}
},
"15839e1c-5085-4f58-bc94-c4cc848a0ae8": {
"displayName": "Data Store Decision",
"nodeType": "DataStoreDecisionNode",
"x": 349,
"y": 25,
"connections": {
"true": "70e691a5-1e33-4ac3-a356-e7b6d60d92e0",
"false": "e301438c-0bd0-429c-ab0c-66126501069a"
}
}
},
"staticNodes": {
"startNode": {
"x": 50,
"y": 25
},
"70e691a5-1e33-4ac3-a356-e7b6d60d92e0": {
"x": 570,
"y": 30
},
"e301438c-0bd0-429c-ab0c-66126501069a": {
"x": 573,
"y": 107
}
},
"enabled": false
}
Disable direct access through a child journey
A child journey lets you nest authentication logic. There is no limit to the depth of nesting.
You configure a child journey like any other journey and call it from a parent journey using an Inner Tree Evaluator node.
You may want to hide child journeys as complete services. In other words, you may want to prevent users from authenticating directly through a child journey, either for security reasons or simply because the child journey is insufficient as a complete authentication service.
To prevent a journey from being used outside of its parent journey, send a PUT request to update the journey configuration,
including the journey ID and all the nodes in the journey and set the innerTreeOnly
property to true
:
Example
$ curl \
--header "Content-Type: application/json" \
--header "<session-cookie-name>: AQIC5..." \
--header 'accept-api-version: protocol=2.1,resource=1.0' \
--header "If-Match: *" \
--request PUT \
--data '
{
"entryNodeId": "c11e9cf8-ef48-4740-876f-6300e2f46aef",
"nodes": {
"c11e9cf8-ef48-4740-876f-6300e2f46aef": {
"displayName": "Page Node",
"nodeType": "PageNode",
"x": 147,
"y": 25,
"connections": {
"outcome": "15839e1c-5085-4f58-bc94-c4cc848a0ae8"
}
},
"15839e1c-5085-4f58-bc94-c4cc848a0ae8": {
"displayName": "Data Store Decision",
"nodeType": "DataStoreDecisionNode",
"x": 349,
"y": 25,
"connections": {
"true": "70e691a5-1e33-4ac3-a356-e7b6d60d92e0",
"false": "e301438c-0bd0-429c-ab0c-66126501069a"
}
}
},
"innerTreeOnly": true
}' \
'https://https://<tenant-env-fqdn>/am/json/realms/root/realms/alpha/realm-config/authentication/authenticationtrees/trees/myAuthTree"
{
"_id": "myAuthTree",
"_rev": "1081620278",
"uiConfig": {},
"entryNodeId": "c11e9cf8-ef48-4740-876f-6300e2f46aef",
"innerTreeOnly": true,
"nodes": {
"c11e9cf8-ef48-4740-876f-6300e2f46aef": {
"displayName": "Page Node",
"nodeType": "PageNode",
"x": 147,
"y": 25,
"connections": {
"outcome": "15839e1c-5085-4f58-bc94-c4cc848a0ae8"
}
},
"15839e1c-5085-4f58-bc94-c4cc848a0ae8": {
"displayName": "Data Store Decision",
"nodeType": "DataStoreDecisionNode",
"x": 349,
"y": 25,
"connections": {
"true": "70e691a5-1e33-4ac3-a356-e7b6d60d92e0",
"false": "e301438c-0bd0-429c-ab0c-66126501069a"
}
}
},
"staticNodes": {
"startNode": {
"x": 50,
"y": 25
},
"70e691a5-1e33-4ac3-a356-e7b6d60d92e0": {
"x": 570,
"y": 30
},
"e301438c-0bd0-429c-ab0c-66126501069a": {
"x": 573,
"y": 107
}
},
"enabled": true
}
Configure authentication webhooks
Webhooks are used to send HTTP POST calls to a server with contextual information about an authentication session when a predefined event occurs, for example, logging out.
Webhooks are used from within authentication journeys, by the Register Logout Webhook node.
-
Under Native Consoles > Access Management, go to Realms > Realm Name > Authentication > Webhooks.
-
Select Create Webhook, specify a Webhook Name, and select Create.
The webhook configuration screen is displayed:
-
Complete the fields as required:
- Url
-
The URL to which the HTTP POST is sent when the event occurs.
- Body
-
The body of the HTTP POST. To send different data formats, set the correct Content-Type header in the
Header
property, for example:-
Form Data. Enter the body value in the format
parameter=value¶meter2=value2
, and set aContent-Type
header ofapplication/x-www-form-urlencoded
. -
JSON Data. Enter the body value in the format
{"parameter":"value","parameter2":"value2"}
, and set aContent-Type
header ofapplication/json
.
-
- Headers
-
Any HTTP headers to add to the POST.
To add a header, enter the name of the header in the
Key
field, and the value, and then click Add (➕).To remove a header, click Delete (✖).
The fields in a webhook support variables for retrieving values from the user’s session after successfully authenticating. Specify a variable in the following format:
${variable_name}
.To access the type of webhook event, use the
WebhookEventType
parameter key to return one of the following possible values:-
LOGOUT
-
UPGRADE
-
DESTROY
-
MAX_TIMEOUT
-
IDLE_TIMEOUT
For example, to retrieve the event type as a query parameter:
&event=${WebhookEventType}
You can use a variable to access custom properties added to the session with the Set Session Properties node as well as the following default session properties:
Default session properties
Property Example value Description AMCtxId
22e73c81-708e-4849-b064-db29b68ef943-105372
The audit ID for the session. This is logged as the
trackingIds
field in PingOne Advanced Identity Cloud access audit logs.authInstant
2022-02-28T14:06:31Z
The exact time that authentication completed.
AuthLevel
5
The authentication level of the session, determined by the login mechanism used to create the session. For example, a journey can have an authentication level of 10.
Step-up authentication is triggered if an authentication level specified by an agent or policy that is designed to protect a resource, is greater than or equal to the value of the
AuthLevel
session property.For more information, refer to Session upgrade with MFA.
CharSet
UTF-8
The character set for the session, set to
UTF-8
.clientType
genericHTML
The type of client, set to
genericHTML
.FullLoginURL
https://example.forgeblocks.com/platform/?realm=alpha
The full login URL, including query parameters.
Host
192.0.2.1
The originating IP address of the authentication request.
HostName
192.0.2.1
The host name that was used when the session was authenticated.
IndexType
service
Based on the value of the
authIndexValue
query parameter during authentication. Typically, this is set toservice
.Locale
en_US
The session locale.
loginURL
/openam/UI/Login
The base login URL. A subset of
FullLoginURL
.OidcSid
g0wmSpoAIwH6HAwCnurvRcfYqh4
Unique session ID used by PingOne Advanced Identity Cloud to determine whether OIDC ID tokens granted for the same client relate to the same session. This appears when
Enable Session Management
(storeOpsToken
) is set to true in the OAuth 2.0 provider settings.Organization
o=alpha,ou=services,dc=openam,dc=forgerock,dc=org
The DN of the realm where authentication took place.
Principal
id=demo,ou=user,o=alpha,ou=services,dc=openam,dc=forgerock,dc=org
The value of
sun.am.UniversalIdentifier
.Principals
demo
The username for the session.
Service
Example
The name of the journey that was used to authenticate this session.
successURL
/openam/console
The URL that was redirected to, upon a successful login request.
sun.am.UniversalIdentifier
id=demo,ou=user,o=alpha,ou=services,dc=openam,dc=forgerock,dc=org
The DN of the user (username is lowercase).
UserId
demo
The
id
value from thePrincipal
property.UserProfile
Required
Can be one of:
Required
,Create
,Ignore
, orCreateWithAlias
. Based on the value of thedynamicProfileCreation
authentication configuration. Values other thanIgnore
indicates that user profile attributes were mapped based on theUser Attribute Mapping to Session Attribute
setting. Refer to authentication configuration for details.Default:
Required
.UserToken
demo
The username, as defined in the
Principal
property.The following figure shows an example webhook, using variable substitutions:
Specifying a variable that is not present in the user’s session places the literal variable text in the HTTP POST, for example
user=${UserId}
, rather thanuser=demo
.
Success and failure redirection URLs
PingOne Advanced Identity Cloud determines the redirection URL based on authentication success or failure.
You can configure success and failure URLs in a number of places in PingOne Advanced Identity Cloud. For each authentication outcome, the user is redirected to the URL with the highest precedence, which is determined by where it is defined in PingOne Advanced Identity Cloud.
Success URL precedence
When a user authenticates successfully, PingOne Advanced Identity Cloud evaluates the redirection URL according to the following order of precedence:
-
The URL set in the authentication journey.
To specify a URL in an authentication journey, add a Success URL node to the journey and configure the Success URL in the node properties.
-
The URL set in the
goto
login URL parameter. For example:https://<tenant-env-fqdn>/am/login/?realm=/alpha&goto=http%3A%2F%2Fwww.example.com#login
-
The URL set in the Success URL attribute in the user’s profile.
Under Native Consoles > Access Management, go to Realm Name > Identities > identity. In Success URL, enter a URL, and save your changes.
You can also specify the client type by entering
ClientType|URL
as the property value. If the client type is specified, it takes precedence over a regular URL in the user’s profile. -
The URL set in the Default Success Login URL attribute in the realm.
Under Native Consoles > Access Management, go to Realm Name > Authentication > Settings > Post Authentication Processing. In Default Success Login URL, enter a URL, and save your changes.
You can also specify the client type by entering
ClientType|URL
as the property value. If the client type is specified, it takes precedence over a Default Success Login URL in the realm.
Failure URL precedence
When a user fails to authenticate, PingOne Advanced Identity Cloud evaluates the redirection URL according to the following order of precedence:
-
The URL set in the authentication journey.
To specify a URL in an authentication journey, add a Failure URL node to the journey and configure the failure URL in the node properties.
-
The URL set in the
gotoOnFail
parameter. For example:https://<tenant-env-fqdn>/am/login/?realm=/alpha&gotoOnFail=http%3A%2F%2Fwww.example.com#login
-
The URL set in the Failure URL attribute in the user’s profile.
Under Native Consoles > Access Management, go to Realm Name > Identities > identity. Under Failure URL, enter a URL, and click Save Changes.
You can also specify the client type by entering
ClientType|URL
as the property value. If the client type is specified, it will have precedence over a regular URL in the user’s profile. -
The URL set in the Default Failure Login URL attribute in the realm.
Under Native Consoles > Access Management, go to Realm Name > Authentication > Settings > Post Authentication Processing. In Default Failure Login URL, enter a URL, and save your changes.
You can also specify the client type by entering
ClientType|URL
as the property value. If the client type is specified, it will have precedence over a Default Failure Login URL in the realm.
Configure trusted URLs
Redirection URLs can be relative to PingOne Advanced Identity Cloud’s URL, or absolute.
By default, PingOne Advanced Identity Cloud trusts all relative URLs and those absolute URLs that are in the same scheme, FQDN, and port as PingOne Advanced Identity Cloud. This increases security against possible phishing attacks through an open redirect.
To configure PingOne Advanced Identity Cloud to trust other absolute URLs, add them to the validation service. If they are not added, PingOne Advanced Identity Cloud will redirect to the user profile or to the administrator console on log in, and to the default logout page in the UI on log out.
Do I need to add my URL to the validation service?
Consider these example URLS for a tenant environment URL, https://openam-example-mytenant-usw1.id.forgerock.io
:
URL | Add to the validation service? |
---|---|
|
Yes, the scheme is different. |
|
Yes, the port is different. |
|
No, the paths relative to the PingOne Advanced Identity Cloud URL are trusted. |
|
Yes, the scheme, port, and FQDN are different. |
Add a URL to the validation service
-
Under Native Consoles > Access Management, go to Realms > Realm Name > Services.
-
If the Validation Service is not in the list of services, configure a new service:
-
Click Add a Service.
-
From the Choose a service type drop-down list, select Validation Service.
-
-
In the Valid goto URL Resources field, enter one or more valid URL patterns to allow.
For example,
https://app.example.com:80/*?*
.General examples of URL pattern matching
-
If no port is specified,
http://www.example.com
canonicalizes tohttp://www.example.com:80
andhttps://www.example.com
canonicalizes tohttps://www.example.com:443
. -
A wildcard before "://" only matches up to "://"
For example,
http*://*.com/*
matcheshttp://www.example.com/hello/world
andhttps://www.example.com/hello
. -
A wildcard between "://" and ":" matches up to ":"
For example,
http://*:85
matcheshttp://www.example.com:85
. -
A wildcard between ":" and "/" only matches up to the first "/"
For example,
http://www.:/
matcheshttp://www.example.com:80
. In another example,http://www.example.com:*
matcheshttp://www.example.com:<any port>
andhttp://www.example.com:<any port>
, but nothing more. -
A wildcard after "/" matches anything, depending on whether it is single-level or a wildcard appropriately.
For example,
https://www.example.com/*
matcheshttps://www.example.com:443/foo/bar/baz/me
. -
If you do not use any wildcards, PingOne Advanced Identity Cloud exactly matches the string, so
http://www.example.com
only matcheshttp://www.example.com
, but NOThttp://www.example.com/
(trailing slash).If you put the wildcard after the path, PingOne Advanced Identity Cloud expects a path (even if it is blank), so
http://www.example.com/*
matcheshttp://www.example.com/
andhttp://www.example.com/foo/bar/baz.html
, but NOThttp://www.example.com
. -
http://www.example.com:*/
matcheshttp://www.example.com/
, which also canonicalizes tohttp://www.example.com:80/
. -
https://www.example.com:*/
matcheshttps://www.example.com/
, which also canonicalizes tohttps://www.example.com:443/
.
For more information on pattern matching and wildcard rules, refer to Specify resource patterns with wildcards.
-
-
Click Create to save your settings.
Validate a goto
URL
To validate a goto
URL over REST, use the /json/realms/root/realms/Realm Name/users?_action=validateGoto
endpoint. For example:
$ curl \
--request POST \
--header "Accept-API-Version: protocol=2.1,resource=3.0" \
--header "Content-Type: application/json" \
--header "<session-cookie-name>: AQIC5...ACMDE.*" \
--data '{"goto":"https://www.example.com/"}' \
'https://<tenant-env-fqdn>/am/json/realms/root/realms/alpha/users?_action=validateGoto'
{
"successURL":"https://www.example.com/"
}
If the URL is valid, the endpoint returns the specified URL as the successURL
response parameter.
A goto
URL is considered valid if one of the following is true:
-
The URL is configured in the validation service
-
The URL is relative
-
The URL is encoded
Encoded URLs are treated as relative URLs for the purposes of validation. To be treated as an absolute URL, the URL must not be encoded.
If the specified URL is invalid, the endpoint returns the default success URL.
Note that a valid session is optional; you can still call the validateGoto
endpoint with an expired session.
Realm authentication configuration
Advanced Identity Cloud users always authenticate to a realm. Each realm has a set of authentication settings that apply to all authentication performed to that realm. The settings are referred to as core authentication attributes.
To configure the default core authentication attributes for a realm, go to Native Consoles > Access Management > Realms > Realm Name > Authentication > Settings.
Edit the attributes on this page to configure authentication behavior, such as:
-
Account lockout settings for users authenticating to the realm
-
The default authentication locale
-
The duration of an authentication session
For more information, refer to Core authentication attributes.
Authenticate with a browser
When you authenticate to Advanced Identity Cloud using a browser, you can specify the realm and the authentication parameters in the URL, to customize the user’s authentication experience.
Specify the realm in the URL
Specify the realm as the value of the realm
parameter in the URL. Preface the realm name with a forward slash (/
); for example:
https://<tenant-env-fqdn>/am/login/?realm=/alpha
Authentication parameters
PingOne Advanced Identity Cloud accepts the following parameters in the URL query string.
- arg=newsession
-
Request that PingOne Advanced Identity Cloud end the user’s current session and start a new session.
- ForceAuth
-
If
ForceAuth=true
, request that PingOne Advanced Identity Cloud force the user to authenticate even if they already have a valid session.On successful authentication, PingOne Advanced Identity Cloud issues new session tokens to reauthenticating users, even if the current session already meets the security requirements.
- goto
-
On successful authentication, or successful logout, request that PingOne Advanced Identity Cloud redirect the user to the specified location. Values must be URL-encoded.
For details, refer to Success and failure redirection URLs.
- gotoOnFail
-
On authentication failure, request that PingOne Advanced Identity Cloud redirect the user to the specified location. Values must be URL-encoded.
For details, refer to Success and failure redirection URLs.
- locale
-
Request that PingOne Advanced Identity Cloud display the user interface in the specified, supported locale. The locale can also be set in the user’s profile, in the HTTP header from their browser, or configured in PingOne Advanced Identity Cloud.
- realm
-
Request that PingOne Advanced Identity Cloud authenticate the user to the specified realm.
- resource
-
Set this parameter to
true
to request resource-based authentication. - service
-
Request that PingOne Advanced Identity Cloud authenticate the user with the specified authentication journey.
Example UI login URLs
Use any of the options listed in Authentication parameters as URL parameters.
Note that URL parameters must appear before any occurrences of the pound or hash character (#
).
The following are example URLs with parameters:
Description | Example URL |
---|---|
Log in to the |
|
Log in to the |
|
Authenticate using REST
PingOne Advanced Identity Cloud provides the /json/authenticate
endpoint for authentication,
and the /json/sessions
endpoint for managing sessions and logging out.
The following table summarizes authentication operations you can perform using REST:
Task | Resources |
---|---|
Authenticate to PingOne Advanced Identity Cloud Authenticating to PingOne Advanced Identity Cloud means logging in to a specific realm and receiving a session token from PingOne Advanced Identity Cloud. Add parameters to the authentication request to provide PingOne Advanced Identity Cloud with more information about how you want to authenticate. |
|
Use the session token PingOne Advanced Identity Cloud returns a session token when you authenticate to a realm. Use this token in subsequent calls to PingOne Advanced Identity Cloud. For example, when using REST calls to create, modify, or delete configuration objects. |
|
Log out of PingOne Advanced Identity Cloud Log out users by sending a |
|
Invalidate sessions Invalidate specific sessions, or invalidate all sessions for a user to ensure they are logged out of PingOne Advanced Identity Cloud. |
Authenticate using REST
To authenticate using REST, send an HTTP POST request to the json/authenticate
endpoint. You must specify the realm
hierarchy. Prefix each realm in the hierarchy with the realms/
keyword; for example, /realms/root/realms/alpha
.
The |
By default, you authenticate using the default authentication service configured for the realm. To override the default, specify authentication services and other options in the REST request.
PingOne Advanced Identity Cloud supports simple authentication methods, such as providing a username and password, and complex authentication journeys that might involve nested journey evaluations and multi-factor authentication.
For authentication journeys where providing a username and password is sufficient, you can log in by providing these credentials in headers. The following command logs in user bjensen
with password Secret12!
:
$ curl \
--request POST \
--header 'Content-Type: application/json' \
--header 'X-OpenAM-Username: bjensen' \
--header 'X-OpenAM-Password: Secret12!' \
--header 'Accept-API-Version: resource=2.0, protocol=1.0' \
'https://<tenant-env-fqdn>/am/json/realms/root/realms/alpha/authenticate'
{
"tokenId":"AQIC5wM...TU3OQ*",
"successUrl": "/enduser/?realm=/alpha",
"realm":"/alpha"
}
This zero page login mechanism works only for username/password authentication.
Note that the POST body is empty. If you submit a POST body, PingOne Advanced Identity Cloud interprets the body as a continuation of an existing authentication attempt that uses a supported callback mechanism. Callback mechanisms support complex authentication journeys, such as those where the user must be redirected to a third party or interact with a device as part of multi-factor authentication.
After successful authentication, PingOne Advanced Identity Cloud returns a tokenId
that applications can present as a cookie value for other
operations that require authentication. The tokenId
is known as the session token.
For information about how applications can use session tokens, refer to Session tokens after authentication.
If HttpOnly
cookies are enabled, and a client makes a call to the /json/authenticate
endpoint with a valid SSO token,
PingOne Advanced Identity Cloud returns the tokenId
field empty. For example:
{
"tokenId":"",
"successUrl":"/openam/console",
"realm":"/alpha"
}
To authenticate a user without providing them with a session, use the |
UTF-8 usernames and passwords
To use UTF-8 usernames and passwords in calls to the /json/authenticate
endpoint,
base64-encode the string, then wrap the string as described in RFC 2047:
encoded-word = "=?" charset "?" encoding "?" encoded-text "?="
For example, to authenticate using a UTF-8 username, such as Åström
, follow these steps:
-
Encode the string in base64 format:
w4VzdHLDtm0=
. -
Wrap the base64-encoded string, as per RFC 2047:
=?UTF-8?B?w4VzdHLDtm0=?=
. -
Use the result in the
X-OpenAM-Username
header passed to the authentication endpoint as follows:$ curl \ --request POST \ --header 'Content-Type: application/json' \ --header 'X-OpenAM-Username: =?UTF-8?B?w4VzdHLDtm0=?=' \ --header 'X-OpenAM-Password: Secret12!' \ --header 'Accept-API-Version: resource=2.0, protocol=1.0' \ 'https://<tenant-env-fqdn>/am/json/realms/root/realms/alpha/authenticate' { "tokenId": "DDZUA0Ellb4bOt...AIwMQ..*", "successUrl": "/enduser/?realm=/alpha", "realm": "/alpha" }
Authenticate to specific authentication services
You can provide PingOne Advanced Identity Cloud with additional information about how a user is authenticating. For example, you can specify a particular authentication journey, or request a list of the authentication services that would satisfy an authentication condition.
The following example specifies the Login
journey by using the authIndexType
and authIndexValue
parameters:
$ curl \
--request POST \
--header 'X-OpenAM-Username: bjensen' \
--header 'X-OpenAM-Password: Secret12!' \
--header 'Accept-API-Version: resource=2.0, protocol=1.0' \
'https://<tenant-env-fqdn>/am/json/realms/root/realms/alpha/authenticate?authIndexType=service&authIndexValue=Login'
You can replace the Login
journey with any other journey configured in the realm.
For details about using the authIndexType
parameter to authenticate to specific services, refer to
Authenticate endpoint parameters.
Return callback information
The /json/authenticate
endpoint supports callback mechanisms to perform complex authentication journeys.
When PingOne Advanced Identity Cloud needs to return or request information, it returns a JSON object with the authentication step, the
authentication identifier, and the related callbacks.
The following callback types are available:
- Read-only callbacks
-
Read-only callbacks provide information to the user, such as text messages or the period of time a user must wait before continuing their authentication journey.
- Interactive callbacks
-
Interactive callbacks request information from the user; for example, their username and password, or a request that they select between different configured options.
- Backchannel callbacks
-
Backchannel callbacks let PingOne Advanced Identity Cloud access additional information from the user’s request; for example, a specific header or certificate.
Read-only and interactive callbacks have an array of output
elements that can be displayed to the end user.
The JSON returned in an interactive callback includes an array of input
elements that must be completed and returned
to PingOne Advanced Identity Cloud. For example:
"output": [
{
"name": "prompt",
"value": " User Name: "
}
],
"input": [
{
"name": "IDToken1",
"value": ""
}
]
The value of some interactive callbacks can be returned as headers,
such as the X-OpenAM-Username
and X-OpenAM-Password
headers,
but most of them must be returned in JSON as a response to the request.
Depending on how complex the authentication journey is, PingOne Advanced Identity Cloud may return several callbacks sequentially. Each must be completed and returned to PingOne Advanced Identity Cloud until authentication is successful.
The following example shows a request for authentication,
and PingOne Advanced Identity Cloud’s response with the NameCallback
and PasswordCallback
:
$ curl \
--request POST \
--header "Content-Type: application/json" \
--header "Accept-API-Version: resource=2.0, protocol=1.0" \
'https://<tenant-env-fqdn>/am/json/realms/root/realms/alpha/authenticate'
{
"authId": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJvdGsiOiJ...", (1)
"callbacks": [
{
"type": "NameCallback", (2)
"output": [ (3)
{
"name": "prompt",
"value": " User Name: "
}
],
"input": [ (4)
{
"name": "IDToken1",
"value": ""
}
]
},
{
"type": "PasswordCallback",
"output": [
{
"name": "prompt",
"value": " Password: "
}
],
"input": [
{
"name": "IDToken2",
"value": ""
}
]
}
]
}
1 | The JWT that uniquely identifies the authentication context to PingOne Advanced Identity Cloud. |
2 | The type of callback. It must be listed under Supported callbacks. |
3 | The information PingOne Advanced Identity Cloud offers about this callback. Usually, this information would be displayed to the user in the UI. |
4 | The information PingOne Advanced Identity Cloud is requesting.
The user must complete the "value": "" field with the required information. |
To respond to a callback, send back the whole JSON object, including the missing values.
The following example shows how to respond to the NameCallback
and PasswordCallback
callbacks, returning the
username (bjensen
) and the password (Secret12!
):
$ curl \
--request POST \
--header "Content-Type: application/json" \
--header "Accept-API-Version: resource=2.0, protocol=1.0" \
--data '{
"authId":""eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJvdGsiOiJ...",
"callbacks": [
{
"type": "NameCallback",
"output": [
{
"name": "prompt",
"value": "User Name"
}
],
"input": [
{
"name": "IDToken1",
"value": "bjensen"
}
],
"_id": 0
},
{
"type": "PasswordCallback",
"output": [
{
"name": "prompt",
"value": "Password"
}
],
"input": [
{
"name": "IDToken2",
"value": "Secret12!"
}
],
"_id": 1
}
],
}' \
'https://<tenant-env-fqdn>/am/json/realms/root/realms/alpha/authenticate'
{
"tokenId": "lWY23F4fuC7cu4Fq4GQa5u6drlQ...*",
"successUrl": "/enduser/?realm=/alpha",
"realm": "/alpha"
}
In complex authentication journeys, PingOne Advanced Identity Cloud may send several callbacks sequentially. Each must be completed and returned to PingOne Advanced Identity Cloud until authentication is successful.
For details about the callbacks PingOne Advanced Identity Cloud can return, refer to Supported callbacks.
Session tokens after authentication
After successful authentication, PingOne Advanced Identity Cloud returns a tokenId
that applications can present as a cookie value
for other operations that require authentication.
The tokenId
contains a session token—a
representation of the exchange of information and credentials between PingOne Advanced Identity Cloud and the user or identity.
If server-side sessions are enabled, the tokenId
is a reference to the session state stored in the CTS
token store.
The following is a common scenario when accessing PingOne Advanced Identity Cloud by using REST API calls:
-
Call the
/json/authenticate
endpoint to log a user in.This call returns a
tokenID
value, which is used in subsequent calls to identify the user:$ curl \ --request POST \ --header 'Content-Type: application/json' \ --header 'X-OpenAM-Username: bjensen' \ --header 'X-OpenAM-Password: Secret12!' \ --header 'Accept-API-Version: resource=2.0, protocol=1.0' \ 'https://<tenant-env-fqdn>/am/json/realms/root/realms/alpha/authenticate' { "tokenId":"AQIC5wM...TU3OQ*", "successUrl": "/enduser/?realm=/alpha", "realm":"/alpha" }
The returned
tokenID
is called a session token (also referred to as an SSO token). Each REST API call made after successful authentication must present the session token in the HTTP header as proof of authentication. -
Call one or more additional REST APIs on behalf of the authenticated user.
Each REST API call passes the user’s
tokenID
back to PingOne Advanced Identity Cloud in the HTTP header as proof of previous authentication.The following is a partial example of a
curl
command that inserts the token ID returned from a prior successful authentication attempt into the HTTP header:$ curl \ --request POST \ --header "Content-Type: application/json" \ --header "<session-cookie-name>: AQIC5w...NTcy*" \ --header "Accept-API-Version: resource=2.0, protocol=1.0" \ --data '{...}' ...
Observe that the session token is inserted into a header field named
<session-cookie-name>
. This header field name must correspond to the name of the tenant session cookie.To find the name of the session cookie, refer to How do I view the tenant session cookie name?
Once a user has authenticated, you do not need to insert login credentials in the HTTP header in subsequent REST API calls. Note the absence of
X-OpenAM-Username
andX-OpenAM-Password
headers in the preceding example.Users must have appropriate privileges to access PingOne Advanced Identity Cloud functionality using the REST API.
-
Use the REST API to log the user out of PingOne Advanced Identity Cloud, as described in Log out using REST.
As with other REST API calls made after a user has authenticated, the REST API call to log out of PingOne Advanced Identity Cloud requires the user’s
tokenID
in the HTTP header.
Log out using REST
Authenticated users can log out with the token cookie value and an HTTP POST request to /json/sessions/?_action=logout
:
$ curl \
--request POST \
--header "<session-cookie-name>: AQICS...NzEz*" \
--header "Accept-API-Version: resource=3.1, protocol=1.0" \
'https://<tenant-env-fqdn>/am/json/realms/root/realms/alpha/sessions/?_action=logout'
{
"result":"Successfully logged out"
}
Single sign-on
Single sign-on (SSO) lets users who have authenticated to Advanced Identity Cloud access multiple independent services from a single login session by storing user sessions as HTTP cookies.
Cross-domain single sign-on (CDSSO) provides SSO inside the same organization within a single domain or across domains. For example, CDSSO lets servers in the DNS domain .internal.net
provide authentication and
authorization to web and Java agents from the .internal.net
domain and other DNS domains, such as .example.net
.
Because CDSSO removes the constraint of configuring SSO depending on the DNS domain, it simplifies the deployment of SSO in your environment.
When implementing CDSSO, take into account the following points:
-
For SSO across multiple organizations or when integrating with other access management software, use PingOne Advanced Identity Cloud’s federation capabilities, such as OAuth 2.0 or SAML 2.0.
-
Web agents and Java agents both support CDSSO.
PingOne Advanced Identity Cloud also supports CDSSO with PingGateway version 6 or later. For details, refer to Single sign-on and cross-domain single sign-on in the PingGateway documentation.
Web agents and Java agents wrap the SSO session token inside an OpenID Connect (OIDC) JSON Web Token (JWT).
During the CDSSO flow, the agents create cookies for the different domains specified in the agent profile,
and the oauth2/authorize
endpoint authorizes the different cookie domains as required.
The following diagram illustrates the CDSSO flow for web agents and Java agents:
Realms and SSO
When changing authentication realms, a subject leaves the current SSO realm. The new SSO realm might apply to different applications, and use a different authentication process. Logging in to a new realm means logging out of the current realm.
When a user interactively changes realms, PingOne Advanced Identity Cloud offers the option of logging out of the current realm to log in to the new realm, or choosing to remain logged in to the current realm.
The result depends on the user’s choice:
-
If the user cancels the change at this point, the user remains logged in to the current realm and is not logged in to the new realm.
-
If the user chooses to log in to the new realm, PingOne Advanced Identity Cloud first logs the user out of the current realm then prompts the user to log in to the new realm.
HTTP cookies
To understand how SSO works, you need to understand some key elements of the HTTP cookie, as described in RFC 6525, HTTP State Management Mechanism.
Within an HTTP cookie, you can store a single custom name=value
pair, such as sessionid=value
.
Other properties within a cookie are as follows:
- Domain
-
Also known as the cookie domain, this is the domain with which the cookie is associated. The default value is the current domain. To work with multiple subdomains, set the
Domain
to a URL such asDomain=server.example.net
. - Path
-
The directory in the URL to which the cookie applies. If
Path=/openam
, the cookie applies to the/openam
subdirectory of the URL, and lower level directories, includingopenam/XUI
.
- Expires
-
You can limit the lifetime of a cookie with an
Expires
property set to a time based on UTC (GMT).
Do not take a shortcut with a top-level domain.
Web browser clients are designed to ignore cookies set to top-level domains including |
Implement CDSSO
Cross-domain single sign-on (CDSSO) provides SSO capabilities for PingOne Advanced Identity Cloud and web or Java agents within a single domain or across domains in the same organization.
CDSSO is the only mode of operation for web and Java agents, so no additional configuration is required to make it work.
PingGateway also supports CDSSO with PingOne Advanced Identity Cloud. For details, refer to the PingGateway Gateway Guide. |
Troubleshooting SSO
In general, problems with single sign-on relate to some sort of mismatch of domain names.
For example, a cookie that is configured on a third-level domain, such as sso.example.net
,
will not work with an application on a similar domain, such as app.example.net
.
The following list describes scenarios that may lead to similar problems:
-
When a cookie domain does not match a domain for the protected application.
Assume the application is configured on a domain named
example.org
. That application will not receive an SSO token configured on theexample.net
domain. -
When a third-level domain is used for the SSO token.
If an SSO token is configured on
sso.example.net
, an application onapp.example.net
does not receive the corresponding session token. In this case, the solution is to configure the SSO token onexample.net
. -
When the
Cookie Security
or theCDSSO Secure Enable
properties are configured in the agent profile with a regular HTTP application.If you need encrypted communications for an application protected by PingOne Advanced Identity Cloud, use the
Cookie Security
or theCDSSO Secure Enable
properties and make sure the application is accessible over HTTPS. -
When the path listed in the cookie does not match the path for the application.
Perhaps the cookie is configured with a
/helloworld
path; that will not match an application that might be configured with a/hellomars
path. In that case, the application will not receive the cookie. -
When an inappropriate name is used for the cookie domain.
As noted earlier, client browsers are configured to ignore first-level domains, such as
com
andnet
as well as functional equivalents, such asco.uk
andco.jp
. -
When working with different browsers.
The
name=value
pairs described earlier may not apply to all browsers. The requirements for an HTTP cookie sent to an IE browser may differ from the requirements for other standard browsers, such as Firefox and Chrome. Based on anecdotal reports, IE does not recognize domain names that start with a number. In addition, IE reportedly refuses cookies that include the underscore (_
) character in the FQDN.
Social authentication
PingOne Advanced Identity Cloud supports delegated authentication through third-party identity providers, such as Facebook and Google. This lets users register and log in to PingOne Advanced Identity Cloud using an account they have through another trusted service.
To configure social authentication, refer to Social authentication.
Suspended authentication
Suspended authentication lets you save a user’s progress through an authentication journey and later resume from the same point.
Any input provided during authentication is saved when the authentication journey is suspended and restored when the authentication journey is resumed. This lets the authentication journey continue if the user closes their browser, uses a different browser, or uses a different device.
When you suspend an authentication journey, you give the user a URL they must visit to resume their authentication. The URL contains a unique identifier for retrieving the saved progress and can only be used once. These URLs are sometimes referred to as magic links.
The Email Suspend node supports suspended authentication.
Typical use cases include passwordless authentication and email verification during progressive profile completion.
The following journey lets a user authenticate if they have forgotten their username:
After obtaining the user’s email address in the Attribute Collector node, the journey attempts to identify the user. The journey then attempts to email the user and suspends itself.
Note both the True and False outcomes are mapped into the Email Suspend node to reduce potential data leakage. If the username is found, it is included in the email sent to the user, along with the link to use to resume the authentication journey.
When the user follows the link, the authentication journey resumes at the Inner Tree Evaluator node, which lets the user authenticate with their recovered username and credentials.
Configure suspended authentication timeouts
You can configure the length of time an authentication session can last so that resources can be freed up if authentication is not completed. You can also configure the length of time that a journey can be suspended.
Set these values to the minimum reasonable time required to complete the authentication. For example, if you are sending an email, 10 minutes might be reasonable.
The time allowed for suspending authentication must be the same as or less than the maximum duration of the journey.
To configure these timeouts, under Native Consoles > Access Management, go to Authentication > Settings > Trees. Set the Max duration and Suspended authentication duration properties. For information about these properties, refer to Trees.
MFA: Authenticate using a device with WebAuthn
WebAuthn lets users authenticate by using an authenticator device, for example, the fingerprint scanner on their laptop or phone.
The user’s browser communicates with the authenticator device. PingOne Advanced Identity Cloud can request that the browser activates authenticator devices with specified criteria. Example criteria are that the authenticator device must be built-in, not a USB device that the user can eject, or that the device must verify the user’s identity, not just the user’s presence.
To use WebAuthn with PingOne Advanced Identity Cloud, users must first register their authenticators. If recovery codes are enabled, users should copy their codes on successful registration.
Registration involves the selected authenticator creating, or minting, a key pair. The public key of the pair is returned to PingOne Advanced Identity Cloud and stored in the user’s profile. The private key is stored securely in the authenticator itself or in the platform managing the authenticators. The private key does not leave the client at any time.
When authenticating with WebAuthn, the authenticator device locks data with its stored private key and sends it to PingOne Advanced Identity Cloud. PingOne Advanced Identity Cloud verifies the data using the public key stored in the user’s profile. If the data verification succeeds and passes any attestation checks, PingOne Advanced Identity Cloud considers the authentication successful.
The user must connect over HTTPS to use WebAuthn. |
PingOne Advanced Identity Cloud supports WebAuthn for the following user agents on the specified platforms:
Browser(1) | Platform |
---|---|
Google Chrome |
Desktop |
Android |
|
Safari |
Desktop |
iOS |
|
Microsoft Edge |
Desktop |
Mozilla Firefox |
Desktop |
(1) Latest stable versions are supported.
Create journeys for WebAuthn
The example journey that follows registers the user’s device if necessary, and authenticates the user with the device. If the user has already registered their device, they only need to enter their username, and then perform the authorization gesture with their registered device to complete authentication.
If the user does not have a registered device, they must provide both their username and their password. The Data Store Decision node confirms their identity before allowing them to register their device. The user then authenticates with the new device to complete authentication.
The journey created here does not include user-friendly features, such as letting the user retry their password if they mistype it. |
Configure the WebAuthn Profile Encryption service
Configure the WebAuthn Profile Encryption service for the realm where you create the journey.
This service configures how PingOne Advanced Identity Cloud stores registered device metadata.
-
Under Native Consoles > Access Management > Realms > Realm Name, click Services > Add a Service.
-
Select WebAuthn Profile Encryption Service in the service type drop-down list, and create the new service configuration.
-
Accept the default configuration unless you must encrypt the device metadata in user profiles:
- Profile Storage Attribute
-
webauthnDeviceProfiles
(default) - Device Profile Encryption Scheme
-
If you choose an encryption scheme, also edit the settings to access the keys. For details, read Use ESVs for signing and encryption keys.
Default:
No encryption of device settings.
You can find detailed information about the available properties in WebAuthn Profile Encryption Service.
Create the WebAuthn journey
-
Configure the WebAuthn Profile Encryption service for the realm if you have not already done so.
-
In the Advanced Identity Cloud admin UI, start a custom journey for WebAuthn.
Learn more in Custom journeys.
-
In the Advanced Identity Cloud admin UI, add the following nodes to your journey:
-
Connect the nodes as demonstrated in the following figure:
-
On the WebAuthn Authentication node, select Allow recovery codes.
-
On the WebAuthn Registration node, select Generate recovery codes.
-
Save your changes.
Test the WebAuthn journey
-
Register a test user account unless you have already done so.
-
In an incognito browser window, browse to the WebAuthn journey. The URL looks something like:
https://<tenant-env-fqdn>/am/XUI/?realm=alpha&authIndexType=service&authIndexValue=myWebAuthnJourney
A login screen prompts for the username.
-
Enter the username for the test user account.
-
If the user does not have a registered device:
-
Enter the test user’s password when prompted.
-
Register a WebAuthn authenticator by performing an authorization gesture.
For example, press the button on a connected YubiKey or scan your fingerprint.
The browser may present a consent pop-up to allow access to the available authenticators.
When you grant consent, the browser activates the relevant authenticators, ready for registration.
If the device registration is successful, the journey returns to the WebAuthn Authentication node.
-
-
When prompted, authenticate by performing an authorization gesture with a registered device.
The UI displays the user profile page.
-
Browse to Edit Your Profile > 2-Step Verification > Change.
The UI displays a list of the registered devices that you can rename or delete.
The default name for a new WebAuthn device is
New Security Key
.
Configure usernameless authentication with ForgeRock Go
With ForgeRock Go, you can create a secure and seamless login experience by authenticating with any credential on the user’s device that supports FIDO2 WebAuthn.
You can also extend passwordless authentication to include usernameless authentication with popular authenticators that support resident keys; for example, Windows Hello (biometric authenticators).
To use usernameless authentication, you must register an authenticator that supports resident keys to the user’s profile, and enable the option to associate a certificate on the device with the user’s username.
Once registered, that device can be used to authenticate the user without them having to provide their credentials; they need to select the appropriate entry to use from the list their device provides.
To configure usernameless authentication with ForgeRock Go, create a web authentication registration journey to associate a device that supports resident keys with a user. The registration journey is similar to that described in Create journeys for WebAuthn.
Create a second journey that lets users authenticate to PingOne Advanced Identity Cloud without entering their username or password, by using ForgeRock Go.
The journeys created here do not include user-friendly features, such as allowing retries or redirecting for further help on failures. |
Create the ForgeRock Go registration journey
-
Configure the WebAuthn Profile Encryption service for the realm if you have not already done so.
-
In the Advanced Identity Cloud admin UI, start a custom journey for ForgeRock Go registration.
Learn more in Custom journeys.
-
In the Advanced Identity Cloud admin UI, add the following nodes to your journey:
-
(Optional) Scripted Decision node
When configured for ForgeRock Go, by default the WebAuthn Registration node stores the journey’s shared state variable
username
on the device. During authentication, this value later identifies the user.Use a Scripted Decision node to customize the display name or string to be saved in the shared state.
Script to set the display name-
Next-generation
-
Legacy
var user = nodeState.get('username'); var identity = idRepository.getIdentity(user); var displayName = ''; var givenName = identity.getAttributeValues('givenName')[0]; var surname = identity.getAttributeValues('sn')[0]; var email = identity.getAttributeValues('mail')[0]; if (givenName) { displayName += givenName; } if (surname) { displayName += ' ' + surname; } if (email) { displayName += ' (' + email + ')'; } if (displayName) { nodeState.putShared('displayName', displayName); } else { nodeState.putShared('displayName', user); } action.goTo("true");
var fr = JavaImporter(org.forgerock.openam.auth.node.api.Action); var user = nodeState.get('username').asString(); var displayName = ''; var givenName = idRepository.getAttribute(user, 'givenName'); var surname = idRepository.getAttribute(user, 'sn'); var email = idRepository.getAttribute(user, 'mail'); if (givenName) { displayName += givenName.toArray()[0]; } if (surname) { displayName += ' ' + surname.toArray()[0]; } if (email) { displayName += ' (' + email.toArray()[0] + ')'; } if (displayName) { nodeState.putShared('displayName', displayName.toString()); } else { nodeState.putShared('displayName', user.toString()); } outcome = 'true'; action = fr.Action.goTo("true").build();
-
-
Connect the nodes as demonstrated in the following figure:
If you do not use the Scripted Decision node, connect the Identity Store Decision node
True
output directly to the WebAuthn Registration node. -
On the Identity Store Decision node, select Username as Universal Identifier.
-
If you use the Scripted Decision node:
-
Select your script in the Script list.
-
Add the outcome of your script,
true
in this example, in the Outcomes field.
-
-
On the WebAuthn Registration node:
-
Select Username to device.
-
If you do not use the Scripted Decision node, add
userName
in the Shared state attribute for display name field. -
If you use the Scripted Decision node, add the shared state variable name, such as
displayName
, in the Shared state attribute for display name field.
-
-
Save your changes.
Create the ForgeRock Go authentication journey
-
Configure the WebAuthn Profile Encryption service for the realm if you have not already done so.
-
In the Advanced Identity Cloud admin UI, start a custom journey for ForgeRock Go authentication.
Learn more in Custom journeys.
-
In the Advanced Identity Cloud admin UI, add a WebAuthn Authentication node to your journey.
-
Connect the nodes as demonstrated in the following figure:
-
On the WebAuthn Authentication node, ensure Username from device is enabled.
-
Save your changes.
Register with ForgeRock Go
Follow these steps to register a device for usernameless authentication, and then authenticate with no username or password, only an authorization gesture.
-
Register a test user account unless you have already done so.
-
In an incognito browser window, browse to the ForgeRock Go registration journey. The URL looks something like:
https://<tenant-env-fqdn>/am/XUI/?realm=alpha&authIndexType=service&authIndexValue=myForgeRockGoRegistrationJourney
A login screen prompts for your credentials.
-
Sign in with the username and password of the test user.
-
If you are authenticating from a FIDO2-enabled device, it prompts you for the method to verify your identity.
For example, you might use a USB security key or a built-in biometric sensor.
Select the option to associate with the user.
-
Perform the authorization gesture of the chosen option when asked to do so.
For example, press the button on your USB security key or scan your fingerprint.
The UI displays the user profile page.
-
Browse to Edit Your Profile > 2-Step Verification > Change.
The UI displays a list of the registered devices that you can rename or delete.
The default name for the WebAuthn device is
New Security Key
. -
(Optional) Click the ellipsis icon, , select Edit Name, and give a suitable name to the new WebAuthn device, such as
MacBook Touch ID
.
Authenticate with ForgeRock Go
After registering, authenticate with ForgeRock Go without your username or password:
-
Sign out.
-
In the same browser window, browse to the ForgeRock Go authentication journey. The URL looks something like:
https://<tenant-env-fqdn>/am/XUI/?realm=alpha&authIndexType=service&authIndexValue=myForgeRockGoAuthenticationJourney
-
Perform the authorization gesture of the chosen option when prompted.
A list of the accounts associated with the authentication device displays:
In this example, the user’s full name and email address appear. The Scripted Decision node gathered them during registration.
-
Select the account to sign in.
The UI displays the user profile page without you having to enter your username or password.
To design simple user journeys that invoke biometric sensors on FIDO2-enabled devices to add biometrics to your authentication journeys, refer to the Community blog Use case: Configure biometric authentication in PingOne Advanced Identity Cloud. |
MFA: Authenticate using push notification
You can use push notifications as part of the authentication process.
To receive push notifications when authenticating, end users must register an Android or iOS device with PingOne Advanced Identity Cloud. The registered device can then be used as an additional factor when authenticating. PingOne Advanced Identity Cloud can send the device a push notification, which can be accepted by the ForgeRock Authenticator app. In the app, the user can allow or deny the request that generated the push notification and return the response to PingOne Advanced Identity Cloud.
About push
The following steps occur as a user completes a push notification journey:
-
The user provides credentials to let PingOne Advanced Identity Cloud locate the user profile and determine if they have a registered mobile device.
-
PingOne Advanced Identity Cloud prompts the user to register a mobile device if they have not done so already.
The user registers their device through the ForgeRock Authenticator app. The app supports a variety of methods to respond to push notifications from tapping a button to biometrics if the device supports them.
Registering a device stores device metadata in the user profile that is required for push notifications. PingOne Advanced Identity Cloud uses the configured ForgeRock Authenticator (Push) service, which supports encrypting the metadata.
For more information, refer to Manage devices for MFA.
-
When the user has a registered device, PingOne Advanced Identity Cloud creates a push message specific to the device.
The message has a unique ID that PingOne Advanced Identity Cloud stores while waiting for the response.
PingOne Advanced Identity Cloud writes a pending record with the same message ID to the CTS store for redundancy should an individual server go offline during the authentication process.
-
PingOne Advanced Identity Cloud sends the push message to the registered device, using the configured push notification service.
Depending on the registered device, PingOne Advanced Identity Cloud uses either Apple Push Notification Services (APNS) or Google Cloud Messaging (GCM) to deliver the message.
PingOne Advanced Identity Cloud begins to poll the CTS for an accepted response from the registered device.
-
The user responds to the notification through the ForgeRock Authenticator app on the device, for example, approving or rejecting the notification.
The app responds to the push notification message with the user’s choice.
-
PingOne Advanced Identity Cloud verifies the message is from the correct registered device and has not been tampered with, and marks the pending record as accepted if valid.
PingOne Advanced Identity Cloud detects the accepted record and redirects the user to their profile page, completing the authentication.
Implement push
The following table summarizes the tasks to perform to implement push authentication in your environment:
Task | Resources |
---|---|
Configure authentication If you’re planning to implement passwordless push authentication, see also Limitations of passwordless push authentication. |
|
Test push authentication After configuring the ForgeRock Authenticator (Push) service, the push notification service, and a push authentication journey, download the ForgeRock Authenticator app and test your configuration. |
Push authentication journeys
Configure authentication journeys for passwordless authentication and to receive push notifications.
When configured for passwordless authentication, the authentication flow requires the user to enter their user ID, but not their password. A push notification is then sent to their registered device to complete authentication with the ForgeRock Authenticator app.
Before implementing passwordless push authentication, consider the Limitations of passwordless push authentication.
Configure the ForgeRock Authenticator (Push) service
Configure the ForgeRock Authenticator (Push) service for the realm where you create the journey.
This service specifies the user profile attribute that stores registered device metadata.
-
Under Native Consoles > Access Management > Realms > Realm Name, click Services > Add a Service.
-
Select ForgeRock Authenticator (Push) Service in the service type drop-down list, and create the new service configuration.
-
Accept the default configuration unless you must encrypt the device metadata in user profiles:
- Profile Storage Attribute
-
pushDeviceProfiles
(default) - Device Profile Encryption Scheme
-
If you choose an encryption scheme, also edit the settings to access the keys.
For details, read Use ESVs for signing and encryption keys.
Default:
No encryption of device settings.
- ForgeRock Authenticator (Push) Device Skippable Attribute Name
-
push2faEnabled
(default)For details, read the reference documentation, ForgeRock Authenticator (Push) Service.
Configure the Push Notification service
Under Native Consoles > Access Management, configure the Push Notification service for the realm.
PingOne Advanced Identity Cloud uses an external AWS service to send push notifications. Its configuration requires access keys and other metadata. As a Ping Identity customer, you have streamlined access to the required metadata: Before you start, log in to Backstage, then follow the instructions in How To Configure Service Credentials (Push Auth, Docker) in Backstage. Download the AWS credential data in JSON format and refer to that as you configure the service. |
-
Under Native Consoles > Access Management > Realms > Realm Name, click Services > Add a Service.
-
Select Push Notification Service in the service type drop-down list.
-
Update the following fields with the data you generated on Backstage, then create the new service configuration:
- SNS Access Key ID
-
The generated Key ID; the
"accessKeyId"
in the JSON - SNS Access Key Secret
-
The generated Secret; the
"accessKeySecret"
in the JSON - SNS Endpoint for APNS
-
The generated APNS; the
"APNS"
in the JSON - SNS Endpoint for GCM
-
The generated GCM; the
"GCM"
in the JSON
You can also store the Access Key Secret in a secret store. For additional details, refer to the reference documentation, Push Notification Service.
Create a push authentication journey
The procedure assumes the following:
-
Users provide user IDs and passwords as the first step of multi-factor authentication (MFA).
-
PingOne Advanced Identity Cloud sends the push notification to the device as an additional factor to complete authentication.
-
You have prepared the prerequisite services, described in Configure the ForgeRock Authenticator (Push) service and Configure the Push Notification service.
-
In the Advanced Identity Cloud admin UI, create a custom journey for push notification.
Learn more in Custom journeys.
-
Add the following nodes to your journey:
-
Connect the nodes as demonstrated in the following figure:
Figure 4. Example Push Authentication JourneyNode connections
Table 3. List of node connections Source node Outcome path Target node Page Node containing:
-
Platform Username
-
Platform Password
→
Data Store Decision
Data Store Decision
True
Push Sender
False
Failure
Push Sender
Sent
Push Wait
Not Registered
MFA Registration Options
Push Wait
Done
Push Result Verifier
Exit
Recovery Code Collector Decision
Push Result Verifier
Success
Success
Failure
Failure
Expired
Push Sender
Waiting
Push Wait
MFA Registration Options
Register
Push Registration
Get App
Get Authenticator App
Skip
Success
Opt-out
Opt-out Multi-Factor Authentication
Recovery Code Collector Decision
True
Success
False
Retry Limit Decision
Push Registration
Success
Recovery Code Display Node
Failure
Failure
Time Out
MFA Registration Options
Get Authenticator App
→
MFA Registration Options
Opt-out Multi-Factor Authentication
→
Success
Retry Limit Decision
Retry
Recovery Code Collector Decision
Reject
Failure
Recovery Code Display Node
→
Push Sender
-
-
Save your changes.
-
Test your authentication journey as follows:
-
Copy and paste the Preview URL into a browser in incognito mode. The URL will look something like:
https://<tenant-env-fqdn>/am/XUI/?realm=alpha&authIndexType=service&authIndexValue=myPushAuthJourney
A login screen prompting you to enter your user ID and password appears.
-
Verify that you can use the ForgeRock Authenticator app to perform MFA.
If the authentication journey is correctly configured, authentication is successful and PingOne Advanced Identity Cloud displays the user profile page. For details, refer to Test push authentication.
-
-
Create a passwordless authentication journey
The procedure assumes the following:
-
Users provide only their user IDs as the first step of MFA.
-
Users have pre-registered a device for push authentication.
-
PingOne Advanced Identity Cloud sends the push notification to the device as an additional factor to complete authentication, without needing the user’s password.
-
You have prepared the prerequisite services, described in Configure the ForgeRock Authenticator (Push) service and Configure the Push Notification service.
-
In the Advanced Identity Cloud admin UI, create a custom journey for push notification.
For details, refer to Custom journeys.
-
Add the following nodes to your journey:
-
Connect the nodes as demonstrated in the following figure:
Figure 5. Passwordless Push Authentication Example -
Save your changes.
-
Test your authentication journey as follows:
-
Copy and paste the Preview URL into a browser in incognito mode. The URL will look something like:
https://<tenant-env-fqdn>/am/XUI/?realm=alpha&authIndexType=service&authIndexValue=myPasswordlessAuthJourney
A login screen appears, prompting you to enter your user ID.
-
Verify that you can use the ForgeRock Authenticator app to perform MFA.
If the authentication journey is correctly configured, authentication is successful and PingOne Advanced Identity Cloud displays the user profile page without the user entering their password.
For details, refer to Test push authentication.
-
-
Test push authentication
PingOne Advanced Identity Cloud presents you with a page for entering only your user ID, or user ID and password. After you provide those credentials, PingOne Advanced Identity Cloud verifies them. If your credentials are valid and the account has a device registered for push notifications, PingOne Advanced Identity Cloud sends a push notification to the registered device.
If the user does not yet have a device registered for push authentication, refer to Register.
The device needs access to the Internet to receive push notifications, and PingOne Advanced Identity Cloud must be able to receive responses from the device. |
Receive push notifications
On your registered device, you will receive a push notification from PingOne Advanced Identity Cloud. Depending on the state of the device and the ForgeRock Authenticator application, respond to the notification as follows:
-
Unlock the device, if necessary, when you receive a device notification from the application.
The ForgeRock Authenticator application opens and displays the push notification.
-
If the device is unlocked, but the ForgeRock Authenticator application is not open, select the device notification to open the application and display the push notification.
-
Open the ForgeRock Authenticator application to respond quickly to notifications.
Approve requests
How you approve requests depends on the ForgeRock Authenticator application settings, and on what the device supports.
Default settings for push notifications use a simple pop up in the application, similar to the following:
Deny requests
Deny the request by tapping the cancel icon in the top-right of the screen or, if Touch ID or face recognition are enabled, tap the Reject button.
If you do not approve or deny the request on the registered device, the Push Authentication page times out and authentication fails. You can configure this through the Message Timeout in the Push Sender node for the journey. |
Register
If your credentials are valid but your profile is missing the metadata for a registered device registered, the MFA Registration Options node of the journey governs what happens:
- Register Device
-
Configure the journey to continue to the Push Registration node.
When completing the journey, scan the QR code it displays with the ForgeRock Authenticator application.
For additional details, refer to Register the ForgeRock Authenticator for multi-factor authentication.
- Get the application
-
Configure the journey to continue to the Get Authenticator App node.
When completing the journey, follow the link needed to obtain the ForgeRock Authenticator application for your device.
- Skip this step
-
(Optional) In the example journey, skipping is linked to the Success node.
- Opt-out
-
Configure the journey to continue to the Opt-out Multi-Factor Authentication node and let the user not use push.
In the example journey, opting out is linked to the Success node.
Configure successful registration to return to the Push Sender node, which starts the actual push notification stage of the journey, and the user can Receive push notifications.
Limitations of passwordless push authentication
When authenticating to a passwordless push authentication journey, the user enters their user ID, but not their password. PingOne Advanced Identity Cloud sends a push notification to their device to complete the authentication.
Be aware of the following limitations when you implement passwordless push authentication:
-
Unsolicited push messages can be sent to a user’s registered device by anyone who knows (or is able to guess) their user ID.
-
If a malicious user attempts to authenticate by using push at the same time as a legitimate user, the legitimate user might unintentionally approve the malicious attempt. This is because push notifications only contain the username and issuer in the text, and it’s not easy to determine which notification relates to which authentication attempt.
Consider using push notifications as part of MFA, and not on their own.
MFA: Use codes from ForgeRock app using OATH
The ForgeRock Authenticator (OATH) nodes support HMAC one-time password (HOTP) and time-based one-time password (TOTP) authentication as defined in the OATH standard protocols for HOTP (RFC 4226) and TOTP (RFC 6238). Both HOTP and TOTP authentication require an OATH-compliant device that can provide the password.
About one-time password support
HOTP authentication generates the one-time password (OTP) every time the user requests a new password on their device. The device tracks the number of times the user requests a new one-time password with a counter. The one-time password displays for a period of time you designate in the setup, so the user may be further in the counter on their device than on their account.
PingOne Advanced Identity Cloud resynchronizes the counter when the user finally logs in. To accommodate this, you set the number of passwords a user can generate before their device cannot be resynchronized. For example, if you set the number of HOTP Window Size to 50 and someone presses the button 30 times on the user’s device to generate a new password, the counter in PingOne Advanced Identity Cloud will review the passwords until it reaches the one-time password entered by the user. If someone presses the button 51 times, you will need to reset the counter to match the number on the device’s counter before the user can log in to PingOne Advanced Identity Cloud. HOTP authentication does not check earlier passwords, so if the user attempts to reset the counter on their device, they will not be able to log in until you reset the counter in PingOne Advanced Identity Cloud to match their device. For more information, refer to Reset registered devices using REST.
TOTP authentication constantly generates a new one-time password based on a time interval you specify. The device tracks the last several passwords generated and the current password. The TOTP Time Steps setting configures the number of passwords tracked. The Last Login Time setting monitors the time when a user logs in to make sure that user is not logged in several times within the present time period. The TOTP Time-Step Interval should not be so long as to lock users out, with a recommended time of 30 seconds.
Create a journey for one-time password authentication
The following example journey uses TOTP, the default:
-
In the Advanced Identity Cloud admin UI, start a custom OATH journey.
Learn more in Custom journeys.
-
In the Advanced Identity Cloud admin UI, add the following nodes to your journey:
-
On the first OATH Token Verifier node, select Allow recovery codes.
-
On the OATH Registration node, select Generate Recovery Codes.
The value for OATH Algorithm must be the same for the registration and verification nodes.
-
Connect the nodes as shown:
-
Save your changes.
This journey demonstrates OATH authentication. In a production environment, you could include additional nodes, such as:
- Get Authenticator App node
-
Displays links to the ForgeRock Authenticator app for Android and iOS.
- MFA Registration Options node
-
Provides options for users to register a multi-factor authentication device, get the authenticator app, or skip the registration process.
- Opt-out Multi-Factor Authentication node
-
Sets an attribute in the user’s profile which lets them skip multi-factor authentication.
Authenticate using a one-time password
After creating the journey, try it:
-
Register a test user account unless you have already done so.
-
In an incognito browser window, browse to the journey. The URL looks something like:
https://<tenant-env-fqdn>/am/XUI/?realm=alpha&authIndexType=service&authIndexValue=myOathTotpJourney
A login screen prompts for your credentials.
-
Sign in with the username and password of the test user.
A registration screen prompts to display a QR code.
-
Register an authenticator, such as the ForgeRock Authenticator app, by scanning the QR code.
The journey registers your one-time password app and displays recovery codes.
-
Save the recovery codes and click Done to proceed to one-time password authentication.
-
Enter the one-time password from your app, and click Submit:
If the animated timer indicates the one-time password is close to expiry, wait for the app to generate a new one.
The UI displays the user profile page.
-
Browse to Edit Your Profile > 2-Step Verification > Change.
The UI displays your registered devices.
The one-time password app you registered is named
OATH Device
.
Manage devices for MFA
Multi-factor authentication requires you to register a device, which is used as an additional factor when you log in to PingOne Advanced Identity Cloud.
The following table summarizes different tasks related to devices used for multi-factor authentication:
Task | Resources |
---|---|
Learn about the ForgeRock Authenticator Download the ForgeRock Authenticator app, which supports push authentication notifications and one-time passwords, and register it in PingOne Advanced Identity Cloud. |
|
Recovering user accounts Learn how to recover a user account when the user has lost their registered device, or when their device has become out of sync with PingOne Advanced Identity Cloud. |
|
Reset registered devices In some scenarios, for example, when users are not able to access their recovery codes, you can reset their registered devices to allow them to register again. |
|
List registered devices Learn how to list devices registered to a user. |
MFA details are stored in the following profile attributes:
You can access these attributes in scripts in the same way you access other profile attributes. |
The ForgeRock Authenticator application
The ForgeRock Authenticator application supports push authentication notifications and one-time passwords.
Download and install the ForgeRock Authenticator application to perform multi-factor authentication. The application is available for both Android and iOS devices, and is free to download from:
To build your own authenticator application, integrate the ForgeRock Authenticator module using Ping Identity SDKs. |
Register the ForgeRock Authenticator for MFA
Register the ForgeRock Authenticator application to use it as an additional factor when logging in.
The ForgeRock Authenticator application supports registration of multiple accounts and multiple different authentication methods in each account, such as push notifications and one-time passwords.
For information on registering Web Authentication (WebAuthn) devices with PingOne Advanced Identity Cloud, refer to Create journeys for WebAuthn.
You register the ForgeRock Authenticator application once per authentication method with an identity provider. For example, if one journey uses push notifications and another uses one-time passwords, you must register the application separately for push notifications and one-time passwords.
The ForgeRock Authenticator application must access the internet to register to receive push notifications. Registering for one-time password authentication does not require a connection to the internet.
-
When accessing a protected resource that requires multi-factor authentication, PingOne Advanced Identity Cloud prompts you to register a device, and displays a QR code screen:
-
If you are logging in on the device and cannot scan the screen, click the On a mobile device? link to launch the application and register the device, bypassing the QR code.
-
If you are logging in on a computer, start the ForgeRock Authenticator application and click its plus icon () to register the device.
The screen on the device changes to an interface similar to your camera app.
Scan the QR code with the ForgeRock Authenticator app.
The application displays the account you registered in the list of accounts.
-
-
After registering your device, you MUST make a copy of the recovery codes for the account.
Store the recovery codes separately from your device. The recovery codes will never be displayed again. They serve as one time verification codes to log in if your registered device is lost, stolen, or broken.
When you have safely stored the recovery codes for your newly registered push device, click Done.
-
If prompted, respond to the push notification or enter a one-time password from the app.
Your device is now registered. You can use it to perform multi-factor authentication.
Recover after replacing a lost device
If you register a device with PingOne Advanced Identity Cloud and then lose it, you must authenticate to PingOne Advanced Identity Cloud using a recovery code. After deleting the lost device, you can register a new device.
-
Access the list of recovery codes you saved when registering the lost device.
If you did not save the recovery codes when you registered the device, contact your administrator to remove the device from your user profile instead of following these steps.
Administrators can refer to Reset registered devices using REST for details.
-
Begin to sign in as you normally would.
When prompted to use a multi-factor option, click the Use Recovery Code link.
-
Enter the recovery code when prompted.
Because recovery codes are valid for a single use only, remove the code you used from your list.
PingOne Advanced Identity Cloud lets you sign in to access your profile page.
-
Browse to Edit Your Profile > 2-Step Verification > Change.
The UI displays the list of the registered devices.
Delete the lost device from your profile.
-
Register your new device by signing out, then accessing the protected resource that requires MFA.
When registering for push notifications or one-time passwords, refer to The ForgeRock Authenticator application.
Recover after a device becomes out of sync
A device that generates one-time passwords can get out of sync with the OATH authentication service in some cases. If you repeatedly enter valid one-time passwords that appear to be valid passwords, but PingOne Advanced Identity Cloud rejects the passwords as unauthorized, your device is likely out of sync.
To resynchronize your device, you must authenticate with a recovery code, and register the device again. Follow the steps in Recover after replacing a lost device.
If you did not save the recovery codes when you registered the device, contact your administrator to remove the device from your user profile instead.
Reset registered devices using REST
As described in Recover after replacing a lost device, a user who has lost a mobile phone registered with PingOne Advanced Identity Cloud can register a replacement device by authenticating using a recovery code, deleting their existing device, and then registering a new device.
Additional support is required for users who lose mobile devices but did not save their recovery codes when they initially registered the device, and for users who have used up all their recovery codes.
PingOne Advanced Identity Cloud provides a REST API to reset a device profile by deleting information about a user’s registered device. Both the user and administrator accounts can use the REST API to reset a device profile. Administrators can:
-
Provide authenticated users with a self-service page that calls the REST API to reset their devices.
-
Call the REST API themselves to reset a user’s device profiles.
-
Call the REST API themselves to reset a device that is out of sync, where the HOTP counter exceeds the HOTP threshold window and requires a reset.
When making a REST API call, specify the realm in the path component of the endpoint.
You must specify the entire hierarchy of the realm.
Prefix each realm in the hierarchy with the realms/
keyword.
For example, /realms/root/realms/alpha
.
The following examples assume that you have obtained an access token with the appropriate scopes.
The API calls reference the user by |
Reset OATH devices
To reset a user’s OATH device profile,
send an HTTP POST request to the /users/user/devices/2fa/oath?_action=reset
endpoint.
The following example resets the OATH devices for a user in the alpha
realm.
The user’s _id
in this example is 014c54bd-6078-4639-8316-8ce0e7746fa4
.
$ curl \
--request POST \
--header "Content-Type: application/json" \
--header "Accept-API-Version: resource=1.0" \
--header "authorization: Bearer access-token" \
--data '{}' \
'https://<tenant-env-fqdn>/am/json/realms/root/realms/alpha/users/014c54bd-6078-4639-8316-8ce0e7746fa4/devices/2fa/oath?_action=reset'
{
"result":true
}
The reset action deletes the OATH device profile, which by default has a limit of one profile per device,
and sets the Select to Enable Skip option to its default value of Not Set
.
Reset push devices
To reset push devices over REST,
send an HTTP POST request to the /users/user/devices/2fa/push?_action=reset
endpoint.
The following example resets the push devices for a user in the alpha
realm.
The user’s _id
in this example is 014c54bd-6078-4639-8316-8ce0e7746fa4
.
$ curl \
--request POST \
--header "Content-Type: application/json" \
--header "Accept-API-Version: resource=1.0" \
--header "authorization: Bearer access-token" \
--data '{}' \
'https://<tenant-env-fqdn>/am/json/realms/root/realms/alpha/users/014c54bd-6078-4639-8316-8ce0e7746fa4/devices/2fa/push?_action=reset'
{
"result":true
}
Delete WebAuthn devices
The reset
action is not implemented on the webauthn
endpoint.
You can delete a WebAuthn device over REST as follows:
-
Retrieve a list of WebAuthn devices associated with a user by querying the
users/user/devices/2fa/webauthn
endpoint.The following example retrieves a list of WebAuthn devices for a user in the
alpha
realm. The user’s_id
in this example is014c54bd-6078-4639-8316-8ce0e7746fa4
.$ curl \ --request GET \ --header "authorization: Bearer access-token" \ 'https://<tenant-env-fqdn>/am/json/realms/root/realms/alpha/users/014c54bd-6078-4639-8316-8ce0e7746fa4/devices/2fa/webauthn?_queryFilter=true' { "result": [ { "_id": "ff1db8bf-d2d7-46e1-926a-568b877f87a5", "_rev": "163664231", "deviceName": "New Security Key", "uuid": "ff1db8bf-d2d7-46e1-926a-568b877f87a5", "deviceManagementStatus": false } ], "resultCount": 1, "pagedResultsCookie": null, "totalPagedResultsPolicy": "NONE", "totalPagedResults": -1, "remainingPagedResults": -1 }
-
Delete the required WebAuthn device from the user by sending an HTTP DELETE request to the
users/user/devices/2fa/webauthn/device-id
endpoint, including the ID of the WebAuthn device you want to delete:$ curl \ --request DELETE \ --header "Accept-API-Version: resource=1.0" \ --header "authorization: Bearer access-token" \ 'https://<tenant-env-fqdn>/am/json/realms/root/realms/alpha/users/014c54bd-6078-4639-8316-8ce0e7746fa4/devices/2fa/webauthn/ff1db8bf-d2d7-46e1-926a-568b877f87a5' { "_id": "ff1db8bf-d2d7-46e1-926a-568b877f87a5", "_rev": "1642022518", "uuid": "ff1db8bf-d2d7-46e1-926a-568b877f87a5", "recoveryCodes": [ ... ], "credentialId": "XGJpYNYv4AHG9sHHgxFfTw", "algorithm": "SHA256withECDSA", "deviceName": "New Security Key", "key": { "kty": "EC", "x": "zMDAfFwRQR_5HIGfK1iJQ0kYwtudesx_UXocoBVrWbo", "y": "UgRBOBlpq6QYsXlqfHDzY8XNv-5DEMajRp9_3klkhDU", "crv": "P-256" } }
-
Repeat step 2 to delete additional WebAuthn devices for the user, if needed.
Reset bound devices
To delete all bound devices for a user, send an HTTP POST request to the /users/user/devices/2fa/binding?_action=reset
endpoint. For details on binding devices to a user profile, refer to /sdks/latest/sdks/use-cases/how-to-bind-devices.html[device binding^].
The following example deletes bound devices for a user in the alpha
realm.
The user’s _id
in this example is 014c54bd-6078-4639-8316-8ce0e7746fa4
.
$ curl \
--request POST \
--header "Content-Type: application/json" \
--header "Accept-API-Version: resource=1.0" \
--header "authorization: Bearer access-token" \
--data '{}' \
'https://<tenant-env-fqdn>/am/json/realms/root/realms/alpha/users/014c54bd-6078-4639-8316-8ce0e7746fa4/devices/2fa/binding?_action=reset'
{
"result":true
}
Deleting a bound device on the server does not remove the private keys from the device. Instead, use the ForgeRock SDKs to remove the bound device from the server, and then remove the keys from the device. Learn more in /sdks/latest/sdks/use-cases/how-to-bind-devices.html#unbind[Unbind devices by deleting keys^]. |
List registered devices over REST
PingOne Advanced Identity Cloud provides a REST API to retrieve information about MFA devices registered to a user.
When making a REST API call, specify the realm in the path component of the endpoint.
You must specify the entire hierarchy of the realm.
Prefix each realm in the hierarchy with the realms/
keyword.
For example, /realms/root/realms/alpha
.
The following examples assume that you have obtained an access token with the appropriate scopes.
The API calls reference the user by |
List OATH devices
To return a list of OATH devices registered to a user, query the users/user/devices/2fa/oath
endpoint.
The following example lists the OATH devices for a user in the alpha
realm.
The user’s _id
in this example is 014c54bd-6078-4639-8316-8ce0e7746fa4
.
$ curl \
--request GET \
--header "authorization: Bearer access-token" \
'https://<tenant-env-fqdn>/am/json/realms/root/realms/alpha/users/014c54bd-6078-4639-8316-8ce0e7746fa4/devices/2fa/oath?_queryFilter=true'
{
"result" : [ {
"_id" : "ff1db8bf-d2d7-46e1-926a-568b877f87a5",
"_rev" : "172031596",
"deviceName" : "OATH Device",
"uuid" : "ff1db8bf-d2d7-46e1-926a-568b877f87a5",
"deviceManagementStatus" : false
} ],
"resultCount" : 1,
"pagedResultsCookie" : null,
"totalPagedResultsPolicy" : "NONE",
"totalPagedResults" : -1,
"remainingPagedResults" : -1
}
List push devices
To return a list of push devices registered to a user, query the users/user/devices/2fa/push
endpoint.
The following example lists the push devices for a user in the alpha
realm.
The user’s _id
in this example is 014c54bd-6078-4639-8316-8ce0e7746fa4
.
$ curl \
--request GET \
--header "authorization: Bearer access-token" \
'https://<tenant-env-fqdn>/am/json/realms/root/realms/alpha/users/014c54bd-6078-4639-8316-8ce0e7746fa4/devices/2fa/push?_queryFilter=true'
{
"result" : [ {
"_id" : "ff1db8bf-d2d7-46e1-926a-568b877f87a5",
"_rev" : "172031596",
"deviceName" : "Push Device",
"uuid" : "ff1db8bf-d2d7-46e1-926a-568b877f87a5",
"deviceManagementStatus" : false
} ],
"resultCount" : 1,
"pagedResultsCookie" : null,
"totalPagedResultsPolicy" : "NONE",
"totalPagedResults" : -1,
"remainingPagedResults" : -1
}
List WebAuthn devices
To return a list of WebAuthn devices registered to a user, query the users/user/devices/2fa/webauthn
endpoint.
The following example lists the WebAuthn devices for a user in the alpha
realm.
The user’s _id
in this example is 014c54bd-6078-4639-8316-8ce0e7746fa4
.
$ curl \
--request GET \
--header "authorization: Bearer access-token" \
'https://<tenant-env-fqdn>/am/json/realms/root/realms/alpha/users/014c54bd-6078-4639-8316-8ce0e7746fa4/devices/2fa/webauthn?_queryFilter=true'
{
"result": [
{
"_id": "ff1db8bf-d2d7-46e1-926a-568b877f87a5",
"_rev": "163664231",
"deviceName": "New Security Key",
"uuid": "ff1db8bf-d2d7-46e1-926a-568b877f87a5",
"deviceManagementStatus": false
}
],
"resultCount": 1,
"pagedResultsCookie": null,
"totalPagedResultsPolicy": "NONE",
"totalPagedResults": -1,
"remainingPagedResults": -1
}
List bound devices
To return a list of bound devices for a user, query the users/user/devices/2fa/binding
endpoint. Learn more about binding devices to a user profile in /sdks/latest/sdks/use-cases/how-to-bind-devices.html[device binding^].
The following example lists the bound devices for a user in the alpha
realm.
The user’s _id
in this example is 014c54bd-6078-4639-8316-8ce0e7746fa4
.
$ curl \
--request GET \
--header "authorization: Bearer access-token" \
'https://<tenant-env-fqdn>/am/json/realms/root/realms/alpha/users/014c54bd-6078-4639-8316-8ce0e7746fa4/devices/2fa/binding?_queryFilter=true'
{
"result": [
{
"_id": "ff1db8bf-d2d7-46e1-926a-568b877f87a5",
"_rev": "192142989",
"createdDate": 1715182923119,
"lastAccessDate": 1715182923183,
"deviceId": "e2e84b5d2a927abdcb85570bac9701c390a92751",
"deviceName": "iOS Device",
"uuid": "ff1db8bf-d2d7-46e1-926a-568b877f87a5",
"key": {
...
},
"deviceManagementStatus": false
}
],
"resultCount": 1,
"pagedResultsCookie": null,
"totalPagedResultsPolicy": "NONE",
"totalPagedResults": -1,
"remainingPagedResults": -1
}
Account lockout
Account lockout is a security mechanism that locks a user account after repeated failed login attempts. It is used to slow down brute-force attacks and compensate for weak password policies.
You can configure account lockout in one of the following ways:
- Persistent lockout
-
Persistent (physical) lockout locks the user account indefinitely. A tenant administrator can release the lock by setting the account status to active.
For persistent lockout, Advanced Identity Cloud sets the user account status to inactive. This makes it easy for a tenant administrator to search for user accounts with a persistent lockout set. It also means that if you synchronize your user accounts from Advanced Identity Cloud to another datastore, you can track locked accounts in the downstream datastore.
This is the default type of account lockout and Ping Identity recommends it as the best way to mitigate brute force attacks.
- Duration lockout
-
Duration lockout locks the user account for a specified duration. The lock is automatically released after the specified duration.
Unlike persistent lockout, the user account status remains active. Instead, Advanced Identity Cloud tracks the locked state internally. This makes it harder for a tenant administrator to search for user accounts with a duration lockout set. It also means that if you synchronize your user accounts from Advanced Identity Cloud to another datastore, you cannot track locked accounts in the downstream datastore. However, it is possible to configure the Invalid Attempts Data Attribute Name to persist metadata about failed authentication attempts to a specified user account attribute — refer to Configure account lockout.
Failed login attempts during the transactional authorization flow do not increment account lockout counters. |
Configure account lockout
-
In the Advanced Identity Cloud admin UI, select Native Consoles > Access Management.
-
Go to Realms > Realm Name > Authentication > Settings > Account Lockout.
-
Enable lockout by checking Login Failure Lockout Mode, then set the number of attempts and the lockout interval. You can also opt to warn users after several consecutive failures.
-
To configure persistent lockout:
-
Set Login Failure Lockout Duration to 0.
-
Check Store Invalid Attempts in Data Store.
-
-
To configure duration lockout:
-
Set Login Failure Lockout Duration to a positive integer value representing number of minutes. Set a value of at least 15. Optionally, configure a multipier to increase the lockout duration on each successive lockout.
-
Check Store Invalid Attempts in Data Store.
-
Set Invalid Attempts Data Attribute Name to
sunAMAuthInvalidAttemptsData
. Alternatively, to persist invalid attempts metadata to the user account, set Invalid Attempts Data Attribute Name to a valid attribute; for example,fr-attr-istr1
. For a list of valid attributes, refer to the User identity attributes and properties reference.
-
-
Click Save Changes.
Success and Failure nodes
If you enable account lockout in a realm, the Success and Failure nodes play a key role in modifying journey behavior. The Success node resets the number of invalid attempts to zero. The Failure node increments the number of invalid attempts and triggers Warn User After N Failures messages.
Success node
This node does the following:
-
Checks the Status property of the user profile, when reached. If the account is marked as
Inactive
, the node fails the authentication with an error message:The error message is returned in the JSON response if authenticating to the journey over REST:
{ "code":401, "reason":"Unauthorized", "message":"User Locked Out.", "detail": { "failureUrl":"" } }
-
If the User Status property is set to
Active
, the node resets the failure count in the user profile, when reached.
Failure node
This node does the following:
-
If you select Authentication > Settings > Account Lockout > Login Failure Lockout Mode for the realm (under Native Consoles > Access Management), the node checks the invalid attempts property of the user profile. It returns a warning message if the number of failed attempts is equal to or greater than the configured Warn User After N Failures value:
The error message is returned in the JSON response if authenticating to the journey over REST:
{ "code":401, "reason":"Unauthorized", "message":"Warning: You will be locked out after 1 more failure(s).", "detail": { "failureUrl":"" } }
-
Increments the failure count in the user profile, when reached.
-
Returns an error message if the account is marked as
Inactive
:The error message is returned in the JSON response if authenticating to the journey over REST:
{ "code":401, "reason":"Unauthorized", "message":"User Locked Out.", "detail": { "failureUrl":"" } }
Lockout-specific nodes
Authentication journeys also provide lockout-specific nodes for checking and changing the status of a user:
- Account Active Decision node
-
Use this node to determine whether an account is considered locked or unlocked.
-
The account is considered locked under these conditions:
-
The status is
inactive
. -
The status is
active
and a duration lockout is set on the account.
-
-
The account is considered unlocked under this condition:
-
The status is
active
and no duration lockout is set on the account.
-
-
- Account Lockout node
-
Use this node to change the account’s status to inactive or active.
When setting an account to inactive, the node does not consider the realm’s account lockout settings, so effectively sets a persistent lockout on the account.
When setting an account to active, the node also resets the failed attempts and lockout duration counters.
Additional reference for auth and SSO
This reference covers settings and the scripting API for authentication in PingOne Advanced Identity Cloud.
Core authentication attributes
Each realm has a set of properties that applies to all authentication performed to that realm. These properties are the core authentication attributes of the realm.
To edit a realm’s authentication configuration, go to Native Consoles > Access Management > Realms > Realm Name > Authentication > Settings.
Core
The following properties are available under the Core tab:
- Administrator Authentication Configuration
-
The default authentication journey used when an administrative user authenticates.
- Organization Authentication Configuration
-
The default authentication journey used when a non-administrative user authenticates.
amster
attribute:orgConfig
User Profile
The following properties are available under the User Profile tab:
User Profile
-
Whether a user profile needs to exist in the user data store, or should be created on successful authentication. The possible values are:
true
. Dynamic.-
After successful authentication, PingOne Advanced Identity Cloud creates a user profile if one does not already exist. PingOne Advanced Identity Cloud then issues the SSO token. PingOne Advanced Identity Cloud creates the user profile in the user data store configured for the realm.
createAlias
. Dynamic with User Alias.-
After successful authentication, PingOne Advanced Identity Cloud creates a user profile that contains the
User Alias List
attribute, which defines one or more aliases for mapping a user’s multiple profiles. ignore
. Ignored.-
After successful authentication, PingOne Advanced Identity Cloud issues an SSO token regardless of whether a user profile exists in the data store. The presence of a user profile is not checked.
Any functionality which needs to map values to profile attributes, such as SAML or OAuth 2.0, will not operate correctly if the User Profile property is set to
ignore
. false
. Required.-
After successful authentication, the user must have a user profile in the user data store configured for the realm in order for PingOne Advanced Identity Cloud to issue an SSO token.
- User Profile Dynamic Creation Default Roles
This property does not apply to Advanced Identity Cloud. |
- Alias Search Attribute Name
-
After a user is successfully authenticated, the user’s profile is retrieved. PingOne Advanced Identity Cloud first searches for the user based on the data store settings. If that fails to find the user, PingOne Advanced Identity Cloud uses the attributes listed here to look up the user profile. This setting accepts any data store specific attribute name.
amster
attribute:aliasAttributeName
Account Lockout
The following properties are available under the Account Lockout tab:
- Login Failure Lockout Mode
-
When enabled, PingOne Advanced Identity Cloud deactivates the LDAP attribute defined in the Lockout Attribute Name property in the user’s profile upon login failure. This attribute works in conjunction with the other account lockout and notification attributes.
amster
attribute:loginFailureLockoutMode
- Login Failure Lockout Count
-
The number of attempts a user has to authenticate within the time interval defined in Login Failure Lockout Interval before being locked out.
amster
attribute:loginFailureCount
- Login Failure Lockout Interval
-
The time in minutes during which failed login attempts are counted. If one failed login attempt is followed by a second failed attempt within this defined lockout interval time, the lockout count starts, and the user is locked out if the number of attempts reaches the number defined by the Login Failure Lockout Count property. If an attempt within the defined lockout interval time proves successful before the number of attempts reaches the number defined by the Login Failure Lockout Count property, the lockout count is reset.
amster
attribute:loginFailureDuration
- Email Address to Send Lockout Notification
-
One or more email addresses to which notification is sent if a user lockout occurs.
Separate multiple addresses with spaces, and append
|locale|charset
to addresses for recipients in non-English locales.amster
attribute:lockoutEmailAddress
- Warn User After N Failures
-
The number of authentication failures after which PingOne Advanced Identity Cloud displays a warning message that the user will be locked out.
- Login Failure Lockout Duration
-
Defines how many minutes a user must wait after a lockout before attempting to authenticate again. Entering a value greater than 0 enables memory lockout and disables physical lockout. Memory lockout means the user’s account is locked in memory for the number of minutes specified. The account is unlocked after the time period has passed.
amster
attribute:lockoutDuration
- Lockout Duration Multiplier
-
Defines a value with which to multiply the value of the Login Failure Lockout Duration attribute for each successive lockout. For example, if Login Failure Lockout Duration is set to 3 minutes, and the Lockout Duration Multiplier is set to 2, the user is locked out of the account for 6 minutes. After the 6 minutes has elapsed, if the user again provides the wrong credentials, the lockout duration is then 12 minutes. With the Lockout Duration Multiplier, the lockout duration is incrementally increased based on the number of times the user has been locked out.
amster
attribute:lockoutDurationMultiplier
- Lockout Attribute Name
-
The LDAP attribute used for physical lockout. The default attribute is
inetuserstatus
, although the field is empty in the UI. The Lockout Attribute Value field must also contain an appropriate value.amster
attribute:lockoutAttributeName
- Lockout Attribute Value
-
The action to take on the attribute defined in Lockout Attribute Name. The default value is
inactive
, although the field is empty in the UI. The Lockout Attribute Name field must also contain an appropriate value.amster
attribute:lockoutAttributeValue
- Invalid Attempts Data Attribute Name
-
The LDAP attribute used to hold the number of failed authentication attempts towards Login Failure Lockout Count. Although the field appears empty in the UI, PingOne Advanced Identity Cloud stores this data in the
sunAMAuthInvalidAttemptsDataAttrName
attribute defined in thesunAMAuthAccountLockout
objectclass by default.amster
attribute:invalidAttemptsDataAttributeName
- Store Invalid Attempts in Data Store
-
When enabled, PingOne Advanced Identity Cloud stores the information regarding failed authentication attempts as the value of the Invalid Attempts Data Attribute Name in the user data store. Information stored includes number of invalid attempts, time of last failed attempt, lockout time and lockout duration.
amster
attribute:storeInvalidAttemptsInDataStore
General
The following properties are available under the General tab:
- Default Authentication Locale
-
The default language subtype to be used by the Authentication Service. The default value is
en_US
.amster
attribute:locale
- Identity Types
This property does not apply to Advanced Identity Cloud. |
- Pluggable User Status Event Classes
This property does not apply to Advanced Identity Cloud. |
+
- Use Client-Side Sessions
-
When enabled, PingOne Advanced Identity Cloud assigns client-side sessions to users authenticating to this realm. Otherwise, PingOne Advanced Identity Cloud users authenticating to this realm are assigned server-side sessions.
amster
attribute:statelessSessionsEnabled
- External Login Page URL
-
The URL of the external login user interface, if the authentication user interface is hosted separately from PingOne Advanced Identity Cloud.
When set, PingOne Advanced Identity Cloud uses the provided URL as the base of the resume URI, rather than using the Base URL Source Service to obtain the base URL. PingOne Advanced Identity Cloud uses this URL when constructing the resume URI if authentication is suspended in an authentication journey.
amster
attribute:externalLoginPageUrl
- Default Authentication Level
This property does not apply to Advanced Identity Cloud. |
Trees
The following properties are available under the Trees tab:
- Authentication session state management scheme
-
The location where PingOne Advanced Identity Cloud stores authentication sessions.
Possible values are:
-
CTS
. PingOne Advanced Identity Cloud stores authentication sessions server-side, in the CTS token store. -
JWT
. PingOne Advanced Identity Cloud sends the authentication session to the client as a JWT. -
In-Memory
. PingOne Advanced Identity Cloud stores authentication sessions in its memory.
For more information on authentication session storage locations, and the requirements for each, see Introduction to sessions and cookies.
Default:
JWT
(new installations),In-Memory
(after upgrade)amster
attribute:authenticationSessionsStateManagement
-
- Max duration (minutes)
-
The maximum allowed duration of an authentication session, including any time spent in the suspended state, in minutes.
Values from
1
to2147483647
are allowed.Default:
5
amster
attribute:authenticationSessionsMaxDuration
- Suspended authentication duration (minutes)
-
The length of time an authentication session can be suspended, in minutes.
Suspending an authentication session allows time for out-of-band authentication methods, such as responding to emailed codes or performing an action on an additional device. The value must be less than or equal to the total time allowed for an authentication session, specified in the Max duration (minutes) property.
Values from
1
to2147483647
are allowed.Default:
5
- Enable Allowlisting
-
When enabled, PingOne Advanced Identity Cloud allowlists authentication sessions to protect them against replay attacks.
Default: Disabled
amster
attribute:authenticationSessionsWhitelist
Security
The following properties are available under the Security tab:
- Module Based Authentication
This property doesn’t apply to Advanced Identity Cloud. |
- Persistent Cookie Encryption Certificate Alias
-
The key pair alias in the PingOne Advanced Identity Cloud keystore to use for encrypting persistent cookies.
This property is deprecated. Use the rotatable secret mapping
am.authentication.nodes.persistentcookie.encryption
instead.If PingOne Advanced Identity Cloud finds a matching secret in the secret store for
am.authentication.nodes.persistentcookie.encryption
, this alias is ignored.Learn more about mapping and rotating secrets in Use ESVs for signing and encryption keys.
Default:
test
amster
attribute:keyAlias
ssoadm
attribute:iplanet-am-auth-key-alias
- Zero Page Login
This property does not apply to Advanced Identity Cloud. |
- Zero Page Login Referer Allowlist
This property does not apply to Advanced Identity Cloud. |
- Zero Page Login Allowed Without Referer?
This property does not apply to Advanced Identity Cloud. |
- Add clear-site-data Header on Logout
This property does not apply to Advanced Identity Cloud. |
- Organization Authentication Signing Secret
-
Specifies a cryptographically-secure random-generated HMAC shared secret for signing RESTful authentication requests. When users attempt to authenticate, PingOne Advanced Identity Cloud signs a JSON Web Token (JWT) containing this shared secret. The JWT contains the authentication session ID, realm, and authentication index type value, but does not contain the user’s credentials.
When modifying this value, ensure the new shared secret is Base-64 encoded and at least 128 bits in length.
amster
attribute:sharedSecret
Post Authentication Processing
The following properties are available under the Post Authentication Processing tab:
- Default Success Login URL
-
Accepts a list of values that specifies where users are directed after successful authentication. The format of this attribute is
client-type|URL
although the only value you can specify at this time is a URL which assumes the type HTML. The default value is/openam/console
. Values that do not specify HTTP have that appended to the deployment URI.amster
attribute:loginSuccessUrl
- Default Failure Login URL
-
Accepts a list of values that specifies where users are directed after authentication has failed. The format of this attribute is
client-type|URL
although the only value you can specify at this time is a URL which assumes the type HTML. Values that do not specify HTTP have that appended to the deployment URI.amster
attribute:loginFailureUrl
- Authentication Post Processing Classes
This property does not apply to Advanced Identity Cloud. |
- Generate UserID Mode
This property does not apply to Advanced Identity Cloud. |
- Pluggable User Name Generator Class
This property does not apply to Advanced Identity Cloud. |
- User Attribute Mapping to Session Attribute
This property does not apply to Advanced Identity Cloud. For authentication journeys, use the Scripted Decision node to retrieve user attributes and session properties, or the Set Session Properties node for session properties only. |
Supported callbacks
For an example using callbacks to authenticate, refer to Return callback information to PingOne Advanced Identity Cloud.
PingOne Advanced Identity Cloud supports the following callback types.
Callback type | Use |
---|---|
Request information. |
|
Return information to the client application, potentially for display to the user. |
|
Recover additional information from the user’s request. |
Interactive callbacks
Nodes return the following callbacks to request information.
BooleanAttributeInputCallback
Collects a boolean-style confirmation, such as yes/no or true/false.
The Attribute Collector node uses this instead of a ConfirmationCallback to apply IDM policies and validate the response.
Callback output field | Description |
---|---|
|
An array of JSON objects describing validation policies that the input failed. The object is empty until the input is provided and validation fails. |
|
A string containing the name of the attribute in the user profile. |
|
An array of JSON objects describing IDM validation policies the input must pass. An empty JSON object if the node does not require validation. |
|
A string containing the description of the information required from the user. |
|
A boolean indicating whether input is required for this attribute. |
|
When the node requires validation, this boolean indicates whether to apply validation policies only,
or to validate the input and continue to the next node.
When When |
|
A string containing a default value for the attribute, if required. |
{
"callbacks": [{
"type": "BooleanAttributeInputCallback",
"output": [{
"name": "name",
"value": "preferences/marketing"
}, {
"name": "prompt",
"value": "Send me special offers and services"
}, {
"name": "required",
"value": true
}, {
"name": "policies",
"value": {}
}, {
"name": "failedPolicies",
"value": []
}, {
"name": "validateOnly",
"value": false
}, {
"name": "value",
"value": false
}],
"input": [{
"name": "IDToken1",
"value": false
}, {
"name": "IDToken1validateOnly",
"value": false
}]
}]
}
In the input, return the value and a boolean to set validateOnly
.
Class to import in scripts: org.forgerock.openam.authentication.callbacks.BooleanAttributeInputCallback
Learn more in BooleanAttributeInputCallback.
ChoiceCallback
Provides a list of choices and collects the selected choice.
In the input, return 0
if the user selected the first choice, 1
for the second choice, and so forth.
{
"callbacks": [{
"type": "ChoiceCallback",
"output": [{
"name": "prompt",
"value": "Choose one"
}, {
"name": "choices",
"value": ["Choice A", "Choice B", "Choice C"]
}, {
"name": "defaultChoice",
"value": 2
}],
"input": [{
"name": "IDToken1",
"value": 0
}]
}]
}
Class to import in scripts: javax.security.auth.callback.ChoiceCallback
Learn more in ChoiceCallback.
ConfirmationCallback
Collects a boolean-style confirmation, such as yes/no or true/false with an optional "Cancel" choice.
Callback output field | Description |
---|---|
|
A number identifying the default option in the array of |
|
A number indicating the severity of the message:
|
|
A number indicating the type of confirmation:
|
|
An array of strings containing the option text for display to the user. |
|
A string containing the description of the choice to display to the user. |
{
"callbacks": [{
"type": "ConfirmationCallback",
"output": [{
"name": "prompt",
"value": ""
}, {
"name": "messageType",
"value": 0
}, {
"name": "options",
"value": ["Submit", "Start Over", "Cancel"]
}, {
"name": "optionType",
"value": -1
}, {
"name": "defaultOption",
"value": 1
}],
"input": [{
"name": "IDToken1",
"value": 0
}]
}]
}
In the input, return 0
if the user selected the first choice, 1
for the second choice, and so forth.
Class to import in scripts: javax.security.auth.callback.ConfirmationCallback
Learn more in ConfirmationCallback.
ConsentMappingCallback
Provides profile attributes that require user consent and collects consent from the user.
Callback output field | Description |
---|---|
|
A string containing the access level description for display to the user. |
|
A string containing the name for display to the user. |
|
An array containing names of the attributes to share. |
|
A string containing an icon specification for the privacy and consent notice. |
|
A boolean indicating whether consent is required. |
|
A string containing the privacy and consent notice for display to the user. |
|
A string containing the name of the mapping. |
{
"callbacks": [{
"type": "ConsentMappingCallback",
"output": [{
"name": "name",
"value": "managedUser_managedUser"
}, {
"name": "displayName",
"value": "Test Mapping"
}, {
"name": "icon",
"value": ""
}, {
"name": "accessLevel",
"value": "Actual Profile"
}, {
"name": "isRequired",
"value": true
}, {
"name": "message",
"value": "You consent to your data being shared with external services."
}, {
"name": "fields",
"value": []
}],
"input": [{
"name": "IDToken1",
"value": false
}]
}]
}
The user must give consent to all attributes or to none; in the input, return a single boolean value.
Class to import in scripts: org.forgerock.openam.authentication.callbacks.ConsentMappingCallback
Learn more in ConsentMappingCallback.
DeviceBindingCallback
Binds a client device to a user.
Callback output field | Description |
---|---|
|
The ID of the user to bind the device to. |
|
The username of the user to bind the device to. |
|
Specifies how the client secures access to the private key. Available options are:
|
|
A string containing the challenge the client should sign with the private key and return for validation. |
|
A string containing an optional title to display when requesting biometric authentication to secure access to the keypair. |
|
A string containing an optional subtitle to display when requesting biometric authentication to secure access to the keypair. |
|
A string containing optional descriptive text to display when requesting biometric authentication to secure access to the keypair. |
|
An integer specifying the number of seconds to wait for device binding to complete before reporting a timeout error. |
{
"authId": "...",
"callbacks": [
{
"type": "DeviceBindingCallback",
"output": [
{
"name": "userId",
"value": "id=demo,ou=user,dc=openam,dc=forgerock,dc=org"
},
{
"name": "username",
"value": "demo"
},
{
"name": "authenticationType",
"value": "BIOMETRIC_ALLOW_FALLBACK"
},
{
"name": "challenge",
"value": "6IBkTEPcMQ0xCghIclmDLost2ssGO5cPDs0AjUhmDTo="
},
{
"name": "title",
"value": "Authentication required"
},
{
"name": "subtitle",
"value": "Cryptography device binding"
},
{
"name": "description",
"value": "Please authenticate with biometrics to proceed"
},
{
"name": "timeout",
"value": 60
}
],
"input": [
{
"name": "IDToken1jws",
"value": ""
},
{
"name": "IDToken1deviceName",
"value": ""
},
{
"name": "IDToken1deviceId",
"value": ""
},
{
"name": "IDToken1clientError",
"value": ""
}
]
}
]
}
The client device should perform the following high-level steps to fulfil this callback:
-
Generate a keypair and secure access to it as defined by the
authenticationType
field. -
Generate a JSON web token (JWT) that has the ID of the user in the subject (
sub
) field and the original value of thechallenge
.For example:
{ "sub": "id=demo,ou=user,dc=openam,dc=forgerock,dc=org", "challenge": "6IBkTEPcMQ0xCghIclmDLost2ssGO5cPDs0AjUhmDTo=" }
-
Sign the JWT using the RS512 algorithm to create a JSON Web Signature (JWS).
-
Complete the callback, returning the JWS, the key ID (
KID
) of the keypair, the public key, and the name and the unique ID of the device.
The server verifies the returned information and persists it in the user’s profile if correct.
{
"authId": "...",
"callbacks": [
{
"type": "DeviceBindingCallback",
"output": [...],
"input": [
{
"name": "IDToken1jws",
"value": "eyJhbGciOiJIUzI1NiI....JV_adQssw5cB6aDS6m_kwIiw"
},
{
"name": "IDToken1deviceName",
"value": "Example Brand Version Android Device"
},
{
"name": "IDToken1deviceId",
"value": "ae9573dbbf442e7f-8e0c8b428409e0f1c"
},
{
"name": "IDToken1clientError",
"value": ""
}
]
}
]
}
Class to import in scripts: org.forgerock.openam.authentication.callbacks.DeviceBindingCallback
Learn more in DeviceBindingCallback.
DeviceProfileCallback
Collects information about the device used to authenticate.
Callback output field | Description |
---|---|
|
A boolean indicating whether to collect device metadata. |
|
A boolean indicating whether to collect the device location. |
|
A string containing optional text to display while collecting device information. |
{
"callbacks": [{
"type": "DeviceProfileCallback",
"output": [{
"name": "metadata",
"value": true
}, {
"name": "location",
"value": true
}, {
"name": "message",
"value": "Collecting....."
}],
"input": [{
"name": "IDToken1",
"value": ""
}]
}]
}
In the input, return escaped JSON resembling the following example response data.
{
"identifier": "aec3fe784...o3Xjiizyb9=",
"alias": "Pixel 3 XL",
"metadata": {
"platform": {
"platform": "Android",
"version": 28,
"device": "generic_x86_arm",
"deviceName": "AOSP on IA Emulator",
"model": "AOSP on IA Emulator",
"brand": "google",
"locale": "en_US",
"timeZone": "America/Vancouver",
"jailBreakScore": 1
},
"hardware": {
"hardware": "ranchu",
"manufacturer": "Google",
"storage": 774,
"memory": 1494,
"cpu": 4,
"display": {
"width": 1440,
"height": 2621,
"orientation": 1
},
"camera": {
"numberOfCameras": 2
}
},
"browser": {
"agent": "Dalvik/2.1.0 (Linux; U; Android 9; AOSP on IA Emulator Build/PSR1.180720.117)"
},
"bluetooth": {
"supported": false
},
"network": {
"connected": true
},
"telephony": {
"networkCountryIso": "us",
"carrierName": "Android"
}
},
"location": {
"latitude": 51.431534,
"Longitude": -2.622353
}
}
The location
and metadata
fields are required when their values are true
in the output.
The alias
and identifier
fields are optional and provided when the client uses the Ping Identity SDKs.
alias
-
A friendly name for the device often derived from the make and model.
identifier
-
A unique identifier string that can be used to later match the device.
location
-
Latitude and longitude of the device.
metadata
-
Refer to the example response data for details.
Class to import in scripts: org.forgerock.openam.authentication.callbacks.DeviceProfileCallback
Learn more in DeviceProfileCallback.
DeviceSigningVerifierCallback
Verifies the signature of data from a registered device.
Callback output field | Description |
---|---|
|
The ID of the user authenticating, if already determined by the authentication journey. |
|
A string containing the challenge the client should sign with the private key and return for validation. |
|
A string containing an optional title to display when requesting biometric authentication to access the keypair. |
|
A string containing an optional subtitle to display when requesting biometric authentication to access the keypair. |
|
A string containing optional descriptive text to display when requesting biometric authentication to access the keypair. |
|
An integer specifying the number of seconds to wait for device signing to complete before reporting a timeout error. |
{
"authId": "...",
"callbacks": [
{
"type": "DeviceSigningVerifierCallback",
"output": [
{
"name": "userId",
"value": ""
},
{
"name": "challenge",
"value": "Kc4dc14on98DYFzr5SoP2n3TC/JWAcAqTJMjCM+T27Y="
},
{
"name": "title",
"value": "Authentication required"
},
{
"name": "subtitle",
"value": "Cryptography device binding"
},
{
"name": "description",
"value": "Please complete with biometric to proceed"
},
{
"name": "timeout",
"value": 60
}
],
"input": [
{
"name": "IDToken1jws",
"value": ""
},
{
"name": "IDToken1clientError",
"value": ""
}
]
}
]
}
The client device should perform the following high-level steps to fulfill this callback:
-
Generate a JSON web token (JWT) that has the ID of the user in the subject (
sub
) field) and the original value of thechallenge
.For example:
{ "sub": "id=demo,ou=user,dc=openam,dc=forgerock,dc=org", "challenge": "6IBkTEPcMQ0xCghIclmDLost2ssGO5cPDs0AjUhmDTo=" }
-
Sign the JWT using the RS512 algorithm to create a JSON Web Signature (JWS).
-
Complete the callback, returning the JWS.
The server verifies the signature against the stored public key.
{
"authId": "...",
"callbacks": [
{
"type": "DeviceSigningVerifierCallback",
"output": [...],
"input": [
{
"name": "IDToken1jws",
"value": "eyJhbGciOiJIUzI1NiI....JV_adQssw5cB6aDS6m_kwIiw"
},
{
"name": "IDToken1clientError",
"value": ""
}
]
}
]
}
Class to import in scripts: org.forgerock.openam.authentication.callbacks.DeviceSigningVerifierCallback
Learn more in DeviceSigningVerifierCallback.
HiddenValueCallback
Provides form values that are to remain hidden from the user.
{
"callbacks": [{
"type": "HiddenValueCallback",
"output": [{
"name": "value",
"value": "6186c911-b3be-4dbc-8192-bdf251392072"
}, {
"name": "id",
"value": "jwt"
}],
"input": [{
"name": "IDToken1",
"value": "jwt"
}]
}]
}
Class to import in scripts: com.sun.identity.authentication.callbacks.HiddenValueCallback
Learn more in HiddenValueCallback.
IdPCallback
Collects the result of a native OAuth 2.0 or OIDC request to a social identity provider.
The Social Provider Handler node returns this callback when its Client Type is set to NATIVE
.
The output provides the information required to perform the request. Clients built using the Ping SDKs for Android or iOS use this to authenticate to the social identity provider with the mobile OS native APIs.
Callback output field | Description |
---|---|
|
An array containing the Authentication Context Class Reference values for the native authentication request. |
|
A string containing the identifier for the native authentication request. |
|
A string containing the nonce for the native authentication request. |
|
A string containing a name for the provider. |
|
A string containing the redirection URI for the native authentication request. |
|
A string containing the Request Object for the native authentication request. |
|
A string containing a URL that references a resource containing the Request Object for the native authentication request. |
|
An array containing the scopes for the native authentication request. |
{
"callbacks": [{
"type": "IdPCallback",
"output": [{
"name": "provider",
"value": "amazon"
}, {
"name": "clientId",
"value": "amzn1.application-oa2-client.f0c11aa1f8504f8da26a346ccc55a39e"
}, {
"name": "redirectUri",
"value": "https://localhost:8443/openam"
}, {
"name": "scopes",
"value": ["profile"]
}, {
"name": "nonce",
"value": ""
}, {
"name": "acrValues",
"value": []
}, {
"name": "request",
"value": ""
}, {
"name": "requestUri",
"value": ""
}],
"input": [{
"name": "IDToken1token",
"value": ""
}, {
"name": "IDToken1token_type",
"value": ""
}]
}]
}
In the input, return a JWT id_token
, access_token
or authorization code for the token,
and id_token
, access_token
or authorization_code
for the token type.
Class to import in scripts: org.forgerock.openam.authentication.callbacks.IdPCallback
Learn more in IdPCallback.
KbaCreateCallback
Collects knowledge-based authentication (KBA) answers to questions defined in the user profile, or user-defined question and answer pairs.
{
"callbacks": [{
"type": "KbaCreateCallback",
"output": [{
"name": "prompt",
"value": "Select a security question"
}, {
"name": "predefinedQuestions",
"value": ["What's your favorite color?"]
}],
"input": [{
"name": "IDToken1question",
"value": ""
}, {
"name": "IDToken1answer",
"value": ""
}]
}]
}
In the input, return an empty IDTokenNumberquestion
value
when IDTokenNumberanswer
corresponds to predefinedQuestions[Number]
.
For user-provided questions, return both.
Class to import in scripts: org.forgerock.openam.authentication.callbacks.KbaCreateCallback
Learn more in KbaCreateCallback.
NameCallback
Collects a string entered by the user, such as a username.
{
"callbacks": [{
"type": "NameCallback",
"output": [{
"name": "prompt",
"value": "User Name"
}],
"input": [{
"name": "IDToken1",
"value": ""
}]
}]
}
Class to import in scripts: javax.security.auth.callback.NameCallback
Learn more in NameCallback.
NumberAttributeInputCallback
Collects a numeric attribute, such as size or age.
The Attribute Collector node uses this to apply IDM policies and validate the response.
Callback output field | Description |
---|---|
|
An array of JSON objects describing validation policies that the input failed. The object is empty until the input is provided and validation fails. |
|
A string containing the name of the attribute in the user profile. |
|
An array of JSON objects describing IDM validation policies the input must pass. An empty JSON object if the node does not require validation. |
|
A string containing the description of the information required from the user. |
|
A boolean indicating whether input is required for this attribute. |
|
When the node requires validation, this boolean indicates whether to apply validation policies only,
or to validate the input and continue to the next node.
When When |
|
A string containing a default value for the attribute, if required. |
In the input, return the value and a boolean to set validateOnly
.
Class to import in scripts: org.forgerock.openam.authentication.callbacks.NumberAttributeInputCallback
Learn more in NumberAttributeInputCallback.
PasswordCallback
Collects a password value.
{
"callbacks": [{
"type": "PasswordCallback",
"output": [{
"name": "prompt",
"value": "Password"
}],
"input": [{
"name": "IDToken1",
"value": ""
}]
}]
}
Class to import in scripts: javax.security.auth.callback.PasswordCallback
Learn more in PasswordCallback.
PingOneProtectEvaluationCallback
Instructs the client to return the data captured by the PingOne Signals (Protect) SDK so that a risk evaluation can be completed.
Callback output field | Description |
---|---|
|
A boolean indicating whether to stop collecting behavioral data after returning the existing data. |
{
"callbacks":[
{
"type":"PingOneProtectEvaluationCallback",
"output":[
{
"name":"pauseBehavioralData",
"value":true
}
],
"input":[
{
"name":"IDToken1signals",
"value":""
},
{
"name":"IDToken1clientError",
"value":""
}
]
}
]
}
In the input:
-
In
IDToken1signals
, return the data captured by the PingOne Signals SDK. -
In
IDToken1clientError
, return an empty string to signal success, or an error string to indicate that the client was unable to process the request.
- Class to import
-
org.forgerock.openam.authentication.callbacks.PingOneProtectEvaluationCallback
Learn more in PingOneProtectEvaluationCallback.
PingOneProtectInitializeCallback
Instructs the client to initialize the PingOne Signals (Protect) SDK to gather information during a transaction.
Callback output field | Description |
---|---|
|
A string containing the PingOne environment ID. |
|
A boolean indicating whether to output SDK log messages to the developer console. |
|
An array of device attributes to ignore when collecting device signals. |
|
A string containing a custom host URL from which to retrieve a "Pong" token. Not currently used. |
|
A boolean indicating whether to calculate metadata on demand. When |
|
A boolean indicating whether to collect behavioral data. |
|
A boolean indicating whether the client stores device data in the browser’s localStorage only. When |
|
An integer indicating the number of days that device attestation can rely upon the device fallback key. |
|
A boolean indicating whether to tie the device payload to a non-extractable crypto key stored in the browser for content authenticity verification. |
|
A boolean indicating whether to collect tag data. |
{
"type":"PingOneProtectInitializeCallback",
"output":[
{
"name":"envId",
"value":"3072206d-c6ce-4c19-a366-f87e972c7cc3"
},
{
"name":"consoleLogEnabled",
"value":false
},
{
"name":"deviceAttributesToIgnore",
"value":[
"field1",
"field2"
]
},
{
"name":"customHost",
"value":""
},
{
"name":"lazyMetadata",
"value":false
},
{
"name":"behavioralDataCollection",
"value":true
},
{
"name":"deviceKeyRsyncIntervals",
"value":14
},
{
"name":"enableTrust",
"value":false
},
{
"name":"disableTags",
"value":false
},
{
"name":"disableHub",
"value":false
}
],
"input":[
{
"name":"IDToken1clientError",
"value":""
}
]
}
In the input IDToken1clientError
field, return an empty string to signal success, or define any error string to indicate initialization of the SDK failed.
- Class to import
-
org.forgerock.openam.authentication.callbacks.PingOneProtectInitializeCallback
Learn more in PingOneProtectInitializeCallback.
SelectIdPCallback
Collects a choice of an enabled social identity provider or local authentication.
The Select Identity Provider node returns this callback when multiple social identity providers are enabled, or when Local Authentication is enabled alongside at least one provider.
In the input, return the provider name, such as amazon
or localAuthentication
.
{
"callbacks": [{
"type": "SelectIdPCallback",
"output": [{
"name": "providers",
"value": [{
"provider": "amazon",
"uiConfig": {
"buttonCustomStyle": "background: linear-gradient(to bottom, #f7e09f 15%,#f5c646 85%);color: black;border-color: #b48c24;",
"buttonImage": "",
"buttonClass": "fa-amazon",
"buttonDisplayName": "Amazon",
"buttonCustomStyleHover": "background: linear-gradient(to bottom, #f6c94e 15%,#f6c94e 85%);color: black;border-color: #b48c24;",
"iconClass": "fa-amazon",
"iconFontColor": "black",
"iconBackground": "#f0c14b"
}
}, {
"provider": "google",
"uiConfig": {
"buttonImage": "images/g-logo.png",
"buttonCustomStyle": "background-color: #fff; color: #757575; border-color: #ddd;",
"buttonClass": "",
"buttonCustomStyleHover": "color: #6d6d6d; background-color: #eee; border-color: #ccc;",
"buttonDisplayName": "Google",
"iconFontColor": "white",
"iconClass": "fa-google",
"iconBackground": "#4184f3"
}
}, {
"provider": "localAuthentication"
}]
}, {
"name": "value",
"value": ""
}],
"input": [{
"name": "IDToken1",
"value": ""
}]
}]
}
Class to import in scripts: org.forgerock.openam.authentication.callbacks.SelectIdPCallback
Learn more in SelectIdPCallback.
StringAttributeInputCallback
Collects string attributes, such as city names, telephone numbers, and postcodes.
The Attribute Collector node uses this instead of a TextInputCallback to apply IDM policies and validate the response.
Callback output field | Description |
---|---|
|
An array of JSON objects describing validation policies that the input failed. The object is empty until the input is provided and validation fails. |
|
A string containing the name of the attribute in the user profile. |
|
An array of JSON objects describing IDM validation policies the input must pass. An empty JSON object if the node does not require validation. |
|
A string containing the description of the information required from the user. |
|
A boolean indicating whether input is required for this attribute. |
|
When the node requires validation, this boolean indicates whether to apply validation policies only,
or to validate the input and continue to the next node.
When When |
|
A string containing a default value for the attribute, if required. |
{
"callbacks": [{
"type": "StringAttributeInputCallback",
"output": [{
"name": "name",
"value": "givenName"
}, {
"name": "prompt",
"value": "First Name"
}, {
"name": "required",
"value": true
}, {
"name": "policies",
"value": {
"policyRequirements": ["REQUIRED", "VALID_TYPE"],
"fallbackPolicies": null,
"name": "givenName",
"policies": [{
"policyRequirements": ["REQUIRED"],
"policyId": "required"
}, {
"policyRequirements": ["VALID_TYPE"],
"policyId": "valid-type",
"params": {
"types": ["string"]
}
}],
"conditionalPolicies": null
}
}, {
"name": "failedPolicies",
"value": []
}, {
"name": "validateOnly",
"value": false
}, {
"name": "value",
"value": ""
}],
"input": [{
"name": "IDToken1",
"value": ""
}, {
"name": "IDToken1validateOnly",
"value": false
}]
}]
}
When input validation is not required, the policies
contain an empty object:
{
"name": "policies",
"value": {}
}
In the input, return the value and a boolean to set validateOnly
.
Class to import in scripts: org.forgerock.openam.authentication.callbacks.StringAttributeInputCallback
Learn more in StringAttributeInputCallback.
TermsAndConditionsCallback
Displays the current terms and conditions and collects the user’s agreement to them.
{
"callbacks": [
{
"type": "TermsAndConditionsCallback",
"output": [
{
"name": "version",
"value": "0.0"
},
{
"name": "terms",
"value": "Terms and conditions text that you must agree to."
},
{
"name": "createDate",
"value": "2022-10-28T04:20:11.320Z"
}
],
"input": [
{
"name": "IDToken1",
"value": false
}
]
}
]
}
In the input, return true
if the user agrees to the terms and conditions.
Class to import in scripts: org.forgerock.openam.authentication.callbacks.TermsAndConditionsCallback
Learn more in TermsAndConditionsCallback.
TextInputCallback
Collects text input from the user.
{
"callbacks": [{
"type": "TextInputCallback",
"output": [{
"name": "prompt",
"value": "Provide a nickname for this account"
}],
"input": [{
"name": "IDToken1",
"value": ""
}]
}]
}
Class to import in scripts: javax.security.auth.callback.TextInputCallback
Learn more in TextInputCallback.
ValidatedCreatePasswordCallback
Collects a password value.
The Platform Password node uses this instead of a PasswordCallback to apply IDM policies and validate the response.
Callback output field | Description |
---|---|
|
An array of JSON objects describing validation policies that the input failed. The object is empty until the input is provided and validation fails. |
|
A string containing the name of the attribute in the user profile. |
|
An array of objects describing IDM validation policies the input must pass. An empty JSON object if the node does not require validation. |
|
A string containing the description of the information required from the user. |
|
When the node requires validation, this boolean indicates whether to apply validation policies only,
or to validate the input and continue to the next node.
When When |
{
"callbacks": [{
"type": "ValidatedCreatePasswordCallback",
"output": [{
"name": "echoOn",
"value": false
}, {
"name": "policies",
"value": {
"policyRequirements": ["VALID_TYPE", "MIN_LENGTH", "AT_LEAST_X_CAPITAL_LETTERS", "AT_LEAST_X_NUMBERS", "CANNOT_CONTAIN_OTHERS"],
"fallbackPolicies": null,
"name": "password",
"policies": [{
"policyRequirements": ["VALID_TYPE"],
"policyId": "valid-type",
"params": {
"types": ["string"]
}
}, {
"policyId": "minimum-length",
"params": {
"minLength": 8
},
"policyRequirements": ["MIN_LENGTH"]
}, {
"policyId": "at-least-X-capitals",
"params": {
"numCaps": 1
},
"policyRequirements": ["AT_LEAST_X_CAPITAL_LETTERS"]
}, {
"policyId": "at-least-X-numbers",
"params": {
"numNums": 1
},
"policyRequirements": ["AT_LEAST_X_NUMBERS"]
}, {
"policyId": "cannot-contain-others",
"params": {
"disallowedFields": ["userName", "givenName", "sn"]
},
"policyRequirements": ["CANNOT_CONTAIN_OTHERS"]
}],
"conditionalPolicies": null
}
}, {
"name": "failedPolicies",
"value": []
}, {
"name": "validateOnly",
"value": false
}, {
"name": "prompt",
"value": "Password"
}],
"input": [{
"name": "IDToken1",
"value": ""
}, {
"name": "IDToken1validateOnly",
"value": false
}]
}]
}
In the input, return the value and a boolean to set validateOnly
.
Class to import in scripts: org.forgerock.openam.authentication.callbacks.ValidatedPasswordCallback
Learn more in ValidatedPasswordCallback.
ValidatedCreateUsernameCallback
Collects a username.
The Platform Username node uses this instead of a NameCallback to apply IDM policies and validate the response.
Callback output field | Description |
---|---|
|
An array of JSON objects describing validation policies that the input failed. The object is empty until the input is provided and validation fails. |
|
A string containing the name of the attribute in the user profile. |
|
An array of objects describing IDM validation policies the input must pass. An empty JSON object if the node does not require validation. |
|
A string containing the description of the information required from the user. |
|
When the node requires validation, this boolean indicates whether to apply validation policies only,
or to validate the input and continue to the next node.
When When |
{
"callbacks": [{
"type": "ValidatedCreateUsernameCallback",
"output": [{
"name": "policies",
"value": {
"policyRequirements": ["REQUIRED", "VALID_TYPE", "VALID_USERNAME", "CANNOT_CONTAIN_CHARACTERS", "MIN_LENGTH", "MAX_LENGTH"],
"fallbackPolicies": null,
"name": "userName",
"policies": [{
"policyRequirements": ["REQUIRED"],
"policyId": "required"
}, {
"policyRequirements": ["VALID_TYPE"],
"policyId": "valid-type",
"params": {
"types": ["string"]
}
}, {
"policyId": "valid-username",
"policyRequirements": ["VALID_USERNAME"]
}, {
"policyId": "cannot-contain-characters",
"params": {
"forbiddenChars": ["/"]
},
"policyRequirements": ["CANNOT_CONTAIN_CHARACTERS"]
}, {
"policyId": "minimum-length",
"params": {
"minLength": 1
},
"policyRequirements": ["MIN_LENGTH"]
}, {
"policyId": "maximum-length",
"params": {
"maxLength": 255
},
"policyRequirements": ["MAX_LENGTH"]
}],
"conditionalPolicies": null
}
}, {
"name": "failedPolicies",
"value": []
}, {
"name": "validateOnly",
"value": false
}, {
"name": "prompt",
"value": "Username"
}],
"input": [{
"name": "IDToken1",
"value": ""
}, {
"name": "IDToken1validateOnly",
"value": false
}]
}]
}
In the input, return the value and a boolean to set validateOnly
.
Class to import in scripts: org.forgerock.openam.authentication.callbacks.ValidatedUsernameCallback
Learn more in ValidatedUsernameCallback.
Read-only callbacks
Nodes use these callbacks to return information to the client application or to display information to the user.
MetadataCallback
Injects key-value pairs into the authentication process.
{
"callbacks": [{
"type": "MetadataCallback",
"output": [{
"name": "data",
"value": {
"myParameter": "MyValue"
}
}]
}]
}
Class to import in scripts: com.sun.identity.authentication.spi.MetadataCallback
Learn more in MetadataCallback.
PollingWaitCallback
Indicates the number of milliseconds to wait before responding to the callback.
{
"callbacks": [{
"type": "PollingWaitCallback",
"output": [{
"name": "waitTime",
"value": "8000"
}, {
"name": "message",
"value": "Waiting for response..."
}]
}]
}
Class to import in scripts: org.forgerock.openam.authentication.callbacks.PollingWaitCallback
Learn more in PollingWaitCallback.
RedirectCallback
Redirects the user-agent.
The Social Provider Handler node returns this callback when its Client Type is set to BROWSER
,
and the client must redirect the user to the social provider for authentication.
{
"callbacks": [{
"type": "RedirectCallback",
"output": [{
"name": "redirectUrl",
"value": "https://accounts.google.com/o/oauth2/v2/auth?nonce..."
}, {
"name": "redirectMethod",
"value": "GET"
}, {
"name": "trackingCookie",
"value": true
}]
}]
}
PingOne Advanced Identity Cloud uses a trackingCookie
to store the authentication identifier
that reflects the client’s place in the authentication process.
Class to import in scripts: com.sun.identity.authentication.spi.RedirectCallback
Learn more in RedirectCallback.
SuspendedTextOutputCallback
Provides a message to display to the user when the authentication journey is suspended.
Callback output field | Description |
---|---|
|
A string containing a message to display to the user. |
|
A number indicating the severity of the message:
|
{
"callbacks": [{
"type": "SuspendedTextOutputCallback",
"output": [{
"name": "message",
"value": "An email has been sent to your inbox."
}, {
"name": "messageType",
"value": "0"
}]
}]
}
Class to import in scripts: org.forgerock.openam.auth.node.api.SuspendedTextOutputCallback
Learn more in SuspendedTextOutputCallback.
TextOutputCallback
Provides a message to display to the user.
Callback output field | Description |
---|---|
|
A string containing a message to display to the user. |
|
A number indicating the severity of the message:
|
{
"callbacks": [{
"type": "TextOutputCallback",
"output": [{
"name": "message",
"value": "Default message"
}, {
"name": "messageType",
"value": "0"
}]
}]
}
Class to import in scripts: javax.security.auth.callback.TextOutputCallback
Learn more in TextOutputCallback.
Backchannel callbacks
Nodes use these callbacks to recover additional information from the request, such as a header or a certificate.
HttpCallback
Accesses user credentials sent in the Authorization
header:
Authorization: Basic bXlDbGllbnQ6Zm9yZ2Vyb2Nr
Class to import in scripts: com.sun.identity.authentication.spi.HttpCallback
Learn more in HttpCallback.
LanguageCallback
Retrieves the locale from the request header for localizing text presented to the user.
Class to import in scripts: javax.security.auth.callback.LanguageCallback
Learn more in LanguageCallback.
ScriptTextOutputCallback
Inserts a script into the page presented to the user; for example, to collect data about the user’s environment.
Class to import in scripts: com.sun.identity.authentication.callbacks.ScriptTextOutputCallback
Learn more in ScriptTextOutputCallback.
X509CertificateCallback
Retrieves an X.509 certificate, for example, from a header.
Class to import in scripts: com.sun.identity.authentication.spi.X509CertificateCallback
Learn more in X509CertificateCallback.
Authenticate endpoint parameters
To authenticate to Advanced Identity Cloud using REST, send an HTTP POST request to the json/authenticate
endpoint.
Specify the realm hierarchy, starting at the root; for example, /realms/root/realms/alpha
.
The following list describes the json/authenticate
endpoint parameters:
authIndexType
The authIndexType
specifies the type of authentication the user will perform.
Always use this parameter in conjunction with the authIndexValue
to provide additional information about how the user
is authenticating.
If not specified, PingOne Advanced Identity Cloud authenticates the user against the default journey configured for the realm.
The authIndexType
can be one of the following:
composite_advice
-
When the
authIndexType
iscomposite_advice
, theauthIndexValue
must be a URL-encoded composite advice string.Use the
composite_advice
type to indicate which authentication services to use when logging in a user.This example indicates that the user should authenticate through the
myExampleJourney
:$ curl --get \ --request POST \ --header "Content-Type: application/json" \ --header 'Accept-API-Version: resource=2.0, protocol=1.0' \ --data-urlencode 'authIndexType=composite_advice' \ --data-urlencode 'authIndexValue=<Advices> <AttributeValuePair> <Attribute name="AuthenticateToServiceConditionAdvice"/> <Value>myExampleJourney</Value> </AttributeValuePair> </Advices>' \ 'https://<tenant-env-fqdn>/am/json/realms/root/realms/alpha/authenticate'
This curl
command URL-encodes the XML values. The--get
option appends them as query string parameters to the URL.Possible options for
Advices
are:-
AuthenticateToServiceConditionAdvice
. Requires the name of an authentication journey. For example:<Advices> <AttributeValuePair> <Attribute name="AuthenticateToServiceConditionAdvice"/> <Value>myExampleJourney</Value> </AttributeValuePair> </Advices>
-
AuthenticateToTreeConditionAdvice
. Also requires the name of an authentication journey. For example:<Advices> <AttributeValuePair> <Attribute name="AuthenticateToTreeConditionAdvice"/> <Value>PersistentCookieJourney</Value> </AttributeValuePair> </Advices>
-
AuthenticateToRealmConditionAdvice
. Requires the name of a realm. For example:<Advices> <AttributeValuePair> <Attribute name="AuthenticateToRealmConditionAdvice"/> <Value>alpha</Value> </AttributeValuePair> </Advices>
-
TransactionConditionAdvice
. Requires the unique ID of a transaction token. For example:<Advices> <AttributeValuePair> <Attribute name="TransactionConditionAdvice"/> <Value>9dae2c80-fe7a-4a36-b57b-4fb1271b0687</Value> </AttributeValuePair> </Advices>
For more information, refer to Authorize one-time access with transactional authz.
You can specify multiple advice conditions. For example:
<Advices> <AttributeValuePair> <Attribute name="AuthenticateToServiceConditionAdvice"/> <Value>ldapService</Value> </AttributeValuePair> <AttributeValuePair> <Attribute name="AuthenticateToServiceConditionAdvice"/> <Value>Example</Value> </AttributeValuePair> <AttributeValuePair> <Attribute name="TransactionConditionAdvice"/> <Value>9dae2c80-fe7a-4a36-b57b-4fb1271b0687</Value> </AttributeValuePair> </Advices>
-
resource
-
When the
authIndexType
isresource
, theauthIndexValue
must be a URL protected by an PingOne Advanced Identity Cloud policy.For example, to log into PingOne Advanced Identity Cloud using a policy matching the
https://www.example.com
resource, you could use the following:$ curl \ --request POST \ --header 'Accept-API-Version: resource=2.0, protocol=1.0' \ 'https://<tenant-env-fqdn>/am/json/realms/root/realms/alpha/authenticate?authIndexType=resource&authIndexValue=https%3A%2F%2Fwww.example.com'
Note that the resource must be URL-encoded. Authentication will fail if no policy matches the resource.
service
-
When the
authIndexType
isservice
, theauthIndexValue
is the journey PingOne Advanced Identity Cloud must use to authenticate the user.For example, to authenticate using the built-in
login
authentication journey, you could use the following:$ curl \ --request POST \ --header 'Accept-API-Version: resource=2.0, protocol=1.0' \ 'https://<tenant-env-fqdn>/am/json/realms/root/realms/alpha/authenticate?authIndexType=service&authIndexValue=Login'
If
authIndexType=service
and noauthIndexValue
is specified, the default service is used. This is similar to noauthIndexType
being set.If there are several authentication services that satisfy the authentication requirements, PingOne Advanced Identity Cloud presents them as a choice callback to the user. Return the required callbacks to PingOne Advanced Identity Cloud to authenticate.
Required: No.
authIndexValue
This parameter sets a value for the specific authIndexType
.
Required: Yes, when using the authIndexType
parameter.
noSession
When set to true
, this parameter specifies that PingOne Advanced Identity Cloud should not return a session when authenticating a user.
For example:
$ curl \
--request POST \
--header "Content-Type: application/json" \
--header "Accept-API-Version: resource=2.0, protocol=1.0" \
--header "X-OpenAM-Username: bjensen" \
--header "X-OpenAM-Password: Secret12!" \
'https://<tenant-env-fqdn>/am/json/realms/root/realms/alpha/authenticate?noSession=true'
{
"successUrl": "/enduser/?realm=/alpha",
"realm": "/alpha"
}
Required: No.
Client configuration reference
- Enabled
-
Whether the provider is enabled.
Required: Yes.
- Auth ID Key
-
The attribute the social identity provider uses to identify an authenticated individual. For example,
id
,sub
, anduser_id
.Required: Yes.
- Client ID
-
The
client_id
parameter as described in section 2.2 of The OAuth 2.0 Authorization Framework specification.Required: Yes.
- Client Secret
-
The
client_secret
parameter as described in section 2.3 of The OAuth 2.0 Authorization Framework specification.This property is deprecated. Use the Client Secret Label Identifier instead.
If you set a Client Secret Label Identifier and PingOne Advanced Identity Cloud finds a matching secret in a secret store, the Client Secret is ignored.
Required: No.
- Client Secret Label Identifier
-
An identifier used to create a secret label for mapping to a secret in a secret store.
PingOne Advanced Identity Cloud uses this identifier to create a specific secret label for this service instance, using the template
am.social.providers.identifier.secret
where identifier is the value of Client Secret Label Identifier.The identifier can only contain alphanumeric characters
a-z
,A-Z
,0-9
, and periods (.
). It can’t start or end with a period.If you set a Client Secret Label Identifier and PingOne Advanced Identity Cloud finds a matching secret in a secret store, the Client Secret is ignored.
Required: No.
- Authentication Endpoint URL
-
The URL to the social provider’s endpoint handling authentication as described in section 3.1 of The OAuth 2.0 Authorization Framework. For example,
https://accounts.google.com/oauth2/v2/auth
.Required: Yes.
- Access Token Endpoint URL
-
The URL to the endpoint handling access tokens as described in section 3.2 of The OAuth 2.0 Authorization Framework specification. For example,
https://www.googleapis.com/oauth2/v4/token
.Required: Yes.
- User Profile Service URL
-
The user profile URL that returns profile information. For example,
https://www.googleapis.com/oauth2/v3/userinfo
.This URL should return JSON objects in its response.
Required: No.
- Token Introspection Endpoint URL
-
The URL to the endpoint handling access token validation, as described in the OAuth 2.0 Token Introspection specification. For example,
https://oauth2.googleapis.com/tokeninfo
.Required: No.
- Redirect URL
-
The URL to which the identity provider will redirect the user after authenticating, as described in Section 3.1.2 of The OAuth 2.0 Authorization Framework specification.
This URL is usually a page or path in PingOne Advanced Identity Cloud; for example,
https://<tenant-env-fqdn>/am?_realm=alpha
. The URL is also registered in the identity provider’s service.If you’re using an app built with the ForgeRock SDKs for Android or iOS, you can also use a custom URI scheme as the redirect For example,
com.example.sdkapp:redirect_uri_path
orfrauth://com.forgerock.ios.sdkapp
.-
When using the
FORM_POST
response mode, you must specify theform_post
endpoint in the redirection URL. Refer to Response Mode for more information. -
If you encounter domain validation prompts when using
forgeblocks.com
andid.forgerock.io
domains as redirect URLs in your Google OAuth 2.0 applications, you must use a custom domain, and then set up domain verification with Google. -
If you encounter
No provider found
errors when usingforgeblocks.com
andid.forgerock.io
domains as redirect URLs in your OAuth 2.0 applications, either modify the redirect URL to include a realm identifier, or use a custom domain:-
Incorrect:
https://<tenant-env-fqdn>/am/oauth2/client/form_post/...
-
Correct:
https://<tenant-env-fqdn>/am/oauth2/<realm>/client/form_post/...
or
https://<custom-domain>/am/oauth2/client/form_post/...
A custom domain acts as a realm DNS alias, so when it’s used as a redirect URL, you don’t have to specify the realm because Advanced Identity Cloud implicitly knows which realm to use.
-
Required: Yes.
-
- Redirect after form post URL
-
The URL of a custom login page or application. Advanced Identity Cloud will send processed form post data related to social login authentication to that URL as the value of the
form_post_entry
query parameter.To continue the authentication journey, the custom login page is responsible for making a call to the Advanced Identity Cloud
/json/authenticate
endpoint with the authentication ID (authID
) and the processed form data (form_post_entry
).Configure this property when the following is true:
-
The
FORM_POST
response mode is configured. -
Your users log in to Advanced Identity Cloud using custom login pages, such as apps using the Ping Identity SDKs, instead of the Advanced Identity Cloud admin UI.
Required: No.
-
- Scope Delimiter
-
The delimiter used to separate scope values. For example, a blank space (), or a comma character (,).
Most providers use a blank space.
Required: Yes.
- OAuth Scopes
-
The list of scopes to request from the provider.
The scopes that the provider returns depends on the permissions that the resource owner, such as the end user, grants to the client application.
For example, Google exposes its supported scopes in their OAuth 2.0 Scopes for Google APIs documentation.
Required: Yes.
- Client Authentication Method
-
How the client should authenticate to the provider. Possible values are:
CLIENT_SECRET_POST
-
The client sends the client ID and the secret in the
client_ID
and theclient_secret
parameters in the body of the request. CLIENT_SECRET_BASIC
-
The client sends the client ID and the secret in a basic authorization header with the base64-encoded value of client-id:client-secret.
PRIVATE_KEY_JWT
-
The client sends its credentials to the provider in a signed JWT as specified in the JSON Web Token (JWT) Profile for OAuth 2.0 Client Authentication and Authorization Grants.
ENCRYPTED_PRIVATE_KEY_JWT
-
The client sends its credentials to the provider in a signed, then encrypted JWT as specified in the JSON Web Token (JWT) Profile for OAuth 2.0 Client Authentication and Authorization Grants.
Some authentication methods require additional configuration:
How do I configure JWT authentication with signed JWTs?
-
Obtain a list of supported signing algorithms from the provider’s
.well-known
endpoint, and decide which one you will use. -
In the JWT Signing Algorithm field, enter the signing algorithm that PingOne Advanced Identity Cloud will use to sign the JWT. For example,
RSA256
.This field may already be configured if the client is sending request objects.
-
Provide a JWK with the public key to the identity provider. Refer to their documentation for more information.
For example, you could copy the contents of the public JWK in a field in the provider’s service configuration, or you could configure the realm’s
/oauth2/connect/rp/jwk_uri
endpoint, which exposes the client’s public keys.Configure the realm’s
/oauth2/connect/rp/jwk_uri
endpoint in the provider, which exposes the client’s public keys. Refer to the provider’s documentation for more information. -
Change the value in the Private Key JWT Expiration Time (seconds) field, if needed. It has a sensible value preconfigured, but you may need to tune it for your provider.
How do I configure JWT authentication with signed and encrypted JWTs?
-
Follow the steps in How do I configure JWT authentication with signed JWTs? to configure PingOne Advanced Identity Cloud to sign authentication JWTs.
Now you are ready to configure PingOne Advanced Identity Cloud to encrypted authentication JWTs.
-
Obtain a list of supported encryption algorithms and methods from the provider’s
.well-known
endpoint, and decide which one you will use. -
In the JWT Encryption Algorithm field, select the encryption algorithm.
If the required encryption algorithm does not appear in the drop-down, check the reference entry for the JWT Encryption Algorithm field for information on how to add it.
This field may already be configured if the client is encrypting request objects.
-
In the JWT Encryption Method field, select the encryption method.
This field may already be configured if the client is encrypting request objects.
-
In the JWKS URI Endpoint field, configure the URI containing the provider’s public JWK set.
Obtain the URI from the provider’s
.well-known
endpoint, or their documentation.PingOne Advanced Identity Cloud will use the JWK URI to fetch the provider’s public encryption key.
-
Perform one of the following steps depending on the encryption method you configured:
-
If you chose Direct AES Encryption method, select
NONE
in the JWT Signing Algorithm field. Signing is redundant with this encryption method. -
If you chose an encryption method different from the Direct AES Encryption method, configure signing. For more information, refer to How do I configure JWT authentication with signed JWTs?.
-
Required: Yes.
- PKCE Method
-
Specifies the PKCE transformation method PingOne Advanced Identity Cloud uses when making requests to the provider’s authorization endpoint, as specified in Section 4.2 of the Proof Key for Code Exchange by OAuth Public Clients specification.
Select
NONE
to disable PKCE transformations.Required: No.
- Request Parameter JWT Option
-
(OIDC providers only) Specifies whether PingOne Advanced Identity Cloud should provide a request object JWT to the provider. Possible values are:
NONE
-
PingOne Advanced Identity Cloud does not send a request object to the provider.
REFERENCE
-
The request object JWT is stored in PingOne Advanced Identity Cloud’s CTS token store, and PingOne Advanced Identity Cloud exposes a unique identifier for it using the
oauth2/request_uri
endpoint for the realm. The URL to the endpoint and the JWT’s unique identifier are passed to the provider in therequest_uri
parameter of the request.Ensure that the provider can reach the endpoint.
An example of the URL is
https://platform.example.com:8443/am/realms/root/realms/myRealm/oauth2/request_uri/requestobjectID
When integrating with itsme®, ensure that the base URL of PingOne Advanced Identity Cloud contains the
443
port. For example,https://platform.example.com:443/am
.To do this, configure the Base URL Source service:
-
Under Native Consoles > Access Management, go to Realms > Realm Name > Services.
-
Add a
Base URL Source
service (if one isn’t already configured) or select it to change its properties:
-
VALUE
-
PingOne Advanced Identity Cloud appends the JWT as the value of the
request
parameter of the request.How do I configure the client to send signed request objects?
-
In the Request Parameter JWT Option field, select either
VALUE
orREFERENCE
.Refer to your identity provider’s documentation for more information.
-
Obtain a list of supported signing algorithms from the provider’s
.well-known
endpoint, and decide which one you will use. -
In the JWT Signing Algorithm field, select the signing algorithm that PingOne Advanced Identity Cloud will use to sign the request object. For example,
RS256
.This field may already be configured if the client is using JWT client authentication.
-
Provide a JWK with the public key to the identity provider. Refer to their documentation for more information.
For example, you could copy the contents of the public JWK in a field in the provider’s service configuration, or you could configure the realm’s
/oauth2/connect/rp/jwk_uri
endpoint, which exposes the client’s public keys.Configure the realm’s
/oauth2/connect/rp/jwk_uri
endpoint in the provider, which exposes the client’s public keys. Refer to the provider’s documentation for more information.
How do I configure the client to send signed and encrypted request objects?
-
Follow the steps in How do I configure the client to send signed request objects? to configure PingOne Advanced Identity Cloud to send signed request objects.
Now you are ready to configure PingOne Advanced Identity Cloud to send encrypted request objects.
-
Enable Encrypt Request Parameter JWT.
-
Obtain a list of supported encryption algorithms and methods from the provider’s
.well-known
endpoint, and decide which one you will use. -
In the JWT Encryption Algorithm field, select the encryption algorithm.
If the required encryption algorithm does not appear in the drop-down, check the reference entry for the JWT Encryption Algorithm field for information on how to add it.
This field may already be configured if the client is encrypting authentication JTWs.
-
In the JWT Encryption Method field, select the encryption method.
This field may already be configured if the client is encrypting authentication JWTs.
-
In the JWKS URI Endpoint field, configure the URI containing the provider’s public JWK set.
Obtain the URI from the provider’s
.well-known
endpoint.PingOne Advanced Identity Cloud will use the JWK URI to fetch the provider’s public encryption key.
-
Perform one of the following steps depending on the encryption method you configured:
-
If you chose Direct AES Encryption method, select
NONE
in the JWT Signing Algorithm field. Signing is redundant with this encryption method. -
If you chose an encryption method different from the Direct AES Encryption method, configure signing. For more information, refer to How do I configure the client to send signed request objects?.
-
-
- Encrypt Request Parameter JWT
-
Specifies whether the request parameter must be encrypted when Request Parameter JWT Option is set to
REFERENCE
orVALUE
. - ACR Values
-
(OIDC providers only) A space-separated list, in order of preference, of the client’s
acr
values.Required: No.
- Well Known Endpoint
-
(OIDC providers only) The URL for retrieving information about the provider, such as endpoints, and public keys. For example,
https://accounts.google.com/.well-known/openid-configuration
.Leave this field empty for the LINE (Browser)
configuration.Required: No.
- Request Object Audience
-
(OIDC providers only) The intended audience (
aud
) of the request object when the Request Parameter JWT Option field is set toVALUE
orREFERENCE
.When not configured, the value of the Issuer field will be used as the audience of the request object.
- OP Encrypts ID Tokens
-
(OIDC providers only) Whether the provider encrypts ID Tokens.
How do I configure PingOne Advanced Identity Cloud to receive encrypted tokens?
-
Provide a JWK with the public key to the identity provider. Refer to the identity provider’s documentation for more information.
For example, you could copy the contents of the public JWK in a field in the provider’s service configuration, or you could configure the realm’s
/oauth2/connect/rp/jwk_uri
endpoint, which exposes the client’s public keys.Configure the realm’s
/oauth2/connect/rp/jwk_uri
endpoint in the provider, which exposes the client’s public keys. Refer to the provider’s documentation for more information.
Required: No.
-
- Issuer
-
(OIDC providers only) The issuer of ID Tokens.
Either specify a regular expression or a string value that must exactly match the value returned in the ID token, depending on the configuration of the Issuer comparison check setting.
Obtain the
issuer
value from the provider’s.well-known
endpoint.Required: Yes.
- Enable Native Nonce
-
(OIDC providers only) When enabled, the provider native SDK must include a
nonce
claim in the ID token. The value of the claim must be the value of thenonce
claim sent in the Authentication Request.Required: No.
- User Info Response Format
-
(OIDC providers only) The format in which the provider’s
userinfo
endpoint returns data.Some options require additional configuration:
How do I configure the client to receive signed userinfo JWTs?
-
In the JWKS URI Endpoint field, configure the URL containing the provider’s public JWK set. Obtain it from the provider’s
.well-known
endpoint, or their documentation.PingOne Advanced Identity Cloud will use this URL to fetch the provider’s public signing key.
How do I configure the client to receive signed, then encrypted userinfo JWTs?
-
Follow the steps in How do I configure the client to receive signed userinfo JWTs? to configure PingOne Advanced Identity Cloud to receive signed JWTs.
Now you are ready to configure PingOne Advanced Identity Cloud to receive encrypted JWTs.
-
Provide a JWK with the public key to the identity provider. Refer to the their documentation for more information.
For example, you could copy the contents of the public JWK in a field in the provider’s service configuration, or you could configure the realm’s
/oauth2/connect/rp/jwk_uri
endpoint, which exposes the client’s public keys.Configure the realm’s
/oauth2/connect/rp/jwk_uri
endpoint in the provider, which exposes the client’s public keys. Refer to the provider’s documentation for more information.
Possible values are:
JSON
-
The provider’s
userinfo
endpoint returns a JSON object. SIGNED_JWT
-
The provider’s
userinfo
endpoint returns a signed JWT. SIGNED_THEN_ENCRYPTED_JWT
-
The provider’s
userinfo
endpoint returns a signed, then encrypted JWT.
-
- JWKS URI Endpoint
-
The URI that contains the public keys of the identity provider. PingOne Advanced Identity Cloud will use these keys to verify signatures or to encrypt objects.
Configure this field when:
-
Client Authentication Method is set to
ENCRYPTED_PRIVATE_KEY_JWT
. -
Encrypt Request Parameter JWT is enabled.
-
User Info Response Format is set to
SIGNED_JWT
orSIGNED_THEN_ENCRYPTED_JWT
.
Required: No.
-
- Claims
-
Any claims on the request object, in JSON format. These claims must conform to the claims request parameter, as defined in the OpenID Connect specification.
- JWT Signing Algorithm
-
The signing algorithm supported by the provider that Advanced Identity Cloud uses to sign the following:
-
Client authentication JWTs when Client Authentication Method is set to
PRIVATE_KEY_JWT
. -
(OIDC providers only) Request JWTs when Request Parameter JWT Option is set to
VALUE
orREFERENCE
.
Obtain a list of the supported algorithms from the provider’s
.well-known
endpoint. SelectNONE
if the client will encrypt the JWT with the Direct AES Encryption method, because the signature will be redundant.
Required: No. -
- JWT Encryption Algorithm
-
The encryption algorithm supported by the provider that PingOne Advanced Identity Cloud should use to encrypt client authentication JWTs when Client Authentication Method is set to
PRIVATE_KEY_JWT
, and (OIDC providers only) request JWTs when Request Parameter JWT Option is set toVALUE
orREFERENCE
.If set to
NONE
, PingOne Advanced Identity Cloud will not encrypt the JWTs. Obtain a list of the supported algorithms from the provider’s.well-known
endpoint.Required: No.
- JWT Encryption Method
-
The encryption algorithm supported by the provider that PingOne Advanced Identity Cloud should use to encrypt the following:
-
Client authentication JWTs when Client Authentication Method is set to
PRIVATE_KEY_JWT
. -
(OIDC providers only) Request JWTs when Request Parameter JWT Option is set to
VALUE
orREFERENCE
.
Use in conjunction with
JWT Encryption Algorithm
. Obtain a list of the supported methods from the provider’s.well-known
endpoint.
Required: No. -
- Private Key JWT Expiration Time (seconds)
-
Specifies the amount of time, in seconds, that PingOne Advanced Identity Cloud will cache the client authentication JWT before creating a new one.
Caching the JWT avoids creating a new one for every client authentication. However, it may also become invalid if the provider changes it configuration.
Required: No.
- Response Mode
-
(OIDC providers only) Specify the way the provider will return ID tokens to PingOne Advanced Identity Cloud. Possible values are:
-
DEFAULT
. The provider returns the ID token as query parameters, as explained in the OpenID Connect Core 1.0 incorporating errata set 1 specification.Most preconfigured providers use the
DEFAULT
response mode. -
FORM_POST
. The provider returns the ID token by submitting an HTML form using the HTTP POST method, as explained in the OAuth 2.0 Form Post Response Mode specification.When using this response mode, add the
/oauth2/client/form_post/ClientConfigName
URI to the Redirect URL, where ClientConfigName is the name of the social identity provider client that you are configuring. For example,https://platform.example.com:8443/am/oauth2/client/form_post/myAppleClient
.By default, the
form_post
endpoint processes the post data, encrypts it, and redirects with it back to the authentication journey to resume authentication.However, environments using custom login pages need to configure the Redirect after form post URL property to redirect back to the custom login pages.
Required: Yes.
-
- Certificate Revocation Checking Options
-
Specify one or more options to be used by the TLS certificate revocation checking mechanism.
The possible values are:
-
ONLY_END_ENTITY
: Only check the revocation status of end-entity certificates. -
PREFER_CRLS
: Prefer certificate revocation lists (CRLs) to Online Certificate Status Protocol (OCSP). -
NO_FALLBACK
: Disable the fallback mechanism. -
SOFT_FAIL
: Allow revocation check to succeed if the revocation status cannot be determined due to a network error. -
DISABLE_REVOCATION_CHECKING
: Disable all revocation checking.
Including
DISABLE_REVOCATION_CHECKING
as one of the options will prevent any revocation checking. For further details of the other options, refer to: PKIXRevocationChecker.Option.If no options are selected, the default behavior is to enable revocation checking with
SOFT_FAIL
.If the certificate does not specify any OCSP or CRL endpoints, the revocation checking will hard fail even if the
SOFT_FAIL
option is enabled. In this case, an administrator could disable revocation checking. -
- Use custom trust store
-
Specifies whether a custom truststore is used to verify the server certificate of the
.well-known
endpoint or JWKs URI of an OpenID provider (OP) in a TLS handshake.If enabled, a secret label is generated dynamically using the alphanumeric characters of the client configuration name. For example, a client configuration called
sampleOidcConfig
results in a secret label namedam.services.oidc.reliant.party.sampleOidcConfig.truststore
.Note that an administrator must map the generated secret label to an alias that exists in the realm secret store.
If this setting is not enabled, the default truststore is used to verify the server certificate.
- Request Native App for UserInfo
-
(Apple SSO) When enabled, this flag indicates that the native app can send the user’s
userinfo
in JSON format.Apple returns the
userinfo
only once, when the user first consents to send their details, and not on subsequent authentication attempts. In addition, the user has the option not to consent to Apple sending theiruserinfo
.If you are progressively profiling the
userinfo
with data from other social providers—usually by using a Patch Object node--there is a risk of overwriting the user’s details with blank values when the user authenticates through Apple SSO.To mitigate this risk, you can add a Scripted Decision node to your authentication journey to assess whether
userinfo
is provided.How do I use a Scripted Decision node to check
userinfo
?The normalized-profile-to-managed-user.js script sets a boolean flag (
nameEmptyOrNull
) that indicates whether Apple returned the user’sfirstName
andlastName
.Add a Scripted Decision node to your journey that evaluates the flag and sets the outcome accordingly; for example:
-
Next-generation
-
Legacy
if (nodeState.get('nameEmptyOrNull')) { action.goTo("true"); } else { action.goTo("false"); }
var fr = JavaImporter(org.forgerock.openam.auth.node.api.Action); if (nodeState.get('nameEmptyOrNull')) { action = fr.Action.goTo("true").build(); } else { action = fr.Action.goTo("false").build(); }
You can now configure your journey to patch the
userinfo
object based on the outcome of the Scripted Decision node. If you need to progressively profile the user information on every authentication, regardless of whether the user’s first name and last name are returned by the OIDC provider, you can use another Scripted Decision node that does the following:-
If the user details aren’t present, route the
userinfo
patch through a Patch Object node configured to ignore thefirstName
andlastName
. (In the Ignored Fields list, addgivenName
to ignore thefirstName
andsn
to ignore thelastName
.) -
If the user details are present, route the
userinfo
patch through a Patch Object node that patches the full object.
For more information, refer to First name and last name are missing when signing in to Identity Cloud or AM 7.x using Apple social sign-on in the ForgeRock Knowledge Base.
Required: No.
-
- UI Config Properties
-
Specifies a map of properties defined and consumed in the UI. The map affects how the identity provider’s logo will show on the login page.
PingOne Advanced Identity Cloud common end user UI properties
-
buttonImage
: A relative path to an image in the End User UI. -
buttonCustomStyle
: Any custom CSS you wish to apply to the button outside of normal End User UI styling. -
buttonClass
: Adds the specified class to the identity provider button, for any additional styling you want to apply. -
buttonCustomStyleHover
: Adds custom styling when the cursor is hovering over the button. -
buttonDisplayName
: The name of the identity provider, which will be included either on the button or in the button’salt
attribute, depending on styling. -
iconFontColor
: Specifies the color of the icon. You can use methods supported in CSS (such aswhite
, or#ffffff
). -
iconClass
: Adds the specified class to the identity provider icon, for any additional styling you want to apply. -
iconBackground
: The color for the background of the icon. You can use methods supported in CSS (such aswhite
, or#ffffff
).
Required: Yes
-
- Transform Script
-
A script to convert the provider’s raw profile object into a normalized object.
Each social identity provider returns different user profile information using their own attribute names.
For example, Google’s OIDC
/userinfo
endpoint returns claims, which PingOne Advanced Identity Cloud stores in arawProfile
object. The followinggoogle-profile-normalization.js
script maps the attributes of this object to PingOne Advanced Identity Cloud profile attributes:(function () { var frJava = JavaImporter( org.forgerock.json.JsonValue ); var normalizedProfileData = frJava.JsonValue.json(frJava.JsonValue.object()); normalizedProfileData.put('id', rawProfile.get('sub')); normalizedProfileData.put('displayName', rawProfile.get('name')); normalizedProfileData.put('givenName', rawProfile.get('given_name')); normalizedProfileData.put('familyName', rawProfile.get('family_name')); normalizedProfileData.put('photoUrl', rawProfile.get('picture')); normalizedProfileData.put('email', rawProfile.get('email')); normalizedProfileData.put('username', rawProfile.get('email')); normalizedProfileData.put('locale', rawProfile.get('locale')); return normalizedProfileData; }());
The script returns a JsonValue object containing normalized attributes in the following format:
("<platformAttributeName>", rawProfile.<providerAttributeName>)
Even if field names are the same, such as
email
andrawProfile.email
, they still need to be mapped for them to be included in the returned JSON object.PingOne Advanced Identity Cloud provides default scripts for other preconfigured identity providers. To view the bindings and expected return values, find the
<identity provider>-profile-normalization.*
scripts in Sample scripts.To write your own script in Javascript for an identity provider, go to Realms > Realm Name > Scripts, and use the provided scripts as a reference.
When a user authenticates, the social authentication journey calls another transformation script set in the Social Provider Handler node to convert the attributes again; this time into an identity object that PingOne Advanced Identity Cloud can process.
Social authentication nodes expect every attribute to have a value. In other words, the attributes returned by the identity provider cannot be empty or
null
, or the journey will end with an error.For example, if a user tries to log in using Google as the identity provider, but they did not configure a surname in their account, Google returns
null
as the value of thefamilyName
for the identity, and social authentication fails.Ensure all users have their social profiles configured correctly, or modify the transformation scripts so that they don’t collect null or empty attributes.
Required: Yes
- Issuer comparison check
-
(OIDC providers only) Determines how the expected issuer value should match the actual value of the
iss
claim:-
EXACT
: PingOne Advanced Identity Cloud performs a string comparison between the expected and actual issuer values, which must result in an exact match. -
REGEX
: PingOne Advanced Identity Cloud evaluates the expected issuer value as a regular expression, against which the actual value must match.This lets social identity providers use a common issuer value for multiple tenants, which is replaced with a unique value during the OIDC authentication flow. For example,
^https://login.microsoftonline.com/(.*)/v2.0$
is successfully matched againsthttps://login.microsoftonline.com/tenant-d5c6a592-eec6-47f0/v2.0
.Consider the performance impact when constructing regular expressions as the comparison is performed for each social identity provider interaction.
Also, ensure the regular expression is as specific as possible to avoid matching against incorrect issuer values.
-