API reference

This page lists the modules that the Advanced Identity Cloud/PingAM Login Widget provides for use in your apps.

This is a compiled Svelte class. This is what instantiates the component, mounts it to the DOM, and sets up all the event listeners.

import Widget from '@forgerock/login-widget';

// Instantiate Widget
const widget = new Widget({
  target: widgetRootEl, // REQUIRED; Element mounted in DOM
  props: {
    type: 'modal', // OPTIONAL; "modal" or "inline"; "modal" is default
  },
});

// OPTIONAL; Remove widget from DOM and destroy component listeners
widget.$destroy();

Call $destroy() if you instantiate the Advanced Identity Cloud/PingAM Login Widget within a part of your application frequently created and destroyed.

We strongly encourage you to instantiate the modal form factor of the Advanced Identity Cloud/PingAM Login Widget high up in your application code. Instantiate it close to the top-level file in a component that is created once and preserved.

Configuration

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

For information on setting up your server for use with the Advanced Identity Cloud/PingAM Login Widget, refer to Prerequisites.

To provide these settings, import and await the async configure() function. Call it once at the top level of your application, before any other Widget API.

import { 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
  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',
  },
  // OPTIONAL; see dedicated sections below
  captcha: {},
  content: {},
  journeys: {},
  links: {},
  style: {},
});

configure() is asynchronous. Always await it, since the Advanced Identity Cloud/PingAM Login Widget constructs its internal clients during this call. Any Widget API called before configure() resolves throws an error.

Content configuration options

Use the content configuration element to pass custom text content to the Advanced Identity Cloud/PingAM Login Widget, replacing its default values.

You can use this method to localize user interface text for different regions. Learn more in Localizing the widget.

Example content configuration

await configure({
  wellknown: 'https://openam-forgerock-sdks.forgeblocks.com/am/oauth2/realms/root/realms/alpha/.well-known/openid-configuration',
  content: {
    userName: 'Identifier',
    passwordCallback: 'Passphrase',
    nextButton: "Let's go!",
  },
});

Figure 1. Result of example content configuration

For a list of the content you can override, refer to the en-us locale file in the Advanced Identity Cloud/PingAM Web Login Framework repository.

Links configuration options

Use the links configuration element to set the full canonical URL to your terms and conditions page.

This should be a page hosted on your website or elsewhere within your app. Users are sent to this URL if they click to view the terms and conditions in the Advanced Identity Cloud/PingAM Login Widget.

This supports the TermsAndConditionsCallback often used in registration journeys.

Example links configuration

await configure({
  wellknown: 'https://openam-forgerock-sdks.forgeblocks.com/am/oauth2/realms/root/realms/alpha/.well-known/openid-configuration',
  links: {
    termsAndConditions: 'https://example.com/terms',
  },
});

Style configuration options

Use the style configuration element to configure the look and feel of the Advanced Identity Cloud/PingAM Login Widget. This allows you to choose the type of labels used or provide a logo for the modal.

Figure 2. Use the style property to control aspects of the display

Key:

Use style/logo to add images for use in dark or light modes
Set style/stage/icon to true to render UI specific to certain stage parameter values. Supported stage values are:
- OneTimePassword - enable the Advanced Identity Cloud/PingAM Login Widget to display one-time password entry forms correctly.
- DefaultRegistration - adds UI elements to the display most suitable for user self-registration forms.
- DefaultLogin - adds UI elements to the display most suitable for user log in forms.
A section that displays the Page Header and Page Description fields from the page node configuration
To float labels above their respective fields, set style/labels to floating
Use style/showPassword to control how the password visibility toggle is rendered

Adding logos and enabling icons

await configure({
  wellknown: 'https://openam-forgerock-sdks.forgeblocks.com/am/oauth2/realms/root/realms/alpha/.well-known/openid-configuration',
  style: {
    checksAndRadios: 'animated', // OPTIONAL; choices are 'animated' or 'standard'
    labels: 'floating', // OPTIONAL; choices are 'floating' or 'stacked'
    showPassword: 'button', // OPTIONAL; choices are 'none', 'button', or 'checkbox'
    logo: {
      // OPTIONAL; only used with modal form factor
      dark: 'https://example.com/img/white-logo.png', // OPTIONAL; used if theme has a dark variant
      light: 'https://example.com/img/black-logo.png', // REQUIRED if logo property is provided; full URL
      height: 300, // OPTIONAL; number of pixels for providing additional controls to logo display
      width: 400, // OPTIONAL; number of pixels for providing additional controls to logo display
    },
    sections: {
      // OPTIONAL; only used with modal form factor
      header: false, // OPTIONAL; separate the logo section from the rest of the modal
    },
    stage: {
      icon: true, // OPTIONAL; displays generic icons for the provided stages
    },
  },
});

The logo and sections properties only apply to the "modal" form factor and not the "inline".

`showPassword` values
Value	Description
`none`	The Advanced Identity Cloud/PingAM Login Widget does not render a way to reveal the password. This is the previous, pre-2.0 behavior.
`button`	Renders a button inside the password field that toggles visibility when clicked. This is the default.
`checkbox`	Renders a checkbox beneath the password field that toggles visibility when checked.

Add a header section

Enabling the header section separates the logo or branding from the journey form.

If you set header: true within the style/sections property, the modal uses a section with a separating line, and extra space:

Figure 3. Modal form factor with header enabled

By default, the separating section is not enabled:

Figure 4. Default modal form factor with header disabled

Set theme colors and fonts

In addition to rebuilding the Advanced Identity Cloud/PingAM Login Widget with a customized Tailwind configuration (refer to Theming the widget), you can override individual theme values at runtime using the style/theme configuration element. This is the quickest way to apply brand colors and fonts without cloning and rebuilding the widget.

Example theme configuration

await configure({
  wellknown: 'https://openam-forgerock-sdks.forgeblocks.com/am/oauth2/realms/root/realms/alpha/.well-known/openid-configuration',
  style: {
    theme: {
      primaryColor: '#f46200',
      secondaryColor: '#003049',
      backgroundColor: '#ffffff',
      linkColor: '#f46200',
      fontFamily: 'Inter, sans-serif',
      buttonBorderRadius: 8,
      cardBorderRadius: 12,
    },
  },
});

`theme` properties
Property	Description
`primaryColor`, `primaryOffColor`, `secondaryColor`	Hex color values (6 or 8 digit, for example `#f46200` or `#f46200ff`) for the widget’s primary and secondary brand colors.
`backgroundColor`	Hex color for the page or modal background.
`linkColor`, `linkActiveColor`	Hex colors for links in their default and active states.
`logo`, `favicon`	Full URLs (or base64 data URIs) to override the logo and favicon images.
`logoHeight`	Number of pixels for the logo height.
`fontFamily`	A font family string, for example `Inter, sans-serif`.
`buttonBorderRadius`, `cardBorderRadius`	Numbers, in pixels, controlling the corner rounding of buttons and cards.
`cardBgColor`, `cardTextColor`, `bodyTextColor`	Hex colors for card backgrounds and body text.
`inputBgColor`, `inputBorderColor`, `inputLabelColor`, `inputFocusRingColor`, `inputTextColor`	Hex colors for form input styling.
`selectAccentColor`, `selectHoverBgColor`	Hex colors for `<select>` elements.
`buttonFocusRingColor`, `buttonTextColor`	Hex colors for button focus and text states.

theme.logo accepts a single URL and is independent from style.logo, which accepts separate dark/light variants for the modal form factor. Use style.logo if you need different images per color scheme; use theme.logo for a single logo applied everywhere.

Journeys configuration options

Use the journeys configuration element to map HREF values rendered within the Advanced Identity Cloud/PingAM Login Widget to start a journey or authentication tree instead of visiting the URL.

Figure 5. Example HREF values in a page node

The Advanced Identity Cloud/PingAM Login Widget listens for click events on elements rendered within its container and compares the HREF to the configured mappings. If there is a match, it prevents the default action of visiting the URL and starts the journey configured in the mapping.

Mapping HREF strings to a journey

await configure({
  wellknown: 'https://openam-forgerock-sdks.forgeblocks.com/am/oauth2/realms/root/realms/alpha/.well-known/openid-configuration',
  journeys: {
    forgotPassword: {
      journey: 'ResetPassword', // Must match actual journey name in the server
      match: ['#/service/ResetPassword'], // Array of strings that match `HREF` values (case-sensitive)
    },
  },
});

The Advanced Identity Cloud/PingAM Login Widget has mappings configured internally to handle the links displayed in page nodes by default. These map the HREF values that are displayed by an out-of-the-box page node to corresponding journeys in an PingOne Advanced Identity Cloud tenant. You can override the mappings if required.

Default HREF strings to journey mappings

forgotPassword: {
    journey: 'ResetPassword',
    match: ['#/service/ResetPassword', '?journey=ResetPassword'],
},
forgotUsername: {
    journey: 'ForgottenUsername',
    match: ['#/service/ForgottenUsername', '?journey=ForgottenUsername'],
},
login: {
    journey: 'Login',
    match: ['#/service/Login', '?journey', '?journey=Login'],
},
register: {
    journey: 'Registration',
    match: ['#/service/Registration', '?journey=Registration'],
},

CAPTCHA configuration

AM does not signal invisible mode in the callback payload for either ReCaptchaCallback or ReCaptchaEnterpriseCallback. Use the captcha option to configure invisible rendering:

await configure({
  wellknown: 'https://openam-forgerock-sdks.forgeblocks.com/am/oauth2/realms/root/realms/alpha/.well-known/openid-configuration',
  captcha: {
    mode: 'invisible', // 'visible' (default) | 'invisible'
  },
});

Refer to Implement a CAPTCHA for more information.

Component

Use the component module for subscribing to modal and inline form factor events and for opening and controlling the modal form factor.

Call the component() method and assign the result to a variable to receive the observable. Subscribe to the observable to listen and react to the state of the Advanced Identity Cloud/PingAM Login Widget component.

import { component } from '@forgerock/login-widget';

// Initiate the component API
const componentEvents = component();

// Know when the component, both modal and inline has been mounted.
// When using the modal type, you will also receive open and close events.
// The property `reason` will be either "auto", "external", or "user"

const unsubComponentEvents = componentEvents.subscribe((event) => {
    /* Run anything you want */
});

// Open the modal
componentEvents.open();

// Close the modal
componentEvents.close();

// Recommended: call when your UI component is destroyed
unsubComponentEvents();

Schema for `component` events

The schema for component events is as follows:

Schema for component events

{
    lastAction: null, // null or the most recent action; one of `close`, `open`, or `mount`
    error: null, // null or object with `code` and `message` properties
    mounted: false, // boolean
    open: null, // boolean for the modal form factor, or null for inline form factor
    reason: null, // string to describe the reason for the event
}

Use the reason value to determine why the modal has closed.

The possible reason values are:

user: The user closed the dialog within the UI
auto: The modal was closed because the user successfully authenticated
external: The application called the close() function

Journey

Use the journey module to manage interaction with authentication and self-service journeys.

import { journey } from '@forgerock/login-widget';

// Call to start the journey
// Optional config can be passed in, see below for more details
const journeyEvents = journey({
  oauth: true, // OPTIONAL; defaults to true; uses OAuth flow for acquiring tokens
  user: true, // OPTIONAL; default to true; returns user information from `userinfo` endpoint
});

// Start a journey
journeyEvents.start({
  journey: 'Login', // OPTIONAL; specify the journey or tree you want to use
  query: {}, // OPTIONAL; additional query parameters to include when starting the journey
  resumeUrl: window.location.href, // OPTIONAL; the full URL for resuming a suspended journey
  recaptchaAction: 'myCaptchaTag', // OPTIONAL; tag reCAPTCHAs. Falls back to journey name.
});

// Change to a different journey
journeyEvents.change({
  journey: 'Registration',
});

// Subscribe to journey events
const unsubJourneyEvents = journeyEvents.subscribe((event) => {
  /* Run anything you want */
});

// Recommended: call when your UI component is destroyed
unsubJourneyEvents();

PingOne Protect risk evaluations are initialized separately via protect.start(), not through the journey() API.

Refer to Step 2. Configure the Advanced Identity Cloud/PingAM Login Widget for PingOne Protect.

Schema for `journey` events

The schema for journey events is as follows:

Schema for journey events

{
  journey: {
    completed: false, // boolean
    error: null, // null or object when the journey fails:
    // {
    //   code: null,         // number; HTTP status code, e.g. 401
    //   message: null,      // string; human-readable failure reason
    //   stage: null,        // string; page node stage value, if set
    //   troubleshoot: null, // always null; reserved for future use
    //   detail: null,       // object; extra detail from the server, e.g. { failureUrl: 'https://...' }
    // }
    loading: false, // boolean
    step: null, // null or object with the last step object from the server
    successful: false, // boolean
    response: null, // null or object if successful containing the success response from the server
  },
  oauth: {
    completed: false, // boolean
    error: null, // null or object with `code` (optional), `message`, and `troubleshoot` properties
    loading: false, // boolean
    successful: false, // boolean
    response: null, // null or object with OAuth/OIDC tokens
  },
  user: {
    completed: false, // boolean
    error: null, // null or object with `code` (optional), `message`, and `troubleshoot` properties
    loading: false, // boolean
    successful: false, // boolean
    response: null, // null or object with user information driven by OAuth scope config
  },
}

User

Use the user module to access methods for managing users:

user.info
user.tokens
user.logout

The user.info and user.tokens methods require use of OAuth 2.0, so you must configure oidcClient in your call to configure().

The user.info method also requires a scope value of openid, which is the default.

You can use user.logout with both OAuth 2.0 and session-based authentication.

import { user } from '@forgerock/login-widget';

/**
 * User info API
 */
const userEvents = user.info();

// Subscribe to user info changes
const unsubUserEvents = userEvents.subscribe((event) => {
  // Return current, *local*, user info and future state changes
  console.log(event);
});

// Fetch/get fresh user info from the server
userEvents.get(); // New state is returned in your `userEvents.subscribe` callback function

/**
 * User tokens API
 */
const tokenEvents = user.tokens();

// Subscribe to user token changes
const unsubTokenEvents = tokenEvents.subscribe((event) => {
  // Return current, *local*, user tokens and future state changes
  console.log(event);
});

// Return existing user tokens if available and not expired or about to expire
// Otherwise obtain fresh ones from the server
tokenEvents.get(); // State is returned in your `tokenEvents.subscribe` callback function

/**
 * Logout
 * Log user out and clear user data (info and tokens)
 */
user.logout(); // Resets user and emits event to your info and tokens' `.subscribe` callback function

// Recommended: call when your UI component is destroyed
unsubUserEvents();
unsubTokenEvents();

To force the Advanced Identity Cloud/PingAM Login Widget to obtain fresh tokens from the server rather than returning cached tokens:

tokenEvents.get({ forceRenew: true });

Schema for `user.info` events

The schema for user.info events is as follows:

Schema for user.info events

{
    completed: false, // boolean
    error: null,  // null or object with `code` (optional), `message`, and `troubleshoot` properties
    loading: false, // boolean
    successful: false, // boolean
    response: null, // object returned from the `/userinfo` endpoint
}

Schema for `user.tokens` events

The schema for user.tokens events is as follows:

Schema for user.tokens events

{
    completed: false, // boolean
    error: null,  // null or object with `code` (optional), `message`, and `troubleshoot` properties
    loading: false, // boolean
    successful: false, // boolean
    response: null, // object returned from the `/access_token` endpoint
}

Protect

Use the protect module to manually control the PingOne Signals SDK: starting data collection, returning collected data, and pausing or resuming behavioral data capture.

Refer to Step 2. Configure the Advanced Identity Cloud/PingAM Login Widget for PingOne Protect for full details and code examples.

Calling protected resources

The Advanced Identity Cloud/PingAM Login Widget does not provide an HTTP client for calling protected resources.

To call a protected endpoint, get the current access token from user.tokens().get() and call fetch() yourself, adding the Authorization header:

import { user } from '@forgerock/login-widget';

const tokenEvents = user.tokens();
const { response: tokens } = await tokenEvents.get();

const response = await fetch('https://protected.resource.com', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${tokens.accessToken}`,
  },
});

Earlier versions of the Advanced Identity Cloud/PingAM Login Widget exposed a request export that automatically refreshed tokens on a 401 response and parsed Identity Gateway policy advice. These behaviors are not provided by the Advanced Identity Cloud/PingAM Login Widget 2.0 and must be implemented by the consumer if needed.

Refer to Breaking changes for more information.

Advanced Identity Cloud/PingAM Login Widget