Configure Ping SDK for JavaScript properties

Applies to:

Ping SDK for Android
Ping SDK for iOS
Ping SDK for JavaScript

Configure SDK properties in your JavaScript app by editing a serverConfig object, a parameter of the forgerock.Config.set() function.

Properties

The following properties are available for configuring the Ping SDK for JavaScript:

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`

Examples

The following examples show how to configure the Ping SDK in your JavaScript applications:

forgerock.Config.set({
    serverConfig: {
        baseUrl: 'https://openam-forgerock-sdks.forgeblocks.com/am',
        timeout: 3000,
        paths: {
            authenticate: 'iam/endpoints/authN',
            authorize: 'iam/endpoints/authZ'
        },
    },
    clientId: 'sdkPublicClient',
    scope: 'openid profile email address',
    redirectUri: `${window.location.origin}/callback.html`,
    realmPath: 'alpha'
});

Using the .well-known endpoint

You can configure the SDKs to obtain many required settings from your authorization server’s .well-known OpenID Connect endpoint.

Settings gathered from the endpoint include the paths to use for OAuth 2.0 authorization requests, and login endpoints.

Use the Config.setAsync method to use the .well-known endpoint to configure OAuth 2.0 paths:

await Config.setAsync({
  serverConfig: {
    wellknown: 'https://openam-forgerock-sdks.forgeblocks.com/am/oauth2/realms/root/realms/alpha/.well-known/openid-configuration'
  },
  clientId: 'sdkPublicClient',
  scope: 'openid profile email address',
  redirectUri: `${window.location.origin}/callback.html`
});

Ping SDKs