--- title: Breaking changes description: This page summarizes breaking changes to the Advanced Identity Cloud/PingAM Login Widget, and how to migrate an existing integration past each one. component: login-widget page_id: login-widget:release-notes:breaking canonical_url: https://developer.pingidentity.com/login-widget/release-notes/breaking.html llms_txt: https://developer.pingidentity.com/login-widget/llms.txt docs_for_agents: https://developer.pingidentity.com/build-with-ai/docs-for-agents.md revdate: Tue, 28 Jul 2026 00:00:00 +0000 keywords: ["Migration", "Breaking Changes", "Source Code", "SDK", "Login Widget"] section_ids: v2-0-0: Advanced Identity Cloud/PingAM Login Widget 2.0 summary_of_changes: Summary of changes migration_checklist: Migration checklist before_and_after: Before and after configuration: Configuration starting_a_journey_after_configuration: Starting a journey after configuration calling_a_protected_resource: Calling a protected resource custom_endpoint_paths: Custom endpoint paths removed_with_no_replacement: Removed with no replacement related_pages: Related pages --- # 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) ```javascript 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) ```javascript 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) ```javascript 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) ```javascript 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) ```javascript import { request } from '@forgerock/login-widget'; const response = await request({ init: { method: 'GET' }, url: 'https://protected.resource.com', }); ``` After (2.0) ```javascript 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](../login-widget/integrations/pingone-protect/02-configure-login-widget-for-protect.html). | ### Related pages * [Tutorial](../login-widget/tutorial.html) Updated for 2.0. * [API reference](../login-widget/widget-api-reference.html) Updated for 2.0. * [Login Widget changelog](changelogs/changelog_login_widget.html) The Advanced Identity Cloud/PingAM Login Widget 2.0 release entry.