Ping SDKs

Integrate Ping SDK for JavaScript with PingFederate

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 PingFederate server to obtain the correct URIs to authenticate the user, and redirects to your PingFederate server’s login UI.

After authentication, PingFederate 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.

  1. In a web browser, navigate to the Ping SDK sample apps repository.

  2. Download the source code using one of the following methods:

    Download a ZIP file

    1. Click Code, and then click Download ZIP.

    2. Extract the contents of the downloaded ZIP file to a suitable location.

    Use a Git-compatible tool to clone the repo locally

    1. Click Code, and then copy the HTTPS URL.

    2. 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.

  1. In a terminal window, navigate to the sdk-sample-apps folder.

  2. 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 PingFederate.

  1. In the IDE of your choice, open the sdk-sample-apps folder you cloned in the previous step.

  2. 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.

  3. Update the .env file with the details of your PingFederate 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 PingFederate.

    $SCOPE

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

    For example, address email openid phone profile

    $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 PingFederate.

    For example, sdkPublicClient

    $WELL_KNOWN

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

    How do I find my PingFederate .well-known URL?

    You can form your .well-known endpoint by adding /.well-known/openid-configuration to your server’s base URL.

    To view the base URL of your PingFederate server:

    1. Log in to your PingFederate administration console.

    2. Navigate to System  Server  Protocol Settings.

    3. Make a note of the Base URL value.

      For example, https://pingfed.example.com

      Do not use the admin console URL.

    4. Append /.well-known/openid-configuration to your base URL.

    For example, https://pingfed.example.com/.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="address email openid phone profile"
TIMEOUT=3000
WEB_OAUTH_CLIENT="sdkPublicClient"
WELL_KNOWN="https://pingfed.example.com/.well-known/openid-configuration"
SERVER_TYPE="PINGONE"

Step 4. Run the central login sample app

In the following procedure, you run the sample app that you configured in the previous step.

The sample connects to your PingFederate server to obtain the correct URIs to authenticate the user, and redirects the browser to your PingFederate server.

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

Run the sample

  1. In a terminal window, navigate to the root of your sdk-sample-apps project.

  2. To run the embedded login sample, enter the following:

    npm run start:central-login-oidc

  3. In a web browser, navigate to the following URL:

    https://localhost:8443/

    The sample displays a page with two buttons:

    Running the central login app

  4. Click Login.

    The sample app redirects the browser to your PingFederate instance.

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

  5. Authenticate as a known user in your PingFederate system.

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

    If the app displays the user information, authentication was successful:

    Successful OAuth 2.0 authentication

  6. To revoke the OAuth 2.0 token, click the Sign Out button.

    In this tutorial, PingFederate 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 PingFederate server.

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

More information

Copyright © 2010-2024 ForgeRock, all rights reserved.