Orchestration SDKs

Migrating JavaScript apps to the Orchestration SDK

PingOne Advanced Identity Cloud PingAM JavaScript

The new Orchestration SDK for JavaScript aims to provide a more modern, efficient, and developer-friendly experience than the legacy ForgeRock SDK.

Some of the shifts in methodology are outlined below:

Async-first initialization

Orchestration SDK clients are initialized asynchronously with factory functions, including journey() and oidc().

Instance-based APIs

Methods are called on client instances, not static classes.

Modularized packages

A significant breakdown into smaller, specialized modules, including clients for Journeys (@forgerock/journey-client), OIDC (@forgerock/oidc-client), Device management (@forgerock/device-client), and PingOne Protect (@forgerock/protect), and more.

Explicit error handling

Response objects contain an { error } property, instead of throwing exceptions.

Well-known endpoint discovery

Only serverConfig.wellknown is required. All paths are derived automatically from the response.

Removed the built-in HTTP client

Choose how your app makes protected API requests, with manual token retrieval and header management.

Config is now fixed at creation

Per-call config overrides have been removed; you’ll now create separate client instances for different environments or configurations.

Package dependency changes

The modular architecture of the Orchestration SDKs means you only have to import the functionality you require in your apps.

The table below shows the packages available in the new Orchestration SDK for JavaScript:

Journey-related dependencies in the JavaScript SDK
ForgeRock SDK Orchestration SDK Description

@forgerock/javascript-sdk

@forgerock/journey-client

Navigating authentication journeys.

@forgerock/javascript-sdk

@forgerock/oidc-client

OAuth 2.0 and OIDC token management, user info, and logout.

@forgerock/javascript-sdk

@forgerock/sdk-types

Shared types and enums.

@forgerock/javascript-sdk

@forgerock/device-client

Device profiling and management, including OATH, Push, WebAuthn, Binding, and Profiling.

@forgerock/ping-protect

@forgerock/protect

PingOne Protect (Signals) integration.

Code change examples

Initialization and configuration

The legacy ForgeRock SDK uses a global static Config.set(). The new Orchestration SDK for JavaScript uses asynchronous factory functions, each returning an independent client instance.

ForgeRock SDK Orchestration SDK Notes

import { Config } from '@forgerock/javascript-sdk'

import { journey } from '@forgerock/journey-client'

Journey client factory.

Learn more in Installing the Journey module in JavaScript.

N/A

import { oidc } from '@forgerock/oidc-client'

OIDC client factory is now a separate package

Config.set({ clientId, redirectUri, scope, serverConfig, realmPath, tree })

const journeyClient = await journey({ config })

Initialize asynchronously, with config being per-client, not global.

Learn more in Configuring the Journey module in JavaScript.

Authentication and Journeys

ForgeRock SDK Orchestration SDK Notes

FRAuth.start({ tree: 'Login' })

journeyClient.start({ journey: 'Login' })

Journey name is now passed per-call by using the journey parameter, not in the client config.

Learn more in Starting an authentication journey in JavaScript.

FRAuth.next(step, { tree: 'Login' })

journeyClient.next(step)

No need to repeat the journey config inside next().

Learn more in Navigating an authentication journey in JavaScript

N/A

await journeyClient.terminate()

Ends the session by using the /sessions endpoint.

Learn more in Signing users out.

Token management and OAuth 2.0 flows

ForgeRock SDK Orchestration SDK Notes

TokenStorage.get()

const tokens = await oidcClient.token.get()

Now part of oidcClient. Auto-retrieves from storage.

Check errors with if ('error' in tokens)

Learn more in Managing OIDC tokens.

TokenManager.getTokens({ forceRenew: true })

await oidcClient.token.get({ forceRenew: true, backgroundRenew: true })

Now a single call, with auto-renewal.

Returns tokens or an error.

Learn more in Managing OIDC tokens.

  1. TokenManager.getTokens()

  2. Manual code and state

  1. await oidcClient.authorize.background()

  2. await oidcClient.token.exchange(code, state)

Now uses a two-step process to authorize, when you need explicit control.

Learn more in Managing OIDC tokens.

TokenManager.deleteTokens()

await oidcClient.token.revoke()

Revokes tokens remotely and deletes locally.

Learn more in Managing OIDC tokens.

TokenStorage.set(tokens)

Handled automatically by oidcClient.token.exchange()

Tokens are now automatically stored after exchange.

TokenStorage.remove()

await oidcClient.token.revoke()

Now a combined revoke and delete.

Learn more in Managing OIDC tokens.

Migrating using AI assistants

To help you migrate applications from the legacy ForgeRock SDK for JavaScript to the new Orchestration SDK for JavaScript using an AI assistant, we have created a MIGRATION.md file, and an interface_mapping.md file.

These file contain detailed mappings and example snippets of changes between the two SDK versions, which AI assistants can utilize to help you migrate your app.

MIGRATION.md

View and download the ForgeRock SDK to Orchestration SDK MIGRATION.md file for JavaScript.
interface_mapping.md

View and download the ForgeRock SDK to Orchestration SDK interface_mapping.md file for JavaScript.

This approach is designed to reduce manual effort and improve consistency during the migration process.