Ping SDKs

Configure the SDKs dynamically

Applies to:

  • Ping SDK for Android

  • Ping SDK for iOS

  • Ping SDK for JavaScript

It can sometimes be convenient to change configurations without reinstalling your app. For example, to switch test environments on the fly or to switch to a different service, change the app settings programmatically with dynamic configuration.

  • Android

  • iOS

Use the FROptionsBuilder methods to build an FROptions object, and pass the object to the FRAuth.start() method.

The builder provides access to the settings defined by the following properties:

Ping SDK for Android dynamic properties

Domain (frOptionsBuilder attribute)

Property name

Description

Required

Android (Java)

Android (Kotlin)

Server (server)

setUrl

url

The base URL of the PingAM instance to connect to, including port and deployment path; for example, https://openam.example.com:8443/openam.

setRealm

realm

The realm where the OAuth 2.0 client profile is configured.

Default: root

setTimeout

timeout

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

Default: 30

setCookieName

cookieName

The name of the cookie that contains the session token, for example, iPlanetDirectoryPro.

To locate the cookie name in an PingOne Advanced Identity Cloud tenant, go to Tenant settings > Global Settings > Cookie.

Default: iPlanetDirectoryPro

setCookieCache

cookieCache

Time, in seconds, to cache the session token cookie in memory.

Default: 0

Journeys (service)

setAuthService

authService

The name of the user authentication tree configured in PingAM.

setRegistrationService

registrationService

The name of the user registration tree configured in PingAM.

OAuth 2.0 (oauth)

setOauthClientId

oauthClientId

The client_id of the OAuth 2.0 client profile to use.

setOauthRedirectUri

oauthRedirectUri

The redirect_uri as configured in the OAuth 2.0 client profile.

SetOauthScope

oauthScope

A list of scopes to request when performing an OAuth 2.0 authorization flow.

setOauthThreshold

oauthThreshold

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

setOauthCache

oauthCache

Time, in seconds, to cache an OAuth 2.0 token in memory (defaults to 0 seconds).

Storage (store)

setOidcStorage

oidcStorage

A custom class for the storage of OpenID Connect-related items, such as access tokens.

SetSsoTokenStorage

ssoTokenStorage

A custom class for the storage of single sign-on-related items, such as SSO tokens.

SetCookiesStorage

cookiesStorage

A custom class for the storage of cookies.

SSL pinning (sslPinning)

setPins

pins

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

setBuildSteps

buildSteps

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

Custom endpoints (urlPath)

setAuthenticateEndpoint

authenticateEndpoint

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

setAuthorizeEndpoint

authorizeEndpoint

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

setTokenEndpoint

tokenEndpoint

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

setRevokeEndpoint

revokeEndpoint

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

setUserinfoEndpoint

userinfoEndpoint

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

setSessionEndpoint

sessionEndpoint

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

In addition, the Ping SDK for Android lets you configure the log level and a custom logger.

Use the FROptions interface to build an options object and pass the object to the FRAuth.start() method.

The options object provides access to the settings defined by the following properties. These settings are the same as the properties in FRAuthConfig.plist:

Ping SDK for iOS dynamic properties
Domain Property Description Required

Server

forgerock_url

The base URL of the PingAM instance to connect to, including port and deployment path; for example, https://openam.example.com:8443/openam.

forgerock_realm

The realm where the OAuth 2.0 client profile is configured.

Default: root

forgerock_timeout

A timeout, in seconds, for each request that communicates with PingAM (defaults to 30 seconds).

forgerock_enable_cookie

When true, enables cookie use (defaults to true).

forgerock_cookie_name

The name of the cookie that contains the SSO token, for example, iPlanetDirectoryPro.

To locate the cookie name in an PingOne Advanced Identity Cloud tenant, go to Tenant Settings > Global Settings > Server.

Default: iPlanetDirectoryPro

Journeys

forgerock_auth_service_name

The name of the user authentication tree configured in PingAM.

forgerock_registration_service_name

The name of the user registration tree configured in PingAM.

OAuth 2.0

forgerock_oauth_client_id

The client_id of the OAuth 2.0 client profile to use.

forgerock_oauth_redirect_uri

The redirect_uri as configured in the OAuth 2.0 client profile.

forgerock_oauth_scope

A list of scopes to request when performing an OAuth 2.0 authorization flow.

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

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 endpoints

forgerock_authenticate_endpoint

Override the default path to PingAM’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 PingAM’s /oauth2/access_token endpoint.
Default: /oauth2/realms/{forgerock_realm}/access_token

forgerock_revoke_endpoint

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

forgerock_userinfo_endpoint

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

forgerock_session_endpoint

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

You must provide a value for properties that are marked as required.

The SDK throws an exception if you provide an empty string for a required property.

Session and token lifecycle

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

  • forgerock_cookie_name

  • forgerock_oauth_client_id

  • forgerock_oauth_redirect_uri

  • forgerock_oauth_scope

  • forgerock_realm

  • forgerock_url

Android example

The following examples use dynamic configuration.

  • Android - Java

  • Android - Kotlin

FROptions options = FROptionsBuilder.build(frOptionsBuilder -> {
    frOptionsBuilder.server(serverBuilder -> {
        serverBuilder.setUrl("https://tenant.forgeblocks.com/am");
        serverBuilder.setRealm("alpha");
        serverBuilder.setCookieName("46b42b4229cd7a3");
        return null;
    });
    frOptionsBuilder.oauth(oAuthBuilder -> {
        oAuthBuilder.setOauthClientId("androidClient");
        oAuthBuilder.setOauthRedirectUri("https://localhost:8443/callback");
        oAuthBuilder.setOauthScope("openid profile email address");
        return null;
    });
    frOptionsBuilder.service(serviceBuilder -> {
        serviceBuilder.setAuthServiceName("Login");
        serviceBuilder.setRegistrationServiceName("Registration");
        return null;
    });
    return null;
});
FRAuth.start(this, options);
val options = FROptionsBuilder.build {
    server {
       url = "https://openam-forgerock-sdks.forgeblocks.com/am"
       realm = "alpha"
       cookieName = "iPlanetDirectoryPro"
    }
    oauth {
       oauthClientId = "sdkPublicClient"
       oauthRedirectUri = "https://localhost:8443/callback"
       oauthScope = "openid profile email address"
    }
    service {
       authServiceName = "Login"
       registrationServiceName = "Registration"
    }
}

FRAuth.start(this, options);

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:

  • When the app calls FRAuth.start() for the first time in its lifecycle, the SDK checks for the presence of session and access tokens in the local storage. If an existing session is present, initialization does not log the user out.

  • If the app calls FRAuth.start() again, the SDK checks whether session managers and token managers are initialized, and cleans the existing session and token storage. This ensures that changes to the app configuration remove and revoke existing sessions and tokens.

iOS example

The following Swift example uses dynamic configuration.

let options = FROptions(url: "https://tenant.forgeblocks.com/am",
                        realm: "alpha",
                        cookieName: "46b42b4229cd7a3",
                        oauthClientId: "iosClient",
                        oauthRedirectUri: "frauth://com.forgerock.ios.frexample",
                        oauthScope: "openid profile email address",
                        authServiceName: "Login",
                        registrationServiceName: "Register")
try FRAuth.start(options: options)

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:

  • When the app calls FRAuth.start() for the first time in its lifecycle, the SDK checks for the presence of session and access tokens in the local storage. If an existing session is present, initialization does not log the user out.

  • If the app calls FRAuth.start() again, the SDK checks whether session managers and token managers are initialized, and cleans the existing session and token storage. This ensures that changes to the app configuration remove and revoke existing sessions and tokens.

Using the .well-known endpoint for dynamic configuration

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.

  • Android

  • iOS

Use the FROptions.discover method to use the .well-known endpoint to configure OAuth 2.0 paths:

val option =
    options.discover("https://auth.pingone.com/3072206d-c6ce-ch15-m0nd-f87e972c7cc3/as/.well-known/openid-configuration")

FRAuth.start(context, option)

Use the FROptions.discover method to use the .well-known endpoint to configure OAuth 2.0 paths:

let options = try await FROptions(config: config).discover(
  discoveryURL: "https://auth.pingone.com/3072206d-c6ce-ch15-m0nd-f87e972c7cc3/as/.well-known/openid-configuration")

try FRAuth.start(options: options)

Limitations

  • Apps do not manage tokens from multiple servers, only those of the currently active server.

  • Dynamic configuration is not persistent.

  • Dynamic configuration applies to core configuration, not extensions such as callback overrides, device profile configuration, and request interception.

  • FRUI pre-defined UI elements do not use dynamic configuration.