Ping SDKs

Step 4. Configure the SDK

The Ping (ForgeRock) Login Widget requires information about the server instance it connects to, as well as OAuth 2.0 client configuration and other settings.

To provide these settings, import and use the configuration module and its set() method.

The Ping (ForgeRock) Login Widget uses the same underlying configuration properties as the main SDK. Add your configuration under the forgerock property:

Example Ping (ForgeRock) Login Widget configuration
// Import the modules
import Widget, { configuration } from '@forgerock/login-widget';

// Create a configuration instance
const myConfig = configuration();

// Set the configuration properties
myConfig.set({
  forgerock: {
    // Minimum required configuration:
    serverConfig: {
        baseUrl: 'https://openam-forgerock-sdks.forgeblocks.com/am',
        timeout: 3000,
    },
    // Optional configuration:
    clientId: 'sdkPublicClient', // The default is `WebLoginWidgetClient`
    realmPath: 'alpha',  // This is the default if not specified
    redirectUri: window.location.href,  // This is the default if not specified
    scope: 'openid profile email address', // The default is `openid profile` if not specified
  },
});

Set your Ping (ForgeRock) Login Widget configuration at the top level of your application, such as its index.js or app.js file.

This ensures the Ping (ForgeRock) Login Widget has the configuration needed to call out to your PingOne Advanced Identity Cloud or PingAM server whenever and wherever you use its APIs in your app.

For example, you must set the configuration before starting a journey with journeyEvents.start() or calling either userEvents.get() or tokenEvents.get().

SDK configuration properties

The configuration properties available in both the SDK and the Ping (ForgeRock) Login Widget are as follows:

Ping SDK for JavaScript properties
Property Description

serverConfig

An interface for configuring how the SDK contacts the PingAM instance.

Contains baseUrl and timeout.

serverConfig: {baseUrl}

The base URL of the server to connect to, including port and deployment path.

Identity Cloud example:

https://openam-forgerock-sdks.forgeblocks.com/am

Self-hosted example:

https://openam.example.com:8443/openam

serverConfig: {wellknown}

A URL to the server’s .well-known/openid-configuration endpoint.

Use the Config.setAsync() method to set SDK configuration using values derived from those provided at the URL.

Example:

https://openam-forgerock-sdks.forgeblocks.com/am/oauth2/realms/root/realms/alpha/.well-known/openid-configuration

Self-hosted example:

https://openam.example.com:8443/openam/oauth2/realms/root/.well-known/openid-configuration

serverConfig: {timeout}

A timeout, in milliseconds, for each request that communicates with your server.

For example, for 30 seconds specify 30000.

Defaults to 5000 (5 seconds).

realmPath

The realm in which the OAuth 2.0 client profile and authentication journeys are configured.

For example, alpha.

Defaults to the self-hosted top-level realm root.

tree

The name of the user authentication tree configured in your server.

For example, sdkUsernamePasswordJourney.

clientId

The client_id of the OAuth 2.0 client profile to use.

redirectUri

The redirect_uri as configured in the OAuth 2.0 client profile.

The Ping SDK for JavaScript attempts to load the redirect page to capture the OAuth 2.0 code and state query parameters that the server appended to the redirect URL.

If the page you redirect to does not exist, takes a long time to load, or runs any JavaScript you might get a timeout, delayed authentication, or unexpected errors.

To ensure the best user experience, we highly recommend that you redirect to a static HTML page with minimal HTML and no JavaScript when obtaining OAuth 2.0 tokens.

For example, https://localhost:8443/callback.html.

scope

A list of scopes to request when performing an OAuth 2.0 authorization flow, separated by spaces.

For example, openid profile email address.

oauthThreshold

A threshold, in seconds, to refresh an OAuth 2.0 token before the access_token expires.

Defaults to 30 seconds.

logLevel

Specify whether the SDK should output its log messages in the console and the level of messages to display.

One of:

  • none (default)

  • info

  • warn

  • error

  • debug

logger

Specify a function to override the default logging behavior.

Refer to Customize the Ping SDK for JavaScript logger.

tokenStore

The API to use for storing tokens on the client:

sessionStorage

Store tokens using the sessionStorage API. The browser clears session storage when a page session ends.

localStorage

Store tokens using the localStorage API. The browser saves local storage data across browser sessions. This is the default setting, as it provides the highest browser compatibility.

prefix

Override the default fr prefix string applied to the keys used for storing data on the client, such as tokens, device IDs, and information about the steps in a journey.

For example, the key used for storing tokens consists of the prefix, followed by the ID of the OAuth 2.0 client:

fr-sdkPublicClient.

platformHeader

Specify whether to include an X-Requested-Platform header in outgoing requests.

The server can use the value of this header to alter the logic of an authentication flow. For example, if the value indicates a JavaScript web app, the journey could avoid device binding nodes, as they are only supported by Android and iOS apps.

Defaults to false.

Next

Next, you can Step 5. Instantiate the widget.