Step 1. Set up the servers
In this step, you set up your ForgeRock and PingOne servers to perform risk evaluations.
Create a worker application in PingOne
To allow your ForgeRock server to access the PingOne administration API you must create a worker application in PingOne.
The worker application provides the client credentials your ForgeRock server uses to communicate with the PingOne admin APIs using the OpenID Connect protocol.
To create a worker application in PingOne:
-
In the PingOne administration console, navigate to Add ().
, and then click -
In the Add Application panel:
-
In Application name, enter a unique identifier for the worker application.
For example,
ForgeRock SDK Worker
. -
Optionally, enter a Description for the application and select an Icon.
These do not affect the operation of the worker application but do help you identify it in the list.
-
In Application Type, select Worker.
-
Click Save.
-
-
In the application properties panel for the worker application you created:
-
On the Roles tab, click Grant Roles.
-
On the Available responsibilities tab, select the Identity Data Admin row, and ensure the environment is correct.
-
Click Save.
-
On the Overview tab, ensure your worker application resembles the following image, and then enable it by using the toggle (1):
Figure 1. Example worker application in PingOne -
Make a note of the Environment ID, Client ID, and Client Secret values (2).
You need these values in the next step when you Configure the PingOne Worker service in your ForgeRock server.
-
Configure the PingOne Worker service in your ForgeRock server
After you create a worker application in PingOne, you must configure the PingOne Worker service in your ForgeRock server with the credentials.
You will need the following values from your PingOne Worker application:
- Client ID
-
Client ID of the worker application in PingOne.
Example:
6c7eb89a-66e9-46df-9ee2-eeaf795650b2
- Client Secret
-
Client secret of the worker application in PingOne.
Use the Secret Mask () or Copy to Clipboard () buttons to obtain the value in the PingOne administration console. Example:
Ch15~o5Hm8N4_eS_m8~ARrV0KQAIQS6d.sJWe8TMXurEb~KWexY_p0gelR
- Environment ID
-
Identifier of the environment that contains the worker application in PingOne.
Example:
3072206d-c6ce-4c19-a366-f87e972c7cc3
To configure the PingOne worker service:
-
If you are using ID Cloud, in the administration console navigate to Native Consoles > Access Management.
-
In the AM admin UI, click Services.
-
If the PingOne Worker Service is in the list of services, select it.
-
If you do not yet have a PingOne Worker Service:
-
Click Add a Service.
-
In Choose a service type, select
PingOne Worker Service
, and then click Create.
-
-
On the Secondary Configurations tab, click Add a Secondary Configuration.
-
On the New workers configuration page:
-
Enter a Name for the configuration.
For example,
SDK PingOne Worker
.You use this value when you configure an authentication journey that performs risk evaluations.
-
In Client ID, enter the client ID of the PingOne Worker application you created earlier.
-
In Client Secret Label Identifier, enter an identifier to create a specific secret label to represent the client secret of the worker application.
For example,
workerAppClientSecret
.The secret label uses the template
am.services.pingone.worker.identifier.clientsecret
where identifier is the Client Secret Label Identifier value.This field can only contain characters
a-z
,A-Z
,0-9
, and.
and can’t start or end with a period.You must then add and map the client secret value from the PingOne Worker application to the ID created, such as
am.services.pingone.worker.workerAppClientSecret.clientsecret
.Figure 2. Example worker application in PingOneLearn more about mapping secrets and label identifiers in:
-
Identity Cloud: Secret labels
-
Self-managed AM: Map and rotate secrets
-
-
In Environment ID, enter the environment ID containing the PingOne Worker application you created earlier.
-
Click Create
-
-
On the Workers Configuration page, ensure that the PingOne API Server URL and PingOne Authorization Server URL are correct for the region of your PingOne servers:
PingOne URLs by region Region Authorization URL API URL North America
(Excluding Canada)
https://auth.pingone.com
https://api.pingone.com/v1
Canada
https://auth.pingone.ca
https://api.pingone.ca/v1
Europe
https://auth.pingone.eu
https://api.pingone.eu/v1
Asia-Pacific
https://auth.pingone.asia
https://api.pingone.asia/v1
-
Confirm your configuration resembles the image below, and then click Save changes.
Figure 3. Example worker application in PingOne
You have now configured the PingOne Worker service in your ForgeRock server. You can now Configure a journey to perform PingOne Protect risk evaluations.
Configure a journey to perform PingOne Protect risk evaluations
To make risk evaluations in PingOne, you must configure an authentication journey in your ForgeRock server.
The following table covers the authentication nodes and callbacks for integrating your authentication journeys with PingOne Protect.
Node | Callback | Description |
---|---|---|
Instruct the embedded PingOne Signals SDK to start gathering contextual information. |
||
Returns contextual information that the ForgeRock server can send to your PingOne Protect instance to perform a risk evaluation. |
||
Non-interactive |
Inform the PingOne Protect instance about the status of the transaction. |
In your ForgeRock server, log in as an administrator and create a new authentication journey similar to the following example:
-
The PingOne Protect Initialize node 1 instructs the SDK to initialize the PingOne Protect Signals API with the configured properties.
Initialize the PingOne Protect Signals API as early in the journey as possible, before any user interaction.
This enables it to gather sufficient contextual data to make an informed risk evaluation.
You can initialize the PingOne Protect Signals API whenever you want to start collecting data. This could be at application startup, or when a particular page or view is visited.
Learn more at initializing data collection^.
-
The user enters their credentials, which are verified against the identity store.
-
The PingOne Protect Evaluation node 2 performs a risk evaluation against a risk policy in PingOne.
The example journey continues depending on the outcome:
High
-
The journey requests that the user respond to a push notification.
Medium
orLow
-
The risk is not significant, so no further authentication factors are required.
Exceeds Score Threshold
-
The score returned is higher than the configured threshold and is considered too risky to complete successfully.
Failure
-
The risk evaluation could not be completed, so the authentication attempt continues to the Failure node.
BOT_MITIGATION
-
The risk evaluation returned a recommended action to check for the presence of a human, so the journey continues to a CAPTCHA node.
ClientError
-
The client returned an error when attempting to capture the data to perform a risk evaluation, so the authentication attempt continues to the Failure node.
-
An instance of the PingOne Protect Result node 3 returns the
Success
result to PingOne, which can be viewed in the audit console to help with analysis and risk policy tuning. -
A second instance of the PingOne Protect Result node 4 returns the
Failed
result to PingOne, which can be viewed in the audit console to help with analysis and risk policy tuning.
You have now configured a suitable authentication journey in your ForgeRock server. You can now proceed to Step 2. Install dependencies.