Ping SDKs

The Ping SDKs can leverage authentication journeys. Use the SDKs to easily step through each stage of an authentication tree by using callbacks.

For more information, refer to Supported callbacks.

For example, let’s say you want to use this authentication flow:

You can use the SDK to make each callback call the next step in the tree. You don’t have to traverse the REST APIs to call the next step.

The Ping SDKs empower developers to build applications that can handle the changes to your authentication journeys in real time, without having to redeploy your app.

The Ping SDKs use the OAuth 2.0 auth code flow, and support PKCE.

This method is the best practice for first-party applications. The SDK automatically handles token exchange for you, and also securely stores the tokens. Token refresh is automatically handled by the SDK, so you don’t have to think about it.

The Ping SDKs also support obtaining OAuth 2.0 tokens from a PingOne or PingFederate server. To learn more, refer to the tutorials.

In some scenarios, your company may have multiple native applications that customers have installed on their devices. You can use the SDK to seamlessly sign users in to multiple applications on a device. When the customer signs in to one application, they are automatically signed in to a second application on that device—​without having to authenticate again.

The Ping SDKs can help you integrate push authentication or one-time password (OTP) capabilities into your mobile applications so your end users don’t have to download and use a dedicated Authenticator application. The SDK’s Authenticator module can support:

The SDK has a modular architecture and is designed with flexibility in mind. Don’t want to use our method for jailbreak detection? No problem! Just plug in your own method, or use any 3rd-party plug-in instead.

Using the SDK, you have the option to collect device profile information to use in your authentication flows. You might use this data to compare a user sign-in to a prior sign-in event. If the device profile has changed too much from the prior event, you can deny the sign-in.

Detecting whether a device is jailbroken or rooted assures developers that a device is managed by the authorized device owner. Jailbroken devices may be running outdated OS versions, or could be missing security patches. Detecting whether a device is jailbroken can provide valuable insight into the security posture of a device. You can feed that insight into authentication flows.

The iOS and Android SDKs generate a score to determine if a device is jailbroken or rooted. There are a number of factors that go into creating this score. The score ranges from 0 to 1.0, where 1 indicates the device is an emulator.

You can use this information as part of an authentication flow to ask the user for another factor, or to deny access entirely.

Ping SDKs can automatically generate a device ID for you. You can use the ID with PingIDM or PingAM to allow your users to manage their devices.

For example, you can insert the device ID and associated data into a user’s profile. This lets them view their devices and set the devices as trusted. You can also decide to use a recognized device in an authentication flow to avoid asking a user for another factor.

You can collect latitude and longitude information from your users via the Android and iOS SDKs. Apps that use location services must request location permissions from users.

The Ping SDKs have a sample user interface that can be used for rapid prototyping, or as a reference implementation for building your own UI. Let’s say you want to get an authentication experience in front of some of your users or business stakeholders. You can easily build an authentication journey and display the results immediately in your application.

The Ping SDK for JavaScript supports web biometrics functionality provided by PingAM.

Web biometrics lets users authenticate by using an authenticator device; for example, the fingerprint scanner on their laptop or phone, or a USB key such as those provided by Yubico, or Google’s Titan security keys.

Communication with authentication devices is handled by the SDK. PingAM requests that the SDK activates authenticators with certain criteria; for example, it must be built-in to the platform, or is a cross-platform roaming USB device. You can also specify that the device must verify the identity of the user, rather than simply that a user is present.

The Ping SDKs have two methods for handling web biometrics: one for registering devices, and another for authenticating using a registered device.

For more information, refer to Web biometrics.

Mobile biometric authentication lets users authenticate by using a mobile device’s biometric authentication. Communication with the platform authenticator, for example, with a fingerprint reader or facial recognition system, is handled by the Ping SDK.

The Ping SDK communicates with PingAM to perform biometric registration and authentication using the WebAuthn nodes. Similar to WebAuthn with the Ping SDK for JavaScript, you can configure the nodes in PingAM to request that the SDK activates authenticators with certain criteria.

The Ping SDKs enable passkey support on supported platforms. Passkeys can be synchronized across a user’s devices and browsers, simplifying device registration and enabling passwordless flows.

This feature is available in the ForgeRock SDK for Android 3.0 and the ForgeRock SDK for iOS v3.0 or later. It requires PingOne Advanced Identity Cloud, or PingAM 7.1 or later.

For more information, refer to What are mobile biometrics?.

You can authenticate by using a trusted Identity Provider (IdP), like Apple, Facebook, Google, and many others. These IdPs are used for authentication and identity verification. This is often referred to as Social Login or Social Authentication. These IdPs return the necessary information to integrate user information into your user’s profile.

Depending on the device platform (Android, Web or iOS), the user is redirected from the current web application or login page to the IdP’s authorization server. Or, if on a native mobile app, the user is directed to the IdP’s authentication SDK, if available. Once on the IdP via a web page or SDK, the user will authenticate and provide the necessary consent required for sharing the information. When complete, the user is redirected back to your app or to your server to complete the authentication journey.

For more information, refer to Set up social login.

For instructions on enabling centralized login, refer to Use centralized login.

For instructions on enabling embedded login, follow the JavaScript tutorials.

Depending on the authentication use case, the SDKs will potentially have to store and be able to retrieve the session cookie, ID tokens, access tokens, and refresh tokens.

Each token is serving a different use case, and as such how the SDKs handle them can be different.

The following sections cover how the SDKs handle different types of tokens.

The session and OAuth 2.0-related tokens the SDKs handle all have associated expiry times. When a token reaches its expiry time it becomes unusable.

A feature of the SDKs is that they manage the refresh of OAuth 2.0 tokens. The timing of the refresh is based on a threshold value to improve the end-user experience. The SDKs refresh tokens automatically when the token is requested from storage to be used in your application and its expiry is within the threshold.

In the case of access tokens, if a refresh token is present, then the Android and iOS SDKs will use it to obtain a new access token. If the refresh token cannot be used, is not present, or if it has expired, then the SDKs fall back to using the session token to start a new OAuth 2.0 flow.

When an OAuth 2.0 or session token expires, the SDK removes any respective tokens from the secure storage and performs a cleanup. The Android and iOS SDKs also check if the current session token is the same one used to obtain the OAuth 2.0 tokens. In case of a mismatch, then these orphaned tokens are cleaned.

When using SDK logout methods to perform a Logout event, the SDKs revoke existing OAuth 2.0 tokens, revoke the session, and perform a local cleanup. If the SDKs are unable to revoke the session at the server—​for example the network is unavailable—​then the SDKs remove the tokens from local storage.

When using the Ping SDK for JavaScript, if an access token expires within the threshold limit or returns an HTTP 401 Unauthorized error, the SDK attempts to renew it using the same session cookie that was performing the authorization code flows.

The Ping SDK for JavaScript calls the endSession and session?action=logout endpoints during logout, as well as calling revoke whenever you use FRUser.logout. This ensures that the server invalidates the session cookie.

On supported platforms and devices, the Ping SDKs generate Hardware-Backed encryption keys, and uses them to encrypt and store tokens. This provides an extra level of security against attacks.

Your app, with the help of our code, generates a code_verifier (nonce). When a user make a request, your app creates a hash of that code_verifier as a code_challenge. ForgeRock, as an authorization server, saves the hash value.

After the hash is confirmed as valid, your app exchanges its authorization code grant for an access token. Your client app, as the bearer, can use the token to access to the user’s resources.

This diagram depicts the authorization code grant flow in detail:

If you’re familiar with OpenID Connect (OIDC) specifications, the web app is the relying party, and PingOne Advanced Identity Cloud or PingAM is the authorization server.

For more information on PKCE standards, see the following IETF document: Proof key for code exchange by OAuth public clients.

For more information on how we implement PKCE for native and SPA apps, refer to Authorization code grant with PKCE.

To register a public OAuth 2.0 client application for use with the SDKs in PingOne Advanced Identity Cloud, follow these steps:

The application is now configured to accept client connections from and issue OAuth 2.0 tokens to the example applications and tutorials covered by this documentation.

The following tutorials and integrations require a confidential client:

To register a confidential OAuth 2.0 client application for use with the SDKs in PingOne Advanced Identity Cloud, follow these steps:

To register a public OAuth 2.0 client application for use with the SDKs in AM, follow these steps:

The following tutorials and integrations require a confidential client:

To register a confidential OAuth 2.0 client application for use with the SDKs in AM, follow these steps:

For more information on resources in PingOne, refer to Adding a custom resource.

To register a public OAuth 2.0 client application in PingOne for use with the Ping SDK for JavaScript, follow these steps:

The application is now configured to accept client connections from and issue OAuth 2.0 tokens to the JavaScript example PingOne applications and tutorials covered by this documentation.

To register a public OAuth 2.0 client application in PingOne for use with the Ping SDKs for Android and iOS, follow these steps:

The application is now configured to accept client connections from and issue OAuth 2.0 tokens to the Android and iOS PingOne example applications and tutorials covered by this documentation.

You can now configure the Ping SDKs to connect to PingOne and obtain OAuth 2.0 access tokens.

You will need some of the property values from the client profile you created to configure the SDKs:

When you have obtained these values from your PingOne instance, continue to the tutorials:

For more information on applications in PingOne, refer to Adding an application.

You can now configure the Ping SDKs to connect to PingFederate and obtain OAuth 2.0 access tokens:

For more information on applications in PingFederate, refer to Managing OAuth clients.

Configure SDK properties in your Android app by editing the strings.xml file, located in app/src/main/res/values.

Configure SDK properties in your iOS app by editing the FRAuthConfig.plist file.

Configure SDK properties in your JavaScript app by editing a serverConfig object, a parameter of the forgerock.Config.set() function.

The SDK revokes and removes persisted tokens if you change any of the following properties dynamically:

The following examples use dynamic configuration.

When the application calls FRAuth.start(), the FRAuth class checks for the presence of an FROptions object. If the object is not present, static initialization from strings.xml happens. If the object is present, the FRAuth class uses the options object and calls the same internal initialization method.

The app can call FRAuth.start() multiple times in its lifecycle:

The following Swift example uses dynamic configuration.

When the application calls FRAuth.start(), the FRAuth class checks for the presence of an FROptions object. If the object is not present, the static initialization from FRAuthConfig.plist happens. If the object is present, the FRAuth class converts it to a [String, Any] dictionary and calls the same internal initialization method.

The app can call FRAuth.start() multiple times in its lifecycle:

You can configure the Android and iOS SDKs to obtain many required settings from your PingOne server’s .well-known OpenID Connect endpoint. Settings gathered from the endpoint include the paths to use for OAuth 2.0 authorization requests, and login endpoints.

To enable SSL pinning you need a hash of your server’s public key. You can use the openssl tool to extract this from your server’s SSL certificate and create the hash value.

In the following command, replace <tenant-env-fqdn> with the fully-qualified domain name of your server, for example, my-company.forgeblocks.com:

The command outputs a hash of the public key extracted from the certificate:

S4kZuhQQ1DPcXBSWFQXD0gG+UW7usdbVx6roNWpRl65I=

Use this value in the next steps to configure SSL pinning.

To enable SSL pinning in the Ping SDK for Android, add the hash of the public keys for any PingAM authorization servers your application will contact to your app’s configuration.

Add the hashes to an array named forgerock_ssl_pinning_public_key_hashes in your strings.xml file:

If the public key you use to obtain SSL certificates for the PingAM servers change, update the strings.xml file with the new hash and re-release your app.

To enable SSL pinning in the Ping SDK for iOS, add the hash of the public keys for any PingAM authorization servers your application will contact to your app’s configuration.

Add the hashes to an array named forgerock_ssl_pinning_public_key_hashes in your FRAuthConfig.plist file:

If the public key you use to obtain SSL certificates for the PingAM servers change, update the FRAuthConfig.plist file with the new hash and re-release your app.

Each SDK provides an interface that you can use to customize requests:

Request interceptors have two inputs:

This section covers how to develop request interceptors, referred to as "middleware" in the Ping SDK for JavaScript, and apply them to outbound requests from your applications.

The Ping SDK for Android does all of its logging through a custom interface called FRLogger. The default implementation of this interface logs the messages through the native Android Log class. This displays messages from the SDK in real-time in the Logcat window in Android Studio.

The log severity levels defined in the Ping SDK for Android are as follows:

The Ping SDK for Android allows developers to customize the default logger behavior:

The Ping SDK for iOS does all of its logging through a custom protocol called FRLogger. The default implementation of the FRLogger protocol logs the messages through the native iOS FRConsoleLogger class. This displays messages from the SDK in real-time in the console window in Xcode.

Each log message has an associated log level that describes the type and the severity of the message. Log levels are helpful tool for tracking and analyzing events that take place in your app.

The log severity levels defined in the Ping SDK for iOS are as follows:

The Ping SDK for iOS lets developers customize the default logger behavior:

The Ping SDK for JavaScript performs logging through the native console class. This displays messages from the SDK in real-time in the console window provided in many browsers.

The default logLevel is none, which prevents the Ping SDK for JavaScript from logging any messages to the console.

To enable the output of log messages from the Ping SDK for JavaScript, specify a logLevel value other than none.

For example, use the following code to specify the debug level:

The log severity levels defined in the Ping SDK for JavaScript are as follows:

For more information on configuring the Ping SDK for JavaScript, refer to Ping SDK for JavaScript Properties

The Ping SDK for JavaScript allows developers to customize the default logger behavior. For example, you might want to redirect the logs to an external service.

You can configure your Android apps to use customized storage for these types of data:

Before starting the tutorials, complete these prerequisite tasks.

There are three tutorials available for Android, depending on your server environment:

The Ping SDK for Android requires at least Java 8 (v1.8).

Configure compile options in your project to use this version of Java, or later:

To use the Ping SDK for Android, add the relevant dependencies to your project:

If you are not using the PingOne Advanced Identity Cloud but rather a local PingAM server that does not use the HTTPS protocol, you can edit your project manifest file to allow cleartext connections.

If you intend for your application to use any of the Android location services; for example, the SDK’s location matching or geofencing features, add one of the relevant properties to the project manifest file

The following shows an example AndroidManifest.xml file with support for cleartext traffic and fine location access enabled:

In Android Studio, select Run > Run 'app'.

Android Studio builds the application and runs it in the default emulator.

As you have not yet added any UI, the app displays only "Hello World!".

You have now configured your Android app development environment, created a new project, and configured it with the required dependencies and build options.

In the next step, you configure your application with the settings it needs to connect to your PingOne Advanced Identity Cloud or PingAM instance.

You have now configured your application with the settings it needs to connect to your PingOne Advanced Identity Cloud or PingAM instance.

In the next step, you add debug logging and initialize the SDK.

You have now added debug logging to your app and initialized the SDK.

If you get errors when running the app, check the app > res > values > strings.xml has the correct values. Refer to Step 2. Configure connection strings.

In the next step, you create the initial user interface to display the current authentication status, and add buttons to log in and log out.

In Android Studio, select Run > Run 'app'.

If everything is configured correctly, the app builds, and the default emulator runs the application.

The app shows the Log in and Log out buttons, as well as a text view element that displays User is not authenticated:

In the next step, you create and attach functions to the buttons to start the authentication journey, or begin the logout process.

In the next step, you add a UI fragment to obtain credentials from the user, and code to open that fragment when the callback is received.

You also add code to populate the callback with the credentials and return it to the server, completing the authentication journey.

You have now completed the quick start application.

You added a UI fragment to obtain credentials from the user, and code to open that fragment when the callback is received.

You also added code to populate the callback with the credentials and return it to the server, completing the authentication journey.

In the next step, you test the application by authenticating a user, checking the logs, and then logging out.

You have successfully completed the tutorial.

Before starting the tutorials, complete these prerequisite tasks.

There are three tutorials available for iOS, depending on your server environment: