Ping SDKs

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 Config.setAsync() 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

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

{{custom}}

Specify a custom implementation that has functions that can set, retrieve, and remove, items from a custom storage scheme.

Learn more in Customize storage on JavaScript.

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:

Config.setAsync({
    serverConfig: {
        wellknown: 'https://openam-forgerock-sdks.forgeblocks.com/am/oauth2/realms/root/realms/alpha/.well-known/openid-configuration',
        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.

How do I find my PingOne Advanced Identity Cloud .well-known URL?

You can view the .well-known endpoint for an OAuth 2.0 client in the PingOne Advanced Identity Cloud admin console:

  1. Log in to your PingOne Advanced Identity Cloud administration console.

  2. Click Applications, and then select the OAuth 2.0 client you created earlier. For example, sdkPublicClient.

  3. On the Sign On tab, in the Client Credentials section, copy the Discovery URI value.

    For example, https://openam-forgerock-sdks.forgeblocks.com/am/oauth2/alpha/.well-known/openid-configuration

If you are using a custom domain, your .well-known is formed as follows:

https://<custom-domain-fqdn>/.well-known/openid-configuration

Learn more in Access OIDC configuration discovery endpoint.
How do I find my PingAM .well-known URL?

To form the .well-known URL for an PingAM server, concatenate the following information into a single URL:

  1. The base URL of the PingAM component of your deployment, including the port number and deployment path.

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

  2. The string /oauth2

  3. The hierarchy of the realm that contains the OAuth 2.0 client.

    You must specify the entire hierarchy of the realm, starting at the Top Level Realm. Prefix each realm in the hierarchy with the realms/ keyword.

    For example, /realms/root/realms/customers

    If you omit the realm hierarchy, the top level ROOT realm is used by default.

  4. The string /.well-known/openid-configuration

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

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`
});