@ping-identity/pingone-signals-web-sdk

v5.6.9

Published

6 days ago

PingOne Signals JavaScript SDK for Web

0High
0Medium
0Low

protect pingone signals web-sdk

PingOne Signals SDK

The PingOne Signals package can be integrated into your web application in order to collect device and browser data that can be used to evaluate the risk level for attempts to access restricted resources.

Note: The Signals package can only be used for client-side programming. It should not be used for server-side JavaScript programming.

Installation
Main steps to carry out
- Import and initialize the SDK package with React
  - CRA/Vite
  - Next.js
- Initialization - optional parameters
- Get the output of the SDK
- Create the risk evaluation, providing the SDK output as input to the evaluation
- Choose a path based on result of risk evaluation - high, medium, or low risk
Reference documentation
Troubleshooting

Installation

Run one of the following commands to install the package on the server hosting your application.

npm install @ping-identity/p14c-js-sdk-signals
# or
yarn add @ping-identity/p14c-js-sdk-signals
# or
pnpm add @ping-identity/p14c-js-sdk-signals

Main steps to carry out

To use the data collected by the Signals SDK, add code to carry out the following steps:

Import the SDK package
Initialize the SDK
Get the output of the SDK
Create risk evaluation using the PingOne API
Choose a path based on result of risk evaluation - high, medium, or low risk

Import and initialize the SDK package with React

To maximize the amount of risk-related data collected, the Signals SDK should be loaded and initialized as early as possible - in the <head> section or the earliest client-side hook.

Internally, the SDK is attached to the global window as _pingOneSignals.

CRA/Vite

import { useEffect } from 'react';

function onPingOneSignalsReady(callback) {
  if (window['_pingOneSignalsReady']) {
    callback();
  } else {
    document.addEventListener('PingOneSignalsReadyEvent', callback);
  }
}

function App() {
  useEffect(() => {
    import('@ping-identity/p14c-js-sdk-signals').then(() => {
      onPingOneSignalsReady(function () {
        _pingOneSignals
          .init({
            // If you are using the PingFed authentication API and version 1.3 of the Integration Kit, uncomment to turn off behavioral data collection
            // behavioralDataCollection: false,
          })
          .then(function () {
            console.log('PingOne Signals initialized successfully');
            // Optionally get data
            return _pingOneSignals.getData();
          })
          .then(function (result) {
            if (result) console.log('get data completed: ' + result);
          })
          .catch(function (e) {
            console.error('SDK Init/getData failed', e);
          });
      });
    });
  }, []);

  return <div>My App</div>;
}

Next.js

'use client';
import { useEffect } from 'react';

function onPingOneSignalsReady(callback) {
  if (typeof window !== 'undefined' && window['_pingOneSignalsReady']) {
    callback();
  } else if (typeof document !== 'undefined') {
    document.addEventListener('PingOneSignalsReadyEvent', callback);
  }
}

export default function Page() {
  useEffect(() => {
    (async () => {
      await import('@ping-identity/p14c-js-sdk-signals');
      onPingOneSignalsReady(function () {
        _pingOneSignals
          .init({
            // If you are using the PingFed authentication API and version 1.3 of the Integration Kit, uncomment to turn off behavioral data collection
            // behavioralDataCollection: false,
          })
          .then(function () {
            console.log('PingOne Signals initialized successfully');
            return _pingOneSignals.getData();
          })
          .then(function (result) {
            if (result) console.log('get data completed: ' + result);
          })
          .catch(function (e) {
            console.error('SDK Init/getData failed', e);
          });
      });
    })();
  }, []);

  return <main>Login</main>;
}

Initialization - optional parameters

When you initialize the Signals SDK, you can include one or more of the following options. The Minimum SDK Version column indicates in what version the option was first added.

| Name | Minimum SDK Version | Description | | ---- |-----------------| ----------- | | behavioralDataCollection | 5.2.1 | Set to false to turn off behavioral data collection when using the PingFederate authentication API with PingOne Risk Integration Kit v1.3. Default: true (collected unless disabled). | | disableTags | 5.3.0 | Disables the default tags array that records visited URLs and visit timestamps. Default: false (tags are collected). | | universalDeviceIdentification | 5.3.0 | When true, device data in the SDK payload is provided as a signed JWT. Default: false. | | agentIdentification | 5.4.0 | Enable if your risk policies use the PingID Device Trust predictor. Default: false. | | agentTimeout | 5.4.0 | Applicable when agentIdentification is true. Timeout for the trust agent in milliseconds. Allowed range: 200–10,000 ms. Uses SDK default if not set. | | agentPort | 5.4.0 | Applicable when agentIdentification is true. Port used to connect to the trust agent. Default: 9400. |

Get the output of the SDK

Get the data for use in risk evaluation by adding a call to the SDK's getData method, for example:

_pingOneSignals.getData()
   .then(function (result) {
       console.log("get data completed: " + result)
   }).catch(function (e) {
       console.error('getData Error!', e);
});

Note: Do not modify the SDK output in any way. Pass it along, as is, to the risk evaluation.

Create the risk evaluation, providing the SDK output as input to the evaluation

Use the PingOne API to create a risk evaluation, providing the SDK payload as a parameter, as shown in the the Create Risk Evaluation example in the PingOne API documentation.

Choose a flow path based on result of risk evaluation - high, medium, or low risk

Add to your flow appropriate paths based on the result of the risk evaluation, for example, denial of access for a high risk result, or requiring an MFA step for medium risk.

Reference documentation

Troubleshooting

If you encounter the error "Protect Signals SDK can only be used in the browser", you probably imported the package in a server-side rendering context (SSR).
If you encounter an error stating that the SDK object is undefined, check that your bundler isn't tree-shaking the import. Use the default export.
If no signals are collected, meaning the SDK data returned is null or an empty string, verify that you have loaded and initialized the SDK early in the page lifecycle.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme