JavaScript Widget for the PingFederate Authentication API

Table of Contents

• JavaScript Widget for the PingFederate Authentication API
• PingFederate Configuration
• Installation
  • Option 1: Building the Widget
  • Option 2: Adding the Widget as a Node Module
  • Widget Configuration
• Technical Notes
  • Building the Latest Version of the Widget
  • Adding the Widget to an Application
  • Creating the index.html File
  • Customizing the Widget
  • Enabling Captcha
  • Using Risk-Based Authentication With the Widget
  • Redirectless Support
• Browser Compatibility
• Bug Reports
• License

The JavaScript Widget for the PingFederate Authentication API is a customizable JavaScript library that provides the capabilities of the HTML form Adapter, the Identifier First Adapter, and the ID DataWeb Integration Kit via Authentication APIs, including:

• user login
• trouble signing in
• trouble with username
• password reset
• authenticate with identifier
• risk-based authentication

The widget is a ready-to-use drop-in bundle with a CSS and customizable templates. This alternative to PingFederate templates provides a sign-in experience as a single page application.

PingFederate Configuration

PingFederate acts as the server interacting with the widget via APIs to authenticate the user.

To configure PingFederate for the widget:

1. First enable the authentication API: Authentication > Authentication API Applications > Enable Authentication API.
2. Then, add an application by clicking the "Add Authentication Application" button and entering the appropriate values. For example: Name: TestApp, URL: https://localhost:8443.
3. Click "Save".

Caution: setting your Authentication Application as the "Default Authentication Application" will make it the default authentication for all of your existing connections. This is the easiest way to configure your connections, but it is not very precise. For more precision, configure the desired authentication policies to use your Authentication API Application.

4. Select your newly created Authentication Application ("TestApp" if you used the example above) in the drop-down in the "Default Authentication Application" section.
5. Start the SSO flow as you would normally. For example, by clicking on an existing IdP Connection, and you will be redirected to your "JavaScript Widget for the PingFederate Authentication API" application.

Note: The redirect URL of the Authentication Applications must point to where the JavaScript Widget for the PingFederate Authentication API is hosted. If you do not wish to use the development server provided by webpack, change the URL of the authentication application to point the correct hosted URL.

Installation

There are two ways to get the widget. You can build and install it locally on your development machine or get it as a node dependency. You also need a running PingFederate instance that is version 9.3 or above.

Option 1: Building the Widget

Before installing, make sure you have node.js installed. Then check out this repository.

Run the following commands:

• npm install - install the dependencies
• npm run start - start the webpack development server

This will start the webpack development server on https://localhost:8443 (as specified in webpack.config.js) and instantiate the widget.

If you need to modify the base URL from localhost:9031, you can modify it in demo-server/templates/index-template.handlebars or pass a BASEURL command line parameter (see Technical Notes).

Click the start SSO link on the IdP Connection in PingFederate or start an OAuth flow from OAuth playground, which will redirect to the widget.

Note: A 'flowId' value is required for the widget to interact with PingFederate, which is created when PingFederate redirects to the widget.

Option 2: Adding the Widget as a Node Module

This is a good choice if you already have a node project with package.json and can just add this widget as a dependency.

To add the widget as a dependency:

1. Run npm install @ping-identity/pf-authn-js-widget --save
2. Add <div id="authnwidget"></div> to your app.

Widget Configuration

The only information required to configure the widget is PingFederate's base URL. The widget can be instantiated and initialized using the following code example:

var baseUrl = 'https://localhost:9031';
var authnWidget = new PfAuthnWidget(baseurl);
authnWidget.init();

Here are all the available constructor parameters, their descriptions, and a usage code example:

• baseUrl: full address of where PingFederate is running, such as https://localhost:9031
• divId: where the widget should be rendered (optional)
• logo: to display on top of every page (this can be passed in as a file or as the URL where the image is hosted)

var baseUrl = 'https://localhost:9031';
var authnWidget = new PfAuthnWidget(baseUrl, {divId: 'mywidget', logo: 'https://path-to-my-logo.svg'})
authnWidget.init();

Technical Notes

Here are all available npm commands:

• npm install - install the dependencies locally
• npm run build - build for production
• npm run start - start the dev server
• BASEURL=https://PingFederateBaseUrl:9031 npm run start - pass a custom base URL from the command line (Mac/Linux only)
• npm run clean - remove the dist/ and coverage directory
• npm run coverage - run ESLint coverage
• npm run test - run tests
• npm run test:watch - just watch the tests

Building the Latest Version of the Widget

Before installing, make sure you have node.js installed. Then check out this repository.

To build the widget:

1. npm install
2. npm run build
3. Copy all the files in the dist folder to where your application will be hosted (this part can be skipped if webpack's development server is used).
4. Create an index.html as shown below.

Adding the Widget to an Application

At minimum you must include:

• pf.authn-widget.js - main javascript library
• https://assets.pingone.com/ux/end-user/0.29.0/end-user.css - basic CSS from CDN
• main-styles.css - widget CSS

Creating the index.html File

Create a file called index.html with the following content and host it in your web server.

<html>
  <head>
    <title>Authentication API Sample App</title>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
    <script src="./pf.authn-widget.js"></script>        
    <link rel="stylesheet" type="text/css" href="https://assets.pingone.com/ux/end-user/0.29.0/end-user.css">
    <link rel="stylesheet" type="text/css" href="main-styles.css">
    <script>
      function load() {
        var authnWidget = new PfAuthnWidget("{{baseUrl}}", { divId: 'authnwidget' });
        authnWidget.init()
      }
      window.onload = load;
    </script>
  </head>

  <body>
    <div class="content" style="padding: 30px">
      <div class="heading">Authentication Application</div>
      <div id="authnwidget"></div>
    </div>
  </body>
</html>

The name of the div can be overwritten in the constructor under options by passing a divId parameter.

Customizing the Widget

All the HTML pages are rendered using Handlebars under the /partials directory. The /scss/ folder contains all the sass files for customizing the styles. Basic CSS should be imported by default from CDN.

Note: Some items cannot be customized:

• the data-actionId must match the actionId that is sent to PingFederate
• the form IDs in the handlebars templates must match what's being referenced in the index.js FORM_ID
• the basic CSS end-user.css is provided via CDN, as shown in demo-server/templates/index-template.handlebars
• the widget-specific CSS is provided via the compiled sass file as main-styles.css
• to overwrite the CSS, add any customization to src/scss/branding.scss and include it in src/index.js

Enabling Captcha

To use Captcha with the HTML Form Adapter, import api.js from Google's CDN at <script src="https://www.google.com/recaptcha/api.js?onload=onloadCallback&render=explicit" async defer></script> After the script is loaded, instantiate the widget.

Three functions are needed:

var authnWidget;

function checkRecaptcha(token) {
  console.log('captcha response: ' + token);
  if (token.length === 0) {
    //reCaptcha not verified
    dispatchPendingState.clearPendingState();
    console.log('did not pass captcha try again');
  } else {
    //reCaptch verified
    authnWidget.dispatchPendingState(token);
  }
}

function invokeReCaptcha() {
  let token = grecaptcha.getResponse();
  if(token) {
    checkRecaptcha(token);
  }
  else {
    grecaptcha.execute();
  }
}

function onloadCallback() {
  authnWidget = new PfAuthnWidget("{{baseUrl}}", {
    divId: 'authnwidget',
    invokeReCaptcha: invokeReCaptcha,
    checkRecaptcha: 'checkRecaptcha',
    grecaptcha: grecaptcha
  });
  authnWidget.init();
}

It is crucial that api.js is loaded before the widget is instantiated. Therefore we are using a callback function to load the widget. The grecaptcha object will be available after the api.js is loaded. For more information, see Captcha documentations.

Using Risk-Based Authentication With the Widget

Please refer to the guide for using risk-based authentication with the widget for more infomation on how to set up the widget with risk-based authentication adapters.

Redirectless Support

Please refer to the Redirectless Support guide for more infomation on how to configure PingFederate and how to use widget's redirectless feature.

Browser Compatibility

The widget works with all major browsers, including Chrome, Firefox, IE11, and MS Edge.

Bug Reports

Use the issue tracker to report any bugs or to file feature requests.

License

This project is licensed under the Apache license. See the LICENSE file for more information.