Migrating Android apps to the Orchestration SDK

PingOne Advanced Identity Cloud PingAM Android

The Orchestration SDK for Android shifts from a callback-based asynchronous model to a modern, coroutine-based approach.

Legacy ForgeRock SDK for Android - Callbacks: The legacy ForgeRock SDK for Android uses NodeListener with methods such as onSuccess, onException, and onCallbackReceived.
New Orchestration SDKs for Android - Coroutines: The new Orchestration SDK for Android embraces Kotlin Coroutines.

Methods like start and next are suspend functions. This allows for writing asynchronous code in a sequential, synchronous-looking manner.

The different outcomes of an operation are handled by the sealed Node class, including ContinueNode, SuccessNode, ErrorNode, and FailureNode types, which allows for exhaustive when statements.

Data model translation

ForgeRock SDK Class Orchestration SDK Model Description

ForgeRock SDK Class	Orchestration SDK Model	Description
`FRSession`	`SuccessNode` and `Journey`	The `FRSession` object, which represented a successful login, is now represented by a `SuccessNode` returned by the journey. The `Journey` object itself holds the session state.
`Node`	`ContinueNode`	The `Node` object in the legacy ForgeRock SDK, which contained callbacks for user input, is now represented by `ContinueNode`.
`Exception` in `onException`	`ErrorNode` and `FailureNode`	Errors and exceptions are now handled through sealed classes `ErrorNode`, for API errors, and `FailureNode`, for exceptions.
`Callback`	`Callback`	The `Callback` classes are similar in both SDKs, but the new Orchestration SDK has a more structured approach to handling them within `ContinueNode`.
`FROptions`	`JourneyConfig`	The initialization options have been streamlined into a new `JourneyConfig` class, with a builder-style configuration.
`UserInfo`	`UserInfo`	The `UserInfo` model remains, but it is now retrieved synchronously or with coroutines.
`AccessToken`	`Token`	`FRListener` is replaced by a `Result` object.

FRSession

SuccessNode and Journey

The FRSession object, which represented a successful login, is now represented by a SuccessNode returned by the journey.

The Journey object itself holds the session state.

Node

ContinueNode

The Node object in the legacy ForgeRock SDK, which contained callbacks for user input, is now represented by ContinueNode.

Exception in onException

ErrorNode and FailureNode

Errors and exceptions are now handled through sealed classes ErrorNode, for API errors, and FailureNode, for exceptions.

Callback

The Callback classes are similar in both SDKs, but the new Orchestration SDK has a more structured approach to handling them within ContinueNode.

FROptions

JourneyConfig

The initialization options have been streamlined into a new JourneyConfig class, with a builder-style configuration.

UserInfo

The UserInfo model remains, but it is now retrieved synchronously or with coroutines.

AccessToken

Token

FRListener is replaced by a Result object.

Library 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 dependencies available in the new Orchestration SDK for Android:

Journey-related dependencies in the Android SDK
Library	Description
`android`	Core Android components for the SDK.
`binding`	Used for binding devices to user accounts.
`binding-ui`	UI components for device binding.
`browser`	Utilities for handling web-based authentication flows.
`commons`	Common classes for multi-factor authentication.
`device-client`	A client for device-related operations.
`device-id`	Provides a unique device identifier.
`device-profile`	Enables device profiling for risk assessment.
`device-root`	Detects if the device is rooted or jailbroken.
`journey`	Core library for handling authentication journeys.
`journey-plugin`	A plugin for extending journey functionality.
`logger`	A logging library for the SDK.
`migration`	Assists with migrating from older SDK versions.
`network`	Handles network requests for the SDK.
`oath`	Implements the OATH (Initiative for Open Authentication) standard.
`oidc`	Provides OpenID Connect (OIDC) functionality.
`orchestrate`	Handles the orchestration of journey nodes.
`protect`	Integrates with PingOne Protect for advanced fraud detection.
`push`	Manages push notifications for multi-factor authentication.
`storage`	Provides secure storage for SDK data.
`utils`	Common utility classes used across the SDK.

Code change examples

This section covers some of the code changes you will need to make to your ForgeRock SDK for Android apps to adopt the Orchestration SDK instead.

Navigating authentication journeys

ForgeRock SDK Orchestration SDK Parameter Changes Return Type

ForgeRock SDK	Orchestration SDK	Parameter Changes	Return Type
`FRSession.authenticate(context, journeyName, listener)`	`journey.start(journeyName)`	`context` is no longer passed directly to every method. `listener` is replaced by return value of the suspend function. Learn more in Starting an authentication journey on Android.	`void` (asynchronous with listener) → `Node` (synchronous-style with coroutines)
`node.next(context, listener)`	`continueNode.next()`	`context` is no longer passed directly. `listener` is replaced by return value of the suspend function. Learn more in Navigating an authentication journey on Android.	`void` (asynchronous with listener) → `Node` (synchronous-style with coroutines)
`NodeListener` callbacks	Sealed `Node` types	For example, ContinueNode, SuccessNode, ErrorNode, and FailureNode. Learn more in Navigating an authentication journey on Android.	N/A

FRSession.authenticate(context, journeyName, listener)

journey.start(journeyName)

context is no longer passed directly to every method.
listener is replaced by return value of the suspend function.

Learn more in Starting an authentication journey on Android.

void (asynchronous with listener) → Node (synchronous-style with coroutines)

node.next(context, listener)

continueNode.next()

context is no longer passed directly.
listener is replaced by return value of the suspend function.

Learn more in Navigating an authentication journey on Android.

void (asynchronous with listener) → Node (synchronous-style with coroutines)

NodeListener callbacks

Sealed Node types

For example, ContinueNode, SuccessNode, ErrorNode, and FailureNode.

Learn more in Navigating an authentication journey on Android.

N/A

Users and sessions

ForgeRock SDK Orchestration SDK Parameter Changes Return Type

ForgeRock SDK	Orchestration SDK	Parameter Changes	Return Type
`FRUser.getCurrentUser()?.logout()`	`journey.user()?.logout()`	The Orchestration SDK provides a nullable `user` object from the journey, on which logout can be called. Learn more in Signing users out.	`void` → `void`

FRUser.getCurrentUser()?.logout()

journey.user()?.logout()

The Orchestration SDK provides a nullable user object from the journey, on which logout can be called.

Learn more in Signing users out.

void → void

OpenID Connect

ForgeRock SDK Orchestration SDK Parameter Changes Return Type

ForgeRock SDK	Orchestration SDK	Parameter Changes	Return Type
`FRUser.getCurrentUser()?.accessToken`	`journey.user()?.token()`	`FRListener` is replaced by a `Result` object. Learn more in Managing OIDC tokens.	`void` (asynchronous with listener) → `Result<Token, OidcError>`
`FRUser.getCurrentUser()?.getUserInfo(...)`	`user.userinfo()`	`FRListener` is replaced by a `Result` object. Learn more in Managing OIDC tokens.	`void` (asynchronous with listener) → `Result<UserInfo, Exception>`
`FRUser.getCurrentUser()?.refreshAccessToken(...)`	`journey.user()?.refresh()`	`FRListener` is replaced by a `Result` object. Learn more in Managing OIDC tokens.	`void` (asynchronous with listener) → `Result<Token, OidcError>`
`FRUser.getCurrentUser()?.revokeAccessToken(...)`	`journey.user()?.revoke()`	`FRListener` is replaced by a suspend function. Learn more in Managing OIDC tokens.	`void` (asynchronous with listener) → suspend function

FRUser.getCurrentUser()?.accessToken

journey.user()?.token()

FRListener is replaced by a Result object.

Learn more in Managing OIDC tokens.

void (asynchronous with listener) → Result<Token, OidcError>

FRUser.getCurrentUser()?.getUserInfo(...)

user.userinfo()

FRListener is replaced by a Result object.

Learn more in Managing OIDC tokens.

void (asynchronous with listener) → Result<UserInfo, Exception>

FRUser.getCurrentUser()?.refreshAccessToken(...)

journey.user()?.refresh()

FRListener is replaced by a Result object.

Learn more in Managing OIDC tokens.

void (asynchronous with listener) → Result<Token, OidcError>

FRUser.getCurrentUser()?.revokeAccessToken(...)

journey.user()?.revoke()

FRListener is replaced by a suspend function.

Learn more in Managing OIDC tokens.

void (asynchronous with listener) → suspend function

Error handling

ForgeRock SDK Orchestration SDK Parameter Changes Return Type

ForgeRock SDK	Orchestration SDK	Parameter Changes	Return Type
`onException(e)` callback	`is ErrorNode` or `is FailureNode`	Explicit error type discrimination Learn more in Handling FailureNode and ErrorNode.	N/A

onException(e) callback

is ErrorNode or is FailureNode

Explicit error type discrimination

Learn more in Handling FailureNode and ErrorNode.

N/A

Migrating using AI assistants

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

This file contains a detailed mapping 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 Android.

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