Ping SDKs

Integrate Ping SDK for JavaScript with PingOne Advanced Identity Cloud or PingAM

In this tutorial you update a sample app that uses embedded login.

The sample navigates through a simple authentication journey, and obtains OAuth 2.0 tokens for the user.

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/javascript 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 embedded login sample app

In this step, you configure the sample app to connect to the authentication tree/journey you created when setting up your server configuration.

Copy the .env.example file in the sdk-sample-apps/embedded-login folder and save it with the name .env within this same directory.

Add your relevant values to this new file as it will provide all the important configuration settings to your applications.

Here’s an example; your values may vary:

AM_URL=https://openam-forgerock-sdks.forgeblocks.com/am
REALM_PATH=alpha
SCOPE=openid profile email address
TIMEOUT=5000
TREE=sdkUsernamePasswordJourney
WEB_OAUTH_CLIENT=sdkPublicClient

Here are descriptions for some of the values:

TREE

The simple login journey or tree you created earlier, for example sdkUsernamePasswordJourney.

REALM_PATH

The realm of your server.

Usually, root for AM and alpha or beta for Advanced Identity Cloud.

Step 4. Run the embedded login sample app

In the following procedure, you run the sample app that you configured in the previous step. The sample connects to your server and walks through the authentication journey you created in an earlier step.

After successful authentication, the sample obtains an OAuth 2.0 access token and displays the related user information.

To run the UI 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:embedded-login

  3. In a web browser:

    1. Ensure you are NOT currently logged into the server instance.

      If you are logged into the PingAM instance in the browser, the sample will not work. Logout of the PingAM instance before you run the sample.

    2. Navigate to the following URL:

      https://localhost:8443

      A form appears with "Username" and "Password" fields, as defined by the page node in the sdkUsernamePasswordJourney you created in a previous step:

      Running the app

    3. Authenticate as a non-administrative user, and click Sign In.

      Default login credentials:

      • "Username" - demo

      • "Password" - Ch4ng3it!

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

        Successful OAuth 2.0 authentication
        To see the application calling the authorize and authenticate endpoints, open the Network tab of your browser’s developer tools.

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

    The application calls the endSession endpoint to revoke the OAuth 2.0 token, and returns to the sign-in form.

Recap

Congratulations!

You have now used the Ping SDK for JavaScript to authenticate to your server instance.

You have seen how to obtain OAuth 2.0 tokens, view the related user information, and log a user out of the server.

More information