Advanced Identity Cloud/PingAM Login Widget

Breaking changes

This page summarizes breaking changes to the Advanced Identity Cloud/PingAM Login Widget, and how to migrate an existing integration past each one.

Advanced Identity Cloud/PingAM Login Widget 2.0

Advanced Identity Cloud/PingAM Login Widget 2.0 introduces breaking changes to configuration, module dependencies, and the public API. This section summarizes what changed, why it changed, and how to migrate an existing 1.x integration.

Summary of changes

  • Configuration is now driven by a single async configure() function; the synchronous configuration() + .set() pattern is removed.

  • Endpoint discovery is now driven by a single top-level wellknown URL that is shared by the journey and OIDC clients.

  • The nested forgerock config object is replaced by a flat, top-level shape with an oidcClient sub-object.

  • The request export, an alias to the legacy HttpClient.request, is removed.

  • Underlying dependencies have moved: OAuth/OIDC is now backed by @forgerock/oidc-client, PingOne Protect is backed by @forgerock/protect, and @forgerock/javascript-sdk is no longer a dependency of the widget.

Migration checklist

  1. Rename the configuration import to configure.

  2. Replace calls to configuration() and .set() with a single await configure({…​}).

  3. Move endpoint discovery to a top-level wellknown URL. Remove serverConfig, baseUrl, timeout, realmPath, tree, and any serverConfig.paths overrides.

  4. Wrap clientId, redirectUri, and scope in a new oidcClient sub-object. Add the oidcClient sub-object if you use OAuth/OIDC tokens, user info, or logout.

  5. Remove any calls to the request export. Fetch tokens from user.tokens().get() and call fetch yourself.

  6. Remove any of the following that appear in your configuration. They have no replacement: oauthThreshold, tokenStore, prefix, logLevel, logger, platformHeader.

  7. await the returned promise before calling any other Widget API. journey().start(), user.info().get(), and user.tokens().get() all fail if called before configure() resolves.

Before and after

Configuration

Before (1.x)
import Widget, { configuration } from '@forgerock/login-widget';

const myConfig = configuration();

myConfig.set({
  forgerock: {
    serverConfig: {
      baseUrl: 'https://openam-forgerock-sdks.forgeblocks.com/am/',
      timeout: 3000,
    },
    clientId: '{edit_client_public}',
    realmPath: 'alpha',
    redirectUri: window.location.href,
    scope: '{edit_scopes}',
  },
});
After (2.0)
import '@forgerock/login-widget/widget.css';
import Widget, { configure } from '@forgerock/login-widget';

// configure() is async, so await it before any other Widget API
await configure({
  wellknown: 'https://openam-forgerock-sdks.forgeblocks.com/am/oauth2/realms/root/realms/alpha/.well-known/openid-configuration',
  oidcClient: {
    clientId: 'sdkPublicClient',
    redirectUri: `${window.location.origin}/callback`,
    scope: 'openid profile email address',
  },
});

Starting a journey after configuration

Before (1.x)
import Widget, { configuration, journey } from '@forgerock/login-widget';

const myConfig = configuration();
myConfig.set({ forgerock: { /* ... */ } });

new Widget({ target: document.getElementById('widget-root') });

const journeyEvents = journey();
journeyEvents.start();
After (2.0)
import Widget, { configure, journey } from '@forgerock/login-widget';

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

new Widget({ target: document.getElementById('widget-root') });

journey().start();

Calling a protected resource

Before (1.x)
import { request } from '@forgerock/login-widget';

const response = await request({
  init: { method: 'GET' },
  url: 'https://protected.resource.com',
});
After (2.0)
import { user } from '@forgerock/login-widget';

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

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

The legacy request alias automatically refreshed the access token on a 401 response and parsed Identity Gateway policy advice.

Neither behavior is provided by the Advanced Identity Cloud/PingAM Login Widget 2.0 or @forgerock/oidc-client.

If your app depends on these, you must implement them at the consumer level.

Custom endpoint paths

The following properties are all removed in 2.0. Every endpoint is now discovered from wellknown.

  • serverConfig.paths.authenticate

  • serverConfig.paths.authorize

  • serverConfig.paths.accessToken

  • serverConfig.paths.revoke

  • serverConfig.paths.userInfo

  • serverConfig.paths.sessions

  • serverConfig.paths.endSession

If your deployment does not expose a standard .well-known/openid-configuration document, you must add one before upgrading to 2.0.

Removed with no replacement

The following configuration properties existed in 1.x and are removed in 2.0. None have direct replacements in the widget configuration.

Property Notes

request (module export)

Use user.tokens().get() plus a manual fetch call.

serverConfig (nested object)

Endpoints are discovered from wellknown; baseUrl and timeout are gone.

serverConfig.paths.*

All seven per-endpoint overrides are gone.

realmPath, tree

The realm is encoded in the wellknown URL path.

The tree option was inherited from the Ping Orchestration SDK for JavaScript and is not a widget concept.

oauthThreshold

Managed internally by @forgerock/oidc-client.

tokenStore, prefix

Token storage is managed internally by @forgerock/oidc-client.

logLevel, logger

Not currently configurable in the widget.

platformHeader

Not currently configurable in the widget.

pingProtect (as a journey().start() parameter)

Initialize PingOne Signals separately via protect.start().

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

Updated for 2.0.

API reference

Updated for 2.0.

Login Widget changelog

The Advanced Identity Cloud/PingAM Login Widget 2.0 release entry.