Orchestration SDKs

Step 2. Configure connection properties

PingOne Advanced Identity Cloud PingAM JavaScript

There are two projects in this tutorial that require configuration:

Backend API server

A backend REST API server that uses a confidential OAuth 2.0 client to contact the authorization server. The API server handles storage and retrieval of your personal "Todo" items.

Client ReactJS app

The front-end client app, written in React, that handles the UI and authentication journeys.

Configure the API server app

  1. In the IDE of your choice, open the sdk-sample-apps folder you cloned previously.

  2. Copy the .env.example file in the sdk-sample-apps/javascript/todo-api folder and save it with the name .env within this same directory.

    The file contains configuration to connect to the confidential OAuth 2.0 client you created earlier:

    Example default API server sdk-sample-apps/javascript/todo-api/.env file
    # 'AIC' or 'PINGONE'
SERVER_TYPE=
# AM URL for AIC or PingOne base URL with env ID for PingOne
SERVER_URL=
PORT=
# 'alpha' or 'bravo' for AIC server type. Not used for PingOne.
REALM_PATH=
# Confidential client ID for AIC or WebApp public client ID for PingOne
REST_OAUTH_CLIENT=
# Confidential client secret for AIC. Not used for PingOne.
REST_OAUTH_SECRET=

  3. Update the configuration block with the details of your server environment.

    SERVER_TYPE

    Ensures the sample app uses the correct behavior for the different servers it supports, for example the endpoint to use for introspecting tokens received from the client app.

    For PingOne Advanced Identity Cloud or PingAM servers, specify AIC.

    SERVER_URL

    The URL of the server to connect to, including the deployment path of the Access Management component.

    Identity Cloud example:

    https://openam-forgerock-sdks.forgeblocks.com/am

    Self-hosted example:

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

    PORT

    The port number on which to run the TODO API server.

    You’ll need this port number when configuring the client app to connect to the TODO API server.

    If not specified, the TODO API server defaults to running on port 9443

    REALM_PATH

    The realm in which the confidential OAuth 2.0 client profile is configured.

    Usually, root for PingAM servers and alpha or bravo for Advanced Identity Cloud tenants.

    REST_OAUTH_CLIENT

    The client ID of the confidential OAuth 2.0 application you created earlier.

    For example, sdkConfidentialClient

    REST_OAUTH_SECRET

    The secret of the confidential OAuth 2.0 application you created earlier.

    For example, 5tr0ngP@S5w0rd!

    The result will resemble the following:

    Example completed API server sdk-sample-apps/javascript/todo-api/.env file
    # 'AIC' or 'PINGONE'
SERVER_TYPE=AIC
# AM URL for AIC or PingOne base URL with env ID for PingOne
SERVER_URL=https://openam-forgerock-sdks.forgeblocks.com/am
PORT=9443
# 'alpha' or 'bravo' for AIC server type. Not used for PingOne.
REALM_PATH=alpha
# Confidential client ID for AIC or WebApp public client ID for PingOne
REST_OAUTH_CLIENT=sdkConfidentialClient
# Confidential client secret for AIC. Not used for PingOne.
REST_OAUTH_SECRET=5tr0ngP@S5w0rd!

  4. Save your changes.

Configure the ReactJS client app

  1. Copy the .env.example file in the sdk-sample-apps/javascript/reactjs-todo-journey folder and save it with the name .env within this same directory.

    The file contains configuration to connect to the public OAuth 2.0 client you created earlier, and the journey to use for authentication:

    Example client sdk-sample-apps/javascript/reactjs-todo-journey/.env file
    VITE_WELLKNOWN_URL=
VITE_WEB_OAUTH_CLIENT=
VITE_API_URL=http://localhost:9443
VITE_PORT=8443
VITE_DEBUGGER_OFF=true
VITE_DEVELOPMENT=true
VITE_SCOPE='openid profile email'
VITE_JOURNEY_LOGIN=Login
VITE_JOURNEY_REGISTER=Registration
VITE_REALM_PATH=alpha

# VITE_INIT_PROTECT (optional) - bootstrap | journey
# 'bootstrap' will initialize protect at app bootstrap time
# 'journey' relies on the PingOneProtectEvaluationCallback for initialization
VITE_INIT_PROTECT=

# VITE_PINGONE_ENV_ID - required if VITE_INIT_PROTECT is set
VITE_PINGONE_ENV_ID=

  2. Update the configuration block with the details of your server environment.

    VITE_WELLKNOWN_URL

    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:

    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

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

    VITE_WEB_OAUTH_CLIENT

    The client ID of your public OAuth 2.0 application in PingOne Advanced Identity Cloud or PingAM.

    For example, sdkPublicClient

    VITE_API_URL

    The URL and port number on which you are running the TODO API backend server.

    For example, http://localhost:9443

    VITE_PORT

    The port number on which to run the ReactJS client app.

    If not specified, the client app defaults to running on port 8443

    VITE_DEBUGGER_OFF

    Set to true, to disable debug statements in the app.

    These statements are for learning the integration points at runtime in your browser.

    When you open the browser’s developer tools, the app pauses at each integration point. Code comments are placed above each one explaining their use.

    VITE_DEVELOPMENT

    When true, this provides better debugging during development.

    VITE_SCOPE

    The scopes you added to your public OAuth 2.0 application.

    Scopes should be space-separated, and the entire value should be enclosed in single-quotes.

    For example, 'openid profile email address'

    VITE_JOURNEY_LOGIN

    The simple login journey or tree you created earlier, for example you could use default builtin Login journey, or the sdkUsernamePasswordJourney you created in a previous step.

    VITE_JOURNEY_REGISTER

    A registration journey or tree.

    You can use the default builtin Registration journey.

    VITE_REALM_PATH

    The realm in which the OAuth 2.0 client profile and authentication journeys are configured.

    Usually, root for AM and alpha or bravo for Advanced Identity Cloud.

    INIT_PROTECT

    The ReactJS client app supports PingOne Protect risk evaluations.

    To enable risk evaluations, specify one of the following options:

    bootstrap

    The client app manually initializes the PingOne Protect SDK during startup.

    journey

    The client app initializes the PingOne Protect SDK only when encountering PingOneProtectEvaluationCallback in a journey.

    Leave this blank if you do not want to use PingOne Protect in the client app.

    PINGONE_ENV_ID

    The PingOne environment identifier.

    For example, 3072206d-c6ce-ch15-m0nd-f87e972c7cc3

    This property is only required if you want to use PingOne Protect in the client application, and have set a value in the INIT_PROTECT property.

    Otherwise, leave this property empty.

    The result will resemble the following:

    Example client sdk-sample-apps/javascript/react-journey/.env file
    VITE_WELLKNOWN_URL=https://openam-forgerock-sdks.forgeblocks.com/am/oauth2/realms/alpha/.well-known/openid-configuration
VITE_WEB_OAUTH_CLIENT=sdkPublicClient
VITE_API_URL=http://localhost:9443
VITE_PORT=8443
VITE_DEBUGGER_OFF=true
VITE_DEVELOPMENT=true
VITE_SCOPE='openid profile email address'
VITE_JOURNEY_LOGIN=Login
VITE_JOURNEY_REGISTER=Registration
VITE_REALM_PATH=alpha

# VITE_INIT_PROTECT (optional) - bootstrap | journey
# 'bootstrap' will initialize protect at app bootstrap time
# 'journey' relies on the PingOneProtectEvaluationCallback for initialization
VITE_INIT_PROTECT=journey

# VITE_PINGONE_ENV_ID - required if VITE_INIT_PROTECT is set
VITE_PINGONE_ENV_ID=3072206d-c6ce-ch15-m0nd-f87e972c7cc3

  3. Save your changes.