Ping SDKs

Configure Ping SDK for Android properties

Applies to:

  • Ping SDK for Android

  • Ping SDK for iOS

  • Ping SDK for JavaScript

To configure the Ping SDK for Android, use the FROptionsBuilder methods to build an FROptions object, and pass the object to the FRAuth.start() method.

Properties

The following properties are available for configuring the Ping SDK for Android:

Server

FROptionsBuilder attribute

server

Properties
Property name Description Required
Java

setUrl

Kotlin

url

The base URL of the PingAM instance 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

Required 1
Java

setRealm

Kotlin

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.

Required 1
Java

setTimeout

Kotlin

timeout

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

Default: 30

Java

setCookieName

Kotlin

cookieName

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.

Default: iPlanetDirectoryPro

Required 1
Java

setCookieCache

Kotlin

cookieCache

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

Default: 0

Journeys

FROptionsBuilder attribute

service

Properties
Property name Description Required
Java

setAuthService

Kotlin

authService

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

For example, sdkUsernamePasswordJourney.

Java

setRegistrationService

Kotlin

registrationService

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

For example, sdkRegistrationJourney.

OAuth 2.0

FROptionsBuilder attribute

oauth

Properties
Property name Description Required
Java

setOauthClientId

Kotlin

oauthClientId

The client_id of the OAuth 2.0 client profile to use.

For example, sdkNativeClient.

1
Java

setOauthRedirectUri

Kotlin

oauthRedirectUri

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.

For example, org.forgerock.demo://oauth2redirect.

1
Java

setOauthSignOutRedirectUri

Kotlin

oauthSignOutRedirectUri

The URI to redirect to after signing the user out of the authorization server.

For example, org.forgerock.demo://oauth2redirect.

1
Java

SetOauthScope

Kotlin

oauthScope

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

For example, openid profile email address.

1
Java

setOauthThreshold

Kotlin

oauthThreshold

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

Java

setOauthCache

Kotlin

oauthCache

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

Storage

FROptionsBuilder attribute

store

Properties
Property name Description Required
Java

setOidcStorage

Kotlin

oidcStorage

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

Java

SetSsoTokenStorage

Kotlin

ssoTokenStorage

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

Java

SetCookiesStorage

Kotlin

cookiesStorage

A custom class for the storage of cookies.

SSL pinning

FROptionsBuilder attribute

sslPinning

Properties
Property name Description Required
Java

setPins

Kotlin

pins

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

Java

setBuildSteps

Kotlin

buildSteps

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

Endpoints

FROptionsBuilder attribute

urlPath

Properties
Property name Description Required
Java

setAuthenticateEndpoint

Kotlin

authenticateEndpoint

Override the path to the authorization server’s authenticate endpoint.

Default: /json/realms/{forgerock_realm}/authenticate

Java

setAuthorizeEndpoint

Kotlin

authorizeEndpoint

Override the path to the authorization server’s authorize endpoint.

Default: /oauth2/realms/{forgerock_realm}/authorize

Java

setTokenEndpoint

Kotlin

tokenEndpoint

Override the path to the authorization server’s access_token endpoint.

Default: /oauth2/realms/{forgerock_realm}/access_token

Java

setRevokeEndpoint

Kotlin

revokeEndpoint

Override the path to the authorization server’s revoke endpoint.

Default: /oauth2/realms/{forgerock_realm}/token/revoke

Java

setUserinfoEndpoint

Kotlin

userinfoEndpoint

Override the path to the authorization server’s userinfo endpoint.

Default: /oauth2/realms/{forgerock_realm}/userinfo

Java

setSessionEndpoint

Kotlin

sessionEndpoint

Override the path to the authorization server’s sessions endpoint.

Session and token lifecycle

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

  • setUrl / url

  • setRealm / realm

  • setCookieName / cookieName

  • setOauthClientId / oauthClientId

  • setOauthRedirectUri / oauthRedirectUri

  • setOauthScope / oauthScope

Examples

The following examples show how to configure the Ping SDK in your Android applications:

  • 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.

Using the .well-known endpoint

You can configure the SDKs to obtain many required settings from your authorization server’s .well-known OpenID Connect endpoint.

How do I find my PingOne Advanced Identity Cloud .well-known URL?

You can view the .well-known endpoint for an OAuth 2.0 client in the PingOne Advanced Identity Cloud admin console:

  1. Log in to your PingOne Advanced Identity Cloud administration console.

  2. Click Applications, and then select the OAuth 2.0 client you created earlier. For example, sdkPublicClient.

  3. On the Sign On tab, in the Client Credentials section, copy the Discovery URI value.

    For example, https://openam-forgerock-sdks.forgeblocks.com/am/oauth2/alpha/.well-known/openid-configuration

If you are using a custom domain, your .well-known is formed as follows:

https://<custom-domain-fqdn>/.well-known/openid-configuration

Learn more in Access OIDC configuration discovery endpoint.
How do I find my PingAM .well-known URL?

To form the .well-known URL for an PingAM server, concatenate the following information into a single URL:

  1. The base URL of the PingAM component of your deployment, including the port number and deployment path.

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

  2. The string /oauth2

  3. The hierarchy of the realm that contains the OAuth 2.0 client.

    You must specify the entire hierarchy of the realm, starting at the Top Level Realm. Prefix each realm in the hierarchy with the realms/ keyword.

    For example, /realms/root/realms/customers

    If you omit the realm hierarchy, the top level ROOT realm is used by default.

  4. The string /.well-known/openid-configuration

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

Settings gathered from the endpoint include the paths to use for OAuth 2.0 authorization requests, and login endpoints.

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

val options =
    options.discover("https://openam-forgerock-sdks.forgeblocks.com/am/oauth2/realms/root/realms/alpha/.well-known/openid-configuration")

FRAuth.start(context, options)