Step 4. Configure the widget

The Advanced Identity Cloud/PingAM Login Widget needs the URL of your server’s .well-known/openid-configuration endpoint. If you use OAuth/OIDC tokens, user info, or logout, it also needs an OIDC client configuration.

To provide these settings, import and await the async configure() function:

Example Advanced Identity Cloud/PingAM Login Widget configuration

// Import the modules
import Widget, { configure } from '@forgerock/login-widget';

// configure() is async, so await it before calling any other Widget API
await configure({
  // REQUIRED; the well-known URL, shared by the journey and OIDC clients
  serverConfig: {
    wellknown: 'https://openam-forgerock-sdks.forgeblocks.com/am/oauth2/realms/root/realms/alpha/.well-known/openid-configuration',
  },
  // REQUIRED if you use OAuth/OIDC tokens, user info, or logout
  oidcClient: {
    clientId: 'sdkPublicClient',
    redirectUri: `${window.location.origin}/callback`,
    // OPTIONAL; defaults to 'openid'
    scope: 'openid profile email address',
  },
});

Call configure() once at the top level of your application, such as its index.js or app.js file, and await the result before any other Widget API.

The Advanced Identity Cloud/PingAM Login Widget constructs its internal clients during this call. Any Widget API, including journey().start(), user.info().get(), or user.tokens().get(), throws an error if it runs before configure() resolves.

Widget configuration properties

The properties accepted by configure() are as follows:

Server

Properties
Property	Description
`serverConfig: { wellknown }`	Required. The full URL to your server’s `.well-known/openid-configuration` endpoint. The Advanced Identity Cloud/PingAM Login Widget uses this single URL to discover the endpoints for both the journey client and the OIDC client. The realm is encoded in the path. PingOne Advanced Identity Cloud 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`

Logging, middleware, and storage

Properties
Property	Description
`logger`	Optional. Forwarded to both the journey and OIDC clients. `logger.level` sets log verbosity. Supported values are `none`, `error`, `warn`, `info`, and `debug`. `logger.custom` redirects log output to your own sink instead of the console.
`middleware`	Optional. An array of request middleware functions, forwarded to both Journey and OIDC clients. Each function has the shape `(req, action, next) => void`.
`storage`	Optional. Configures where the OIDC client persists tokens. Forwarded to the OIDC client only. Accepts either: `{ type: 'localStorage' \| 'sessionStorage', name, prefix }` — `type` and `name` is required; `prefix` is optional. `{ type: 'custom', name, prefix, custom: { get, set, remove } }` — `type`, `name`, and `custom` are required; `prefix` is optional.

OAuth 2.0

The oidcClient object is required if you use OAuth/OIDC tokens, user info, or logout.

Property Description

oidcClient: { clientId }

Required within oidcClient. The client_id of the OAuth 2.0 client profile to use.

oidcClient: { redirectUri }

Required within oidcClient. The redirect_uri as configured in the OAuth 2.0 client profile. Must be a full URL.

The Ping (ForgeRock) 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.

oidcClient: { scope }

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

For example, openid profile email address.

If not provided, the default value is openid.

oidcClient: { oauthThreshold }

Optional within oidcClient. A number, in milliseconds, controlling how long before expiry the Advanced Identity Cloud/PingAM Login Widget attempts to silently renew an access token.

oidcClient: { par }

Optional within oidcClient. Set to true to use Pushed Authorization Requests (PAR) for the authorization flow.

oidcClient: { loginHint }

Optional within oidcClient. A string bridged onto the silent token-renewal request to pre-fill the username.

oidcClient: { acrValues }

Optional within oidcClient. A string of Authentication Context Class Reference values, bridged onto the silent token-renewal request. Use this for step-up authentication.

oidcClient: { query }

Optional within oidcClient. An object of additional query parameters bridged onto the silent token-renewal request.

Optional configuration objects

Properties
Property	Description
`captcha`	Configure CAPTCHA rendering. Currently supports `mode: 'visible'` (default) or `mode: 'invisible'`. Refer to Implement a CAPTCHA.
`content`	Override the widget’s default text content, or provide localized strings. Refer to Localizing the widget.
`journeys`	Map HREF values rendered by the widget to journeys so that clicking a link starts a journey instead of navigating. Refer to Journeys configuration options.
`links`	Set the full canonical URL to your terms and conditions page. Refer to Links configuration options.
`style`	Configure the widget’s visual appearance, including labels, logos, stage icons, password visibility, and theme colors and fonts. Refer to Style configuration options.

Next, you can Step 5. Instantiate the widget.