Integrate Ping SDK for JavaScript with PingOne

In this tutorial you update a sample app that uses OIDC-based login to obtain tokens by redirecting to the server’s UI for authentication.

The sample connects to the .well-known endpoint of your PingOne server to obtain the correct URIs to authenticate the user, and redirects to your PingOne server’s login UI.

After authentication, PingOne redirects the browser back to your application, which then obtains an OAuth 2.0 access token and displays the related user information.

Check that you have completed the prerequisites before starting the tutorial.

Step 1. Download the samples

To start this tutorial, you need to download the Ping SDK sample apps repo, which contains the projects you will use.

In a web browser, navigate to the Ping SDK sample apps repository.
Download the source code using one of the following methods:
Download a ZIP file
Click Code, and then click Download ZIP.

Extract the contents of the downloaded ZIP file to a suitable location.
Use a Git-compatible tool to clone the repo locally
Click Code, and then copy the HTTPS URL.

Use the URL to clone the repository to a suitable location.

For example, from the command-line you could run:

git clone https://github.com/ForgeRock/sdk-sample-apps.git

The result of these steps is a local folder named sdk-sample-apps.

Step 2. Install the dependencies

In the following procedure, you install the required modules and dependencies, including the Ping SDK for JavaScript.

In a terminal window, navigate to the sdk-sample-apps folder.
To install the required packages, enter the following:
```
npm install
```
The npm tool downloads the required packages, and places them inside a node_modules folder.

Step 3. Configure the central login sample app

In this step, you configure the sample app to connect to the OAuth 2.0 application you created in PingOne.

In the IDE of your choice, open the sdk-sample-apps folder you cloned in the previous step.
Make a copy of the /javascript/central-login-oidc/.env.example file, and name it .env.

The .env file provides the values used by the forgerock.Config.setAsync() method in javascript/central-login-oidc/src/main.js.
Update the .env file with the details of your PingOne instance.
```
SCOPE="$SCOPE"
TIMEOUT=$TIMEOUT
WEB_OAUTH_CLIENT="$WEB_OAUTH_CLIENT"
WELL_KNOWN="$WELL_KNOWN"
SERVER_TYPE="$SERVER_TYPE"
```
Replace the following strings with the values you obtained when you registered an OAuth 2.0 application in PingOne.

$SCOPE

The scopes you added to your OAuth 2.0 application in PingOne.

For example, openid profile email address revoke

$TIMEOUT

How long to wait for OAuth 2.0 timeouts, in milliseconds.

For example, 3000

$WEB_OAUTH_CLIENT

The client ID from your OAuth 2.0 application in PingOne.

For example, 6c7eb89a-66e9-ab12-cd34-eeaf795650b2

$WELL_KNOWN

The .well-known endpoint from your OAuth 2.0 application in PingOne.

For example, https://auth.pingone.com/3072206d-c6ce-ch15-m0nd-f87e972c7cc3/as/.well-known/openid-configuration

$SERVER_TYPE

Ensures the sample app uses the correct behavior for the different servers it supports, for example what logout parameters to use.

For PingOne and PingFederate servers, specify PINGONE.

The result resembles the following:
.env
```
SCOPE="openid profile email address revoke"
TIMEOUT=3000
WEB_OAUTH_CLIENT="6c7eb89a-66e9-ab12-cd34-eeaf795650b2"
WELL_KNOWN="https://auth.pingone.com/3072206d-c6ce-ch15-m0nd-f87e972c7cc3/as/.well-known/openid-configuration"
SERVER_TYPE="PINGONE"
```
(Optional) Specify which of the configured policies PingOne uses to authenticate users.

In the /javascript/central-login-oidc/src/main.js file add an acr_values query parameter to the getTokens() calls.

There are multiple calls to the getTokens() function.

Only update the calls that have the login: 'redirect' parameter.
```
await forgerock.TokenManager.getTokens({
  login: 'redirect',
  query: {
    acr_values: "<Policy IDs>"
  }
});
```
Replace <Policy IDs> with either a single DaVinci policy, by using its flow policy ID, or one or more PingOne policies by specifying the policy names, separated by spaces or the encoded space character %20.

Examples:

DaVinci flow policy ID

acr_values: "d1210a6b0b2665dbaa5b652221badba2"

PingOne policy names

acr_values: "Single_Factor%20Multi_Factor"

For more information, refer to Editing an application - OIDC.

Step 4. Run the central login sample app

In a terminal window, navigate to the root of your sdk-sample-apps project.
To run the embedded login sample, enter the following:
```
npm run start:central-login-oidc
```
In a web browser, navigate to the following URL:

https://localhost:8443/

The sample displays a page with two buttons:

Click Login.

The sample app redirects the browser to your PingOne instance.

To see the application calling the authorize endpoint, and the redirect back from PingOne with the code and state OAuth 2.0 parameters, open the Network tab of your browser’s developer tools.

Authenticate as a known user in your PingOne system.

After successful authentication, PingOne redirects the browser to the client application.

If the app displays the user information, authentication was successful:
To revoke the OAuth 2.0 token, click the Sign Out button.

The application redirects to the PingOne server to revoke the OAuth 2.0 token and end the session, and then returns to the URI specified by the logoutRedirectUri parameter of the logout method.

In this tutorial, PingOne redirects users back to the client application, ready to authenticate again.

Recap

Congratulations!

You have now used the Ping SDK for JavaScript to obtain an OAuth 2.0 access token on behalf of a user from your PingOne server.

You have seen how to obtain OAuth 2.0 tokens, and view the related user information.

Ping SDKs

Integrate Ping SDK for JavaScript with PingOne

Step 1. Download the samples

Step 2. Install the dependencies

Step 3. Configure the central login sample app

Step 4. Run the central login sample app

Recap

More information