Orchestration SDKs

Migrating iOS apps to the Orchestration SDK

PingOne Advanced Identity Cloud PingAM iOS

The migration from the legacy ForgeRock SDK for iOS, which uses the FRAuth module, to the modern Orchestration SDK for iOS, represents a fundamental architectural shift towards modern Swift concurrency and modularity.

The Orchestration SDK for iOS fully embraces async/await patterns, replacing traditional callback-based completion handlers for asynchronous operations.

High-level changes

Modular Architecture

A significant breakdown into smaller, specialized modules including, PingJourney, PingOidc, PingDeviceProfile, and PingFido, and more, that allows developers to include only the necessary components, reducing app size and complexity.

Declarative Configuration

Orchestration SDK initialization and module configuration is now handled declaratively using closures, offering a more flexible and readable setup.

Workflow-Centric Design

The Orchestration SDK now explicitly models authentication and orchestration flows using a workflow pattern with distinct node states, such as ContinueNode, SuccessNode, FailureNode, and ErrorNode.

This provides clearer control over the user journey.

Concurrency Model

A complete transition to Swift’s native async/await for all network and asynchronous operations, simplifying code and improving readability.

Enhanced Type Safety

Callback properties are now strongly typed and accessed directly, for instance using specific callback.name or callback.password, instead of the generic callback.setValue(), which improves code reliability.

Updated Minimum Requirements

The SDK requires iOS 16.0+ and Swift 6.0+, leveraging newer platform capabilities.

Overall, the new Orchestration SDK aims to provide a more modern, efficient, and developer-friendly experience by aligning with contemporary Swift development practices.

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 dependency names from the old ForgeRock SDK, and the dependencies available in the new Orchestration SDK for iOS:

Journey-related dependencies for iOS SDKs
ForgeRock SDK Orchestration SDK 
import FRAuth
import FRCore
import FRAuthenticator
import FRDeviceBinding
import FRProximity
import FRGoogleSignIn
import FRFacebookSignIn
import PingProtect
import FRCaptchaEnterprise
 
import PingOrchestrate
import PingJourney
import PingOidc
import PingDeviceProfile
import PingDeviceClient
import PingDeviceId
import PingBinding
import PingOath
import PingPush
import PingFido
import PingExternalIdP
import PingExternalIdPApple
import PingExternalIdPGoogle
import PingExternalIdPFacebook
import PingProtect
import PingReCaptchaEnterprise

Code change examples

The following table covers some of the code changes you will need to make to your ForgeRock SDK for iOS apps to adopt the Orchestration SDK instead.

ForgeRock SDK Orchestration SDK Details

FRAuth.start(options:)

Journey.createJourney { config in ... }

Use declarative configuration when creating a journey instance.

Learn more in Configuring the Journey module on iOS.

FRUser.login()

FRSession.authenticate()

journey.start()

Use start() to begin a journey, which now returns explicit node types.

Learn more in Starting an authentication journey on iOS.

Node.next()

await node.next()

Traverse a journey using async and await, instead of callbacks.

Learn more in Navigating an authentication journey on iOS.

Node

ContinueNode

Changed the class to be more specific.

Learn more in Handling ContinueNode.

Users and sessions

ForgeRock SDK Orchestration SDK Details

FRUser.currentUser

await journey.journeyUser()

Access properties asynchronously.

Learn more in Getting a user object and session token.

Journey node callback handling

ForgeRock SDK Orchestration SDK Details

callback.setValue(value)

callback.name

callback.password

callback.selectedIndex

Different callbacks now have specific properties.

WebAuthnRegistrationCallback

FidoRegistrationCallback

Renamed for clarity.

WebAuthnAuthenticationCallback

FidoAuthenticationCallback

Renamed for clarity.

SelectIdPCallback

SelectIdpCallback

Case changed.

Error handling

ForgeRock SDK Orchestration SDK Details

N/A (used Error object)

failureNode.cause

New property for failure handling.

Learn more in Handling FailureNode and ErrorNode.

N/A (used Error object)

errorNode.message

New property for error handling.

Learn more in Handling FailureNode and ErrorNode.

Migrating using AI assistants

To help you migrate applications from the legacy ForgeRock SDK for iOS to the new Orchestration SDK for iOS 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 iOS.

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