--- title: Configure Ping (ForgeRock) SDK for JavaScript properties description: Applies to: component: sdks version: latest page_id: sdks:sdks:sdkconfiguration/configure-sdk-javascript canonical_url: https://docs.pingidentity.com/sdks/latest/sdks/sdkconfiguration/configure-sdk-javascript.html llms_txt: https://docs.pingidentity.com/sdks/llms.txt docs_for_agents: https://developer.pingidentity.com/build-with-ai/docs-for-agents.md revdate: Mon, 18 Nov 2024 12:13:37 +0100 keywords: ["PingOne Advanced Identity Cloud", "PingAM", "Journeys", "Setup & Configuration", "Source Code", "SDK"] section_ids: properties: Properties server: Server oauth_2_0: OAuth 2.0 storage: Storage logging: Logging general: General endpoints: Endpoints examples: Examples using_the_well_known_endpoint: Using the .well-known endpoint --- # Configure Ping (ForgeRock) SDK for JavaScript properties ***Applies to***: * [icon: square-o, set=fa]Ping (ForgeRock) SDK for Android * [icon: square-o, set=fa]Ping (ForgeRock) SDK for iOS * [icon: check-square-o, set=fa]Ping (ForgeRock) SDK for JavaScript Configure SDK properties in your JavaScript app by editing a `serverConfig` object, a parameter of the `Config.setAsync()` function. ## Properties The following properties are available for configuring the Ping (ForgeRock) SDK for JavaScript: ### Server **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`. | ### OAuth 2.0 **Properties** | Property | Description | | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `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 (ForgeRock) 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. | ### Storage **Properties** | Property | Description | | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `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. - `{{custom}}` Specify a custom implementation that has functions that can set, retrieve, and remove, items from a custom storage scheme. Learn more in [Customize storage on JavaScript](../customize/how-to-customize-storage.html#custom-storage-js). | | `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`. | ### Logging **Properties** | Property | Description | | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `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 (ForgeRock) SDK for JavaScript logger](../customize/how-to-custom-loggers.html#customize-logger-javascript). | ### General **Properties** | Property | Description | | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `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`. | ### Endpoints **Properties** | Property | Description | | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------ | | `serverConfig: { paths: { authenticate }}` | Override the path to the authorization server's `authenticate` endpoint.*Default*: `json/{realmPath}/authenticate` | | `serverConfig: { paths: { authorize }}` | Override the path to the authorization server's `authorize` endpoint.*Default*: `oauth2/{realmPath}/authorize` | | `serverConfig: { paths: { accessToken }}` | Override the path to the authorization server's `access_token` endpoint.*Default*: `oauth2/{realmPath}/access_token` | | `serverConfig: { paths: { revoke }}` | Override the path to the authorization server's `revoke` endpoint.*Default*: `oauth2/{realmPath}/token/revoke` | | `serverConfig: { paths: { userInfo }}` | Override the path to the authorization server's `userinfo` endpoint.*Default*: `oauth2/{realmPath}/userinfo` | | `serverConfig: { paths: { sessions }}` | Override the path to the authorization server's `sessions` endpoint.*Default*: `json/{realmPath}/sessions` | | `serverConfig: { paths: { endSession }}` | Override the path to the authorization server's `endSession` endpoint.*Default*: `oauth2/{realmPath}/connect/endSession` | ## Examples The following examples show how to configure the Ping (ForgeRock) SDK in your JavaScript applications: ```javascript Config.setAsync({ serverConfig: { wellknown: 'https://openam-forgerock-sdks.forgeblocks.com/am/oauth2/realms/root/realms/alpha/.well-known/openid-configuration', timeout: 3000, paths: { authenticate: 'iam/endpoints/authN', authorize: 'iam/endpoints/authZ' }, }, clientId: 'sdkPublicClient', scope: 'openid profile email address', redirectUri: `${window.location.origin}/callback.html`, realmPath: 'alpha' }); ``` ## 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. > **Collapse: How do I find my PingOne Advanced Identity Cloud 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:///.well-known/openid-configuration`Learn more in [Access OIDC configuration discovery endpoint](https://docs.pingidentity.com/pingoneaic/latest/realms/custom-domains.html#access-oidc-configuration-discovery-endpoint). | > **Collapse: How do I find my PingAM 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 `Config.setAsync` method to use the `.well-known` endpoint to configure OAuth 2.0 paths: ```javascript await Config.setAsync({ serverConfig: { wellknown: 'https://openam-forgerock-sdks.forgeblocks.com/am/oauth2/realms/root/realms/alpha/.well-known/openid-configuration' }, clientId: 'sdkPublicClient', scope: 'openid profile email address', redirectUri: `${window.location.origin}/callback.html` }); ```