@ping-identity/pf-authn-js-widget

v2.0.0

Published

4 months ago

JavaScript Widget for the PingFederate Authentication API

Downloads

121

0High
0Medium
0Low

PingFederate Ping Identity API Authentication javascript

JavaScript Widget for the PingFederate Authentication API

Table of Contents

The JavaScript Widget for the PingFederate Authentication API is a customizable JavaScript library that provides the capabilities of the HTML form Adapter and other integrations via Authentication APIs, including:

user login
trouble signing in
trouble with username
password reset
authenticate with identifier
risk-based authentication
social login
multi-factor authentication
identity verification

A full list of the supported integrations can be found here.

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:

First enable the authentication API: Authentication > Authentication API Applications > Enable Authentication API.
Then, add an application by clicking the "Add Authentication Application" button and entering the appropriate values. For example: Name: TestApp, URL: https://localhost:8443.
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.

Select your newly created Authentication Application ("TestApp" if you used the example above) in the drop-down in the "Default Authentication Application" section.
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 three ways to get the widget. You can include it from Ping Identity's CDN, 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: Using CDN Links:

A pre-built widget is available for incorporating directly into your application. All versions of the widget, starting with 1.7.0, will be available via CDN.

To include the latest released version the following links can be used:

https://downloads.pingidentity.com/pf-authn-widget/latest/v2/pf.authn-widget.js
https://downloads.pingidentity.com/pf-authn-widget/latest/v2/main-styles.css

To include a specific version of the widget, replace latest with the version required.

https://downloads.pingidentity.com/pf-authn-widget/2.0.0/pf.authn-widget.js
https://downloads.pingidentity.com/pf-authn-widget/2.0.0/main-styles.css

A working example that utilizes the pre-built widget would look like:

<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="https://downloads.pingidentity.com/pf-authn-widget/latest/v2/pf.authn-widget.js"></script>
    <link rel="stylesheet" type="text/css" href="https://assets.pingone.com/ux/end-user/0.36.1/end-user.css">
    <link rel="stylesheet" type="text/css" href="https://downloads.pingidentity.com/pf-authn-widget/latest/v2/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>

Option 2: 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 3: 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:

Run npm install @ping-identity/pf-authn-js-widget --save
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)
useActionParam: By default the widget uses a custom content type to request authentication API actions. If this flag is set to true, the widget instead uses a query parameter, which may be required in environments where custom content types are blocked. This query parameter is only supported for version 10.2 of PingFederate and later.

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

Upgrade from version 1 to version 2

The JavaScript Widget for PingFederate Authentication API no longer requires custom javascript code to enable CAPTCHA as of version 2.

When upgrading from version 1 to version 2, remove the custom javascript code and replace it with standard widget initialization code to leverage the new capability. More information is available in the Widget Configuration section of this document.

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:

npm install
npm run build
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).
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.36.1/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.36.1/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

Using Protect-Based Authentication Adapters with the Widget

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

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.

Typescript Support

Please refer to the Typescript Support guide for more information on how to use the typescript definitions.

Browser Compatibility

The widget relies upon a cookie that is transferred between the widget and PingFederate. If the widget and PingFederate are hosted on different domains, this cookie will be a cross-origin or third-party cookie. Some browsers such as Firefox and Safari block third-party cookies by default, which will break the widget's functionality.

To be compatible with all major browsers, the widget must be deployed on the same domain as PingFederate, or on a subdomain of the same domain. For example, the following configuration will work for all browsers

PingFederate instance hosted at sso.example.com
Widget instance hosted at auth.example.com

While the configuration

PingFederate hosted at sso.example.com
Widget hosted at auth.differentdomain.com

will require users to enable third-party cookies in their browser configuration.

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.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

JavaScript Widget for the PingFederate Authentication API

PingFederate Configuration

Installation

Option 1: Using CDN Links:

Option 2: Building the Widget

Option 3: Adding the Widget as a Node Module

Widget Configuration

Upgrade from version 1 to version 2

Technical Notes

Building the Latest Version of the Widget

Adding the Widget to an Application

Creating the index.html File

Customizing the Widget

Using Protect-Based Authentication Adapters with the Widget

Using Risk-Based Authentication With the Widget

Redirectless Support

Typescript Support

Browser Compatibility

Bug Reports

License