Configuring the Journey module in JavaScript

PingOne Advanced Identity Cloud PingAM JavaScript

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

There are two methods for configuring the Journey client:

Full configuration: Use the JavaScript factory function to access all available settings, including JavaScript-specific options such as request middleware and custom loggers.
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 client, call the journey() factory function and provide the configuration options as follows:

Configuring the journey client

const journeyClient = await journey({
  logger: {
    level: 'warn', // Specify which messages the module should output
    custom: customLogger, // Specify a custom logger object for the module
  },
  config: {
    serverConfig: {
      wellknown: 'https://openam-forgerock-sdks.forgeblocks.com/am/oauth2/realms/alpha/.well-known/openid-configuration',
    },
  },
  requestMiddleware: [
    customHeaderMiddleware,
    customParamMiddleware
  ]
});

Update the following properties with values that match your environment:

wellknown

The OpenID Connect well-known endpoint for your server.

The Journey module derives the various endpoints and data it requires from the well-known endpoint, such as the server’s base URL, the realm being used, and the authenticate and session endpoints.

Advanced Identity Cloud example:

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

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.

PingAM example:

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

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

level

Specify what level of logging the Orchestration SDK should output.

Select one of the following:

none
error
warn
info (the default)
debug

Learn more in Configuring JavaScript logging.

custom

A custom logger object that the module will use to output messages.

Learn more in Customizing JavaScript logging.

requestMiddleware

The middleware to use to customize network requests from the Journey module.

Learn more in Customizing requests from the Journey module in JavaScript.

To obtain OIDC tokens after authentication, create an OIDC client alongside your Journey client.

Learn more in Configuring JavaScript apps for OIDC sign-on.

Common JSON configuration

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

Use the makeJourneyConfig() helper from @forgerock/sdk-utilities to convert the JSON to native config, then pass it to journey():

Configure the journey client from a JSON object

import { journey } from '@forgerock/journey-client';
import { makeJourneyConfig } from '@forgerock/sdk-utilities';

const unifiedConfig = {
    log: 'WARN',
    oidc: {
        discoveryEndpoint: 'https://openam-forgerock-sdks.forgeblocks.com/am/oauth2/realms/alpha/.well-known/openid-configuration',
    },
};

const journeyClient = await journey({
    config: makeJourneyConfig(unifiedConfig),
});

Because makeJourneyConfig() returns a standard native config object, you can combine it with JavaScript-specific options in the same journey() call:

Combining JSON config with JavaScript-specific options

const journeyClient = await journey({
    config: makeJourneyConfig(unifiedConfig),
    logger: { level: 'debug', custom: myCustomLogger },
    requestMiddleware: [customHeaderMiddleware],
});

The makeJourneyConfig() helper maps oidc.discoveryEndpoint to config.serverConfig.wellknown automatically.

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

Configuration property reference

The following properties are available when configuring the Journey client for JavaScript.

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

Journey module configuration properties for JavaScript
Property	JSON property	Description	Required?
`logger.level`	`log`	Specify what level of logging the Orchestration SDK should output. Select one of the following: `none` `error` `warn` `info` (the default) `debug` Learn more in Configuring JavaScript logging. In JSON configuration, use the `log` property at the root level with values `NONE`, `WARN`, or `DEBUG`.	No
`config.serverConfig.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
`config.realmPath`	`journey.realm`	The realm containing your users and configuration. Usually, `root` for PingAM and `alpha` or `bravo` for Advanced Identity Cloud.	Yes
`config.serverConfig.baseUrl`	`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
`config.serverConfig.wellknown`	`oidc.discoveryEndpoint`	The OpenID Connect well-known endpoint for your server. The Journey module derives the various endpoints and data it requires from the well-known endpoint, such as authenticate and session endpoints. Advanced Identity Cloud example: `https://openam-forgerock-sdks.forgeblocks.com/am/oauth2/realms/alpha/.well-known/openid-configuration` PingAM example: `https://openam.example.com:8443/openam/oauth2/realms/root/.well-known/openid-configuration`	Yes
`logger.custom`		A custom logger object that the module will use to output messages. Learn more in Customizing JavaScript logging.	No
`requestMiddleware`		The middleware to use to customize network requests from the Journey module. Learn more in Customizing requests from the Journey module in JavaScript.	No