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:

Server

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`.

OAuth 2.0

Property Description

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.

Storage

Properties
Property	Description
`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`.

Logging

Properties
Property	Description
`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.

General

Properties
Property	Description
`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`.

Endpoints

Properties
Property	Description
`serverConfig: { paths: { authenticate }}`	Override the path to the authorization server’s `authenticate` endpoint. Default: `json/{realmPath}/authenticate`
`serverConfig: { paths: { authorize }}`	Override the path to the authorization server’s `authorize` endpoint. Default: `oauth2/{realmPath}/authorize`
`serverConfig: { paths: { accessToken }}`	Override the path to the authorization server’s `access_token` endpoint. Default: `oauth2/{realmPath}/access_token`
`serverConfig: { paths: { revoke }}`	Override the path to the authorization server’s `revoke` endpoint. Default: `oauth2/{realmPath}/token/revoke`
`serverConfig: { paths: { userInfo }}`	Override the path to the authorization server’s `userinfo` endpoint. Default: `oauth2/{realmPath}/userinfo`
`serverConfig: { paths: { sessions }}`	Override the path to the authorization server’s `sessions` endpoint. Default: `json/{realmPath}/sessions`
`serverConfig: { paths: { endSession }}`	Override the path to the authorization server’s `endSession` endpoint. Default: `oauth2/{realmPath}/connect/endSession`

Next, you can Step 5. Instantiate the widget.