Configuring the Journey module on Android

PingOne Advanced Identity Cloud PingAM Android

You must configure the Journey module to connect to your Advanced Identity Cloud or PingAM server.

There are two methods for configuring the Journey module:

Full configuration: Use the Kotlin builder DSL to access all available settings, including Android-specific options such as custom HTTP clients and storage configuration.
Common JSON configuration: Use a shared key-value structure that works identically across Android, iOS, and JavaScript, letting you load a single config file across platforms.

Full configuration

To configure the module, instantiate the Journey class and provide the configuration options as follows:

Configuring the journey module

val journeyClient = Journey {
    serverUrl = "https://openam-forgerock-sdks.forgeblocks.com/am" // Specify the server URL
    realm = "alpha" // Specify the realm for authentication
    cookie = "ch15fefc5407912" // Specify the cookie name for session management
    logger = Logger.STANDARD // Optional. Logger the module uses to output messages
    httpClient = customHttpClient // Optional. Intercept and customize network requests
}

Integrating the OIDC Module

You can choose to integrate the OIDC module into your Journey module configuration, to obtain and manage OpenID Connect 1.0 tokens on behalf of the user.

To integrate the OIDC module, add the configuration when instantiating the Journey class as follows:

Integrating the oidc module with the journey module

val journeyClient = Journey {
    serverUrl = "https://openam-forgerock-sdks.forgeblocks.com/am"
    realm = "alpha"
    cookie = "ch15fefc5407912"
    module(Oidc) {
        clientId = "sdkPublicClient"
        discoveryEndpoint = "https://openam-forgerock-sdks.forgeblocks.com/am/oauth2/realms/alpha/.well-known/openid-configuration"
        scopes = ["openid", "email", "address"]
        redirectUri = "org.forgerock.demo://oauth2redirect"
        par = true
    }
}

Common JSON configuration

You can provide the complete Journey and OIDC configuration as a JSON object, which lets you share a single config file across Android, iOS, and JavaScript.

Configure the Journey module from a JSON object

val journeyClient = Journey(buildJsonObject {
    put("timeout", 30000) // milliseconds
    put("log", "WARN")
    putJsonObject("journey") {
        put("serverUrl", "https://openam-forgerock-sdks.forgeblocks.com/am")
        put("realm", "alpha")
        put("cookieName", "ch15fefc5407912")
    }
    putJsonObject("oidc") {
        put("clientId", "sdkPublicClient")
        put("discoveryEndpoint",
            "https://openam-forgerock-sdks.forgeblocks.com/am/oauth2/realms/alpha/.well-known/openid-configuration")
        putJsonArray("scopes") { add("openid"); add("profile"); add("email") }
        put("redirectUri", "com.example.demo://oauth2redirect")
    }
}).getOrThrow()

Optionally, you can store this JSON in a file alongside your app and load it at runtime so the same file can be shared across platforms.

JSON configuration supports the common properties that work across all platforms.

The JSON factory and the native Journey {} builder DSL are mutually exclusive, there is no combined form.

If you need Android-specific settings such as httpClient or storage configuration, use the native builder DSL for the entire configuration instead.

Configuration property reference

The following properties are available when configuring the Journey module for Android.

The JSON property column shows the equivalent key when using JSON configuration.

Journey module configuration properties for Android
Property	JSON property	Description	Required?
`logger`	`log`	The logger the module uses to output messages. Choose from, `STANDARD`, `WARN`, or `NONE`, or specify a custom logger to use. Learn more in Customizing logging on Android. In JSON configuration, use the `log` property at the root level.	No
`cookie`	`journey.cookieName`	The name of the cookie your PingOne Advanced Identity Cloud tenant uses to store SSO tokens in client browsers. On a self-hosted PingAM server this value is usually `iPlanetDirectoryPro`. On servers, the cookie name is a random string of characters, such as `ch15fefc5407912`. How do I find my PingOne Advanced Identity Cloud cookie name? To locate the cookie name in an PingOne Advanced Identity Cloud tenant: Navigate to Tenant settings > Global Settings Copy the value of the Cookie property. In JSON configuration, this property is named `cookieName` under the `journey` object.	Yes
`realm`	`journey.realm`	The realm containing your users and configuration. Usually, `root` for PingAM and `alpha` or `bravo` for Advanced Identity Cloud.	Yes
`serverUrl`	`journey.serverUrl`	The URL of the Access Management service on your server, including the deployment path. Advanced Identity Cloud example: `https://openam-forgerock-sdks.forgeblocks.com/am` PingAM example: `https://openam.example.com:8443/openam`	Yes
`httpClient`		The HTTP client to use to customize network requests from the Journey module. Learn more in Customizing requests from the Journey module on Android.	No
`timeout`	`timeout`	A timeout, in milliseconds, for each request that communicates with the server. For example, for 30 seconds specify `30000`. When using JSON configuration, specify `timeout` at the root level.	No

Property JSON property Description Required?

clientId

oidc.clientId

The client ID from your OAuth 2.0 application.

For example, sdkPublicClient

Yes

discoveryEndpoint

oidc.discoveryEndpoint

The .well-known endpoint from your server.

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:

Log in to your PingOne Advanced Identity Cloud administration console.
Click Applications, and then select the OAuth 2.0 client you created earlier. For example, sdkPublicClient.
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:

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
The string /oauth2
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.
The string /.well-known/openid-configuration

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

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

Yes

par

oidc.par

Whether to use Pushed Authorization Requests (PAR) for communicating with the authorization server.

Learn more in Securing OIDC sign-on with Pushed Authorization Requests.

redirectUri

oidc.redirectUri

The redirect_uri as configured in the OAuth 2.0 client profile.

This value must exactly match a value configured in your OAuth 2.0 client.

For example, com.example.demo://oauth2redirect

Yes

scopes

oidc.scopes

The scopes you added to your OAuth 2.0 application.

For example, "openid", "email", "address", "profile", "phone"

Yes

acrValues

oidc.acrValues

An optional space-separated list of Authentication Context Class Reference (acr) values, in order of preference.

The server can use these values to help determine how the user should be authenticated.

additionalParameters

oidc.additionalParameters

Add any additional key-value query parameters your environment might require to complete an OAuth 2.0 flow.

display

oidc.display

How the authorization server should display the authentication UI.

page: Full-page redirect (default).
popup: Pop-up window.
touch: Optimized for touch-based devices.
wap: Optimized for WAP/mobile browsers.

loginHint

oidc.loginHint

A hint to pre-populate the username field on the authorization server’s sign-on page.

For example, user@example.com

nonce

oidc.nonce

A value to associate with the ID token to prevent replay attacks.

If not set, the SDK generates a nonce automatically.

prompt

oidc.prompt

Controls whether the authorization server prompts the user for re-authentication or consent.

none: No UI; returns an error if interaction is required.
login: Force re-authentication.
consent: Request consent even if previously granted.
select_account: Prompt to select an account.

refreshThreshold

oidc.refreshThreshold

The number of seconds before token expiry at which the SDK proactively refreshes the token.

Defaults to 0, meaning the SDK refreshes only when the token has expired.

signOutRedirectUri

oidc.signOutRedirectUri

The URI to redirect to after sign-out.

Maps to the post_logout_redirect_uri parameter in the end-session request.

This value must be registered in your OAuth 2.0 client.

uiLocales

oidc.uiLocales

Space-separated BCP 47 language tags indicating the preferred display language for the authorization server’s UI.

For example, en-US fr