Ping SDKs

Configure the Ping SDKs

Applies to:

  • Ping SDK for Android

  • Ping SDK for iOS

  • Ping SDK for JavaScript

You need to configure certain settings in the SDKs so they can connect to your authorization server to authenticate your users and obtain tokens.

The method you use to configure these settings depends on which SDK you are using.

Ping SDK for Android

Configure the Ping SDK for Android
Ping SDK for iOS

Configure the Ping SDK for iOS
Ping SDK for JavaScript

Configure the Ping SDK for JavaScript

Ping SDK for Android configuration

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

Server properties

Property Description

forgerock_url

The base URL of the server to connect to, including port and deployment path.

Identity Cloud example:

https://openam-forgerock-sdks.forgeblocks.com/am

Self-hosted example:

https://openam.example.com:8443/openam

forgerock_realm

The realm in which the OAuth 2.0 client profile and authentication journeys are configured.

For example, alpha.

Defaults to the self-hosted top-level realm root.

forgerock_timeout

A timeout, in seconds, for each request that communicates with your server.

forgerock_cookie_name

The name of the cookie that contains the session token.

For example, with a self-hosted PingAM server this value might be iPlanetDirectoryPro.

PingOne Advanced Identity Cloud tenants use a random alpha-numeric string.

To locate the cookie name in an PingOne Advanced Identity Cloud tenant, navigate to Tenant settings > Global Settings, and copy the value of the Cookie property.

Journey properties

Property Description

forgerock_auth_service

The name of a user authentication tree configured in your server.

For example, sdkUsernamePasswordJourney.

forgerock_registration_service

The name of a user registration tree configured in your server.

For example, sdkRegistrationJourney.

OAuth 2.0 properties

Property Description

forgerock_oauth_client_id

The client_id of the OAuth 2.0 client profile to use.

For example, sdkPublicClient.

forgerock_oauth_redirect_uri

The redirect_uri as configured in the OAuth 2.0 client profile.

This value must match a value configured in your OAuth 2.0 client, but is not actually used by the Android application.

For example, https://sdkapp.example.com:8443/callback.

forgerock_oauth_sign_out_redirect_uri

The URI to redirect users to after they sign out and revoke their OAuth 2.0 tokens.

For example, com.forgerock.app://oauth2redirect.

forgerock_oauth_scope

A list of scopes to request when performing an OAuth 2.0 authorization flow, separated by spaces.

For example, openid profile email address.

forgerock_oauth_threshold

A threshold, in seconds, to refresh an OAuth 2.0 token before the access_token expires.

Defaults to 30 seconds.

SSL pinning properties

Property Description

forgerock_ssl_pinning_public_key_hashes

An array of public key certificate hashes (strings) for trusted sites and services.

buildSteps

An array of BuildStep objects to provide additional SSL pinning parameters to OkHttpClient instances.

Custom endpoint properties

Property Description

forgerock_authenticate_endpoint

Override the default path to your server’s /json/authenticate endpoint.
Default: /json/realms/{forgerock_realm}/authenticate

forgerock_authorize_endpoint

Override the default path to the PingAM’s /oauth2/authorize endpoint.
Default: /oauth2/realms/{forgerock_realm}/authorize

forgerock_token_endpoint

Override the default path to your server’s /oauth2/access_token endpoint.
Default: /oauth2/realms/{forgerock_realm}/access_token

forgerock_revoke_endpoint

Override the default path to your server’s /oauth2/token/revoke endpoint.
Default: /oauth2/realms/{forgerock_realm}/token/revoke

forgerock_userinfo_endpoint

Override the default path to your server’s /oauth2/userinfo endpoint.
Default: /oauth2/realms/{forgerock_realm}/userinfo

forgerock_session_endpoint

Override the default path to your server’s /json/sessions endpoint.

SDK permissions

The Ping SDK for Android requires certain permissions depending on your use case.

Internet permissions (required)

Your Android app requires the following permission to access the Internet:

Permission name Description

android.permission.INTERNET

Lets applications open network sockets.

Location permissions (optional)

Your Android app requires the following location permissions if your app needs to capture location information during device profiling:

Permission name Description

android.permission.ACCESS_FINE_LOCATION

Lets the app access precise location.

android.permission.ACCESS_COARSE_LOCATION

Lets the app access approximate location.

Ping SDK for iOS Properties

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

Server properties

Property Description

forgerock_url

The base URL of the server to connect to, including port and deployment path.

Identity Cloud example:

https://openam-forgerock-sdks.forgeblocks.com/am

Self-hosted example:

https://openam.example.com:8443/openam

forgerock_realm

The realm in which the OAuth 2.0 client profile and authentication journeys are configured.

For example, alpha.

Defaults to the self-hosted top-level realm root.

forgerock_timeout

A timeout, in seconds, for each request that communicates with your server.

forgerock_enable_cookie

When true, enables cookie use.

Defaults to true.

forgerock_cookie_name

The name of the cookie that contains the session token.

For example, with a self-hosted PingAM server this value might be iPlanetDirectoryPro.

PingOne Advanced Identity Cloud tenants use a random alpha-numeric string.

To locate the cookie name in an PingOne Advanced Identity Cloud tenant, navigate to Tenant settings > Global Settings, and copy the value of the Cookie property.

Journey properties

Property Description

forgerock_auth_service

The name of a user authentication tree configured in your server.

For example, sdkUsernamePasswordJourney.

forgerock_registration_service_name

The name of a user registration tree configured in your server.

For example, sdkRegistrationJourney.

OAuth 2.0 properties

Property Description

forgerock_oauth_client_id

The client_id of the OAuth 2.0 client profile to use.

For example, sdkPublicClient.

forgerock_oauth_redirect_uri

The redirect_uri as configured in the OAuth 2.0 client profile.

[NOTE] This value must match a value configured in your OAuth 2.0 client, but is not actually used by the iOS application.

For example, https://sdkapp.example.com:8443/callback.

forgerock_oauth_scope

A list of scopes to request when performing an OAuth 2.0 authorization flow, separated by spaces.

For example, openid profile email address.

forgerock_oauth_threshold

A threshold, in seconds, to refresh an OAuth 2.0 token before the access_token expires.

Defaults to 30 seconds.

SSL pinning properties

Property Description

forgerock_ssl_pinning_public_key_hashes

An array of public key certificate hashes (strings) for trusted sites and services.

forgerock_keychain_access_group

Keychain access group for the shared keychain.

Custom endpoint properties

Property Description

forgerock_authenticate_endpoint

Override the default path to your server’s /json/authenticate endpoint.
Default: /json/realms/{forgerock_realm}/authenticate

forgerock_authorize_endpoint

Override the default path to the PingAM’s /oauth2/authorize endpoint.
Default: /oauth2/realms/{forgerock_realm}/authorize

forgerock_token_endpoint

Override the default path to your server’s /oauth2/access_token endpoint.
Default: /oauth2/realms/{forgerock_realm}/access_token

forgerock_revoke_endpoint

Override the default path to your server’s /oauth2/token/revoke endpoint.
Default: /oauth2/realms/{forgerock_realm}/token/revoke

forgerock_userinfo_endpoint

Override the default path to your server’s /oauth2/userinfo endpoint.
Default: /oauth2/realms/{forgerock_realm}/userinfo

forgerock_session_endpoint

Override the default path to your server’s /json/sessions endpoint.

Ping SDK for JavaScript Properties

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

Ping SDK for JavaScript properties
Property Description

serverConfig

An interface for configuring how the SDK contacts the PingAM instance.

Contains baseUrl and timeout.

serverConfig: {baseUrl}

The base URL of the server to connect to, including port and deployment path.

Identity Cloud example:

https://openam-forgerock-sdks.forgeblocks.com/am

Self-hosted example:

https://openam.example.com:8443/openam

serverConfig: {wellknown}

A URL to the server’s .well-known/openid-configuration endpoint.

Use the Config.setAsync() method to set SDK configuration using values derived from those provided at the URL.

Example:

https://openam-forgerock-sdks.forgeblocks.com/am/oauth2/realms/root/realms/alpha/.well-known/openid-configuration

Self-hosted example:

https://openam.example.com:8443/openam/oauth2/realms/root/.well-known/openid-configuration

serverConfig: {timeout}

A timeout, in milliseconds, for each request that communicates with your server.

For example, for 30 seconds specify 30000.

Defaults to 5000 (5 seconds).

realmPath

The realm in which the OAuth 2.0 client profile and authentication journeys are configured.

For example, alpha.

Defaults to the self-hosted top-level realm root.

tree

The name of the user authentication tree configured in your server.

For example, sdkUsernamePasswordJourney.

clientId

The client_id of the OAuth 2.0 client profile to use.

redirectUri

The redirect_uri as configured in the OAuth 2.0 client profile.

The Ping SDK for JavaScript attempts to load the redirect page to capture the OAuth 2.0 code and state query parameters that the server appended to the redirect URL.

If the page you redirect to does not exist, takes a long time to load, or runs any JavaScript you might get a timeout, delayed authentication, or unexpected errors.

To ensure the best user experience, we highly recommend that you redirect to a static HTML page with minimal HTML and no JavaScript when obtaining OAuth 2.0 tokens.

For example, https://localhost:8443/callback.html.

scope

A list of scopes to request when performing an OAuth 2.0 authorization flow, separated by spaces.

For example, openid profile email address.

oauthThreshold

A threshold, in seconds, to refresh an OAuth 2.0 token before the access_token expires.

Defaults to 30 seconds.

logLevel

Specify whether the SDK should output its log messages in the console and the level of messages to display.

One of:

  • none (default)

  • info

  • warn

  • error

  • debug

logger

Specify a function to override the default logging behavior.

Refer to Customize the Ping SDK for JavaScript logger.

tokenStore

The API to use for storing tokens on the client:

sessionStorage

Store tokens using the sessionStorage API. The browser clears session storage when a page session ends.

localStorage

Store tokens using the localStorage API. The browser saves local storage data across browser sessions. This is the default setting, as it provides the highest browser compatibility.

prefix

Override the default fr prefix string applied to the keys used for storing data on the client, such as tokens, device IDs, and information about the steps in a journey.

For example, the key used for storing tokens consists of the prefix, followed by the ID of the OAuth 2.0 client:

fr-sdkPublicClient.

platformHeader

Specify whether to include an X-Requested-Platform header in outgoing requests.

The server can use the value of this header to alter the logic of an authentication flow. For example, if the value indicates a JavaScript web app, the journey could avoid device binding nodes, as they are only supported by Android and iOS apps.

Defaults to false.

Custom endpoint properties

You can override the default paths for a number of endpoints by adding a serverConfig {paths} structure.

You can use a server’s .well-known/openid-configuration endpoint to configure paths automatically.

Enter the well-known URL in the serverConfig.wellknown property, and use the asynchronous Config.setAsync() method to configure the SDK:

await Config.setAsync({
  clientId: 'sdkPublicClient',
  redirectUri: 'https://localhost:8443/callback.html',
  scope: 'openid profile email address',
  serverConfig: {
    wellknown: 'https://openam-forgerock-sdks.forgeblocks.com/am/oauth2/realms/root/realms/alpha/.well-known/openid-configuration'
  },
});
Available properties to override default paths
Property Description

authenticate

Override the default /json/authenticate endpoint.
Default: json/{realmPath}/authenticate

authorize

Override the default /oauth2/authorize endpoint.
Default: oauth2/{realmPath}/authorize

accessToken

Override the default /oauth2/access_token endpoint.
Default: oauth2/{realmPath}/access_token

revoke

Override the default /oauth2/token/revoke endpoint.
Default: oauth2/{realmPath}/token/revoke

userInfo

Override the default /oauth2/userinfo endpoint.
Default: oauth2/{realmPath}/userinfo

sessions

Override the default /json/sessions endpoint.
Default: json/{realmPath}/sessions

endSession

Override the default /oauth2/connect/endSesison endpoint.
Default: oauth2/{realmPath}/connect/endSession

Example:

forgerock.Config.set({
    serverConfig: {
        baseUrl: 'https://openam-forgerock-sdks.forgeblocks.com/am',
        paths: {
            authenticate: 'iam/endpoints/authN',
            authorize: 'iam/endpoints/authZ'
        },
        timeout: 30000,
    },
    realmPath: 'alpha',
    tree: 'sdkUsernamePasswordJourney'
});
Any endpoint paths that you do not override use the pre-configured defaults.