Advanced Identity Cloud/PingAM Login Widget

Before you begin

PingOne Advanced Identity Cloud PingAM Login Widget

To successfully complete this tutorial, refer to the prerequisites in this section.

The tutorial also requires a configured PingOne Advanced Identity Cloud tenant or PingAM server.

This tutorial targets ReactJS web applications running in a browser. It does not cover React Native, which uses a separate framework and mobile application runtime.

Prerequisites

Node.js and npm

The sample requires Node.js 24.2.0 or newer. To get a supported version of Node.js, refer to the Node.js download page.

You will also need npm to install the workspace dependencies and run the sample applications.

Local development environment

The ReactJS client runs over HTTPS at https://localhost:8443 by default. Follow the current setup instructions in the Login Widget sample repository for any local certificate or browser trust prompts.

Server configuration

This tutorial requires you to configure one of the following servers:

PingOneAICStacked

PingOne Advanced Identity Cloud
PingAM

PingAM

PingOne Advanced Identity Cloud

Task 1. Configure CORS

Cross-origin resource sharing (CORS) lets user agents make cross-domain server requests. In PingOne Advanced Identity Cloud, you can configure CORS to allow browsers from trusted domains to access PingOne Advanced Identity Cloud protected resources. For example, you might want a custom web application running on your own domain to get an end-user’s profile information using the PingOne Advanced Identity Cloud REST API.

The Advanced Identity Cloud/PingAM Login Widget samples and tutorials use https://localhost:8443 as the host domain, which you should add to your CORS configuration.

For this Login Widget sample, also add http://localhost:9443 for the Todo API server when your CORS configuration requires it.

If you are using a different domain for hosting SDK applications, ensure you add them to the CORS configuration as accepted origin domains.

To update the CORS configuration in PingOne Advanced Identity Cloud, follow these steps:

  1. Log in to your PingOne Advanced Identity Cloud tenant.

  2. At the top right of the screen, click your name, and then select Tenant settings.

  3. On the Global Settings tab, click Cross-Origin Resource Sharing (CORS).

  4. Perform one of the following actions:

    • If listed, click PingSDK.

    • If there isn’t an existing CORS configuration listed, click Add a CORS Configuration, select Ping SDK, and then click Next.

      The Ping SDK template contains many of the default values used in these tutorials.

  5. In Accepted Origins:

    1. Ensure https://localhost:8443 is listed.

    2. Add http://localhost:9443 for the Todo API server.

    3. Add any DNS aliases you use to host your Ping (ForgeRock) SDK for JavaScript applications.

  6. Complete the remaining fields to suit your environment.

    This documentation assumes the following configuration, required for the tutorials and sample applications:

    Property Values

    Accepted Origins

    https://localhost:8443

    http://localhost:9443

    Accepted Methods

    GET

    POST

    Accepted Headers

    content-type

    x-requested-with

    x-requested-platform

    accept-api-version

    authorization

    Exposed Headers

    authorization

    content-type

    Enable Caching

    True

    Max Age

    600

    Allow Credentials

    True

    Click Show advanced settings to be able to edit all available fields.

  7. Click Save CORS Configuration.

Task 2. Create a demo user

The samples and tutorials in this documentation often require that you have an identity set up so that you can test authentication.

To create a demo user in PingOne Advanced Identity Cloud, follow these steps:

  1. Log in to your PingOne Advanced Identity Cloud tenant.

  2. In the left panel, click Identities > Manage.

  3. Click New Alpha realm - User.

  4. Enter the following details:

    • Username = demo

    • First Name = Demo

    • Last Name = User

    • Email Address = demo.user@example.com

    • Password = Ch4ng3it!

  5. Click Save.

Task 3. Create an authentication journey

Authentication journeys provide fine-grained authentication by allowing multiple paths and decision points throughout the flow. Authentication journeys are made up of nodes that define actions taken during authentication.

Each node performs a single task, such as collecting a username or making a simple decision. Nodes can have multiple outcomes rather than just success or failure.

You’ll need an authentication journey configured on your server to try out the Journey module. That journey must only use callbacks supported by the Advanced Identity Cloud/PingAM Login Widget.

You can use the default Login journey that both Advanced Identity Cloud and PingAM include out-of-the-box.

To create your own authentication journey for use when testing the Ping (ForgeRock) SDKs, follow these steps:

The sample defaults to the journey names Login and Registration. Create or use a Login journey for authentication, and create a Registration journey if you want to test registration. If you use different names, set JOURNEY_LOGIN and JOURNEY_REGISTER to those names in the ReactJS application’s .env file.

  1. In your PingOne Advanced Identity Cloud tenant, navigate to Journeys, and click New Journey.

  2. Enter a name, such as sdkUsernamePasswordJourney and click Save.

    The authentication journey designer appears.

  3. Drag the following nodes into the designer area:

    • Page Node

    • Platform Username

    • Platform Password

    • Data Store Decision

  4. Drag and drop the Platform Username and Platform Password nodes onto the Page Node, so that they both appear on the same page when logging in.

  5. Connect the nodes as follows:

    sdk username password journey idcloud en
    Figure 1. Example username and password authentication journey

  6. Click Save.

Task 4. Register a public OAuth 2.0 client

Public clients do not use a client secret to obtain tokens because they are unable to keep them hidden. The Ping (ForgeRock) SDKs commonly use this type of client to obtain tokens, as they cannot guarantee safekeeping of the client credentials in a browser or on a mobile device.

To register a public OAuth 2.0 client application for use with the SDKs in PingOne Advanced Identity Cloud, follow these steps:

  1. Log in to your PingOne Advanced Identity Cloud tenant.

  2. In the left panel, click Applications.

  3. Click Custom Application.

  4. Select OIDC - OpenId Connect as the sign-in method, and then click Next.

  5. Select Native / SPA as the application type, and then click Next.

  6. In Name, enter a name for the application, such as Public SDK Client.

  7. In Owners, select a user that is responsible for maintaining the application, and then click Next.

    When trying out the SDKs, you could select the demo user you created previously.

  8. In Client ID, enter sdkPublicClient

  9. Select Configure for SDK Sample Apps.

  10. Click Create Application.

    PingOne Advanced Identity Cloud creates the application and displays the details screen.

  11. On the Sign On tab:

    1. In Sign-In URLs, ensure the following values appear, or add them if they don’t:

      https://localhost:8443/callback.html

      Also add any other domains where you host SDK applications.

    2. In Grant Types, ensure the following values appear:

      Authorization Code

      Refresh Token

    3. In Scopes, ensure the following values appear:

      openid profile email

  12. Click Show advanced settings, and on the Authentication tab, confirm the following properties:

    1. In Token Endpoint Authentication Method, select none.

    2. In Client Type, select Public.

    3. Enable the Implied Consent property.

  13. Click Save.

The application is now configured to accept client connections from and issue OAuth 2.0 tokens to the example applications and tutorials covered by this documentation.

Task 5. Register a confidential OAuth 2.0 client

Confidential clients are able to securely store credentials and are commonly used for server-to-server communication. For example, the "Todo" API backend provided with the SDK samples uses a confidential client to obtain tokens.

To register a confidential OAuth 2.0 client application for use with the SDKs in PingOne Advanced Identity Cloud, follow these steps:

  1. Log in to your PingOne Advanced Identity Cloud tenant.

  2. In the left panel, click Applications.

  3. Click Custom Application.

  4. Select OIDC - OpenId Connect as the sign-in method, and then click Next.

  5. Select Web as the application type, and then click Next.

  6. In Name, enter a name for the application, such as Confidential SDK Client.

  7. In Owners, select a user responsible for maintaining the application, and then click Next.

    When trying out the SDKs, you could select the demo user you created previously.

  8. On the Web Settings page:

    1. In Client ID, enter sdkConfidentialClient

    2. In Client Secret, enter a strong password and make a note of it for later use.

      For example, 5tr0ngP@S5w0rd!

      The client secret is not available to view after this step.

      If you forget it, you must reset the secret and reconfigure any connected clients.

    3. Click Create Application.

      PingOne Advanced Identity Cloud creates the application and displays the details screen.

  9. On the Sign On tab, In General Settings click Show advanced settings, and then select the Access tab:

    1. In Default Scopes, enter am-introspect-all-tokens.

  10. Click Save.

Task 6. Configure the OAuth 2.0 provider service

The provider specifies the supported OAuth 2.0 configuration options for a realm.

To ensure the PingOne Advanced Identity Cloud OAuth 2.0 provider service is configured for use with the Ping (ForgeRock) SDKs, follow these steps:

  1. In your PingOne Advanced Identity Cloud tenant, navigate to Native Consoles > Access Management.

  2. In the left panel, click Services.

  3. In the list of services, click OAuth2 Provider.

  4. On the Core tab, ensure Issue Refresh Tokens is enabled.

  5. On the Consent tab, ensure Allow Clients to Skip Consent is enabled.

  6. Click Save Changes.

PingAM

Authentication trees provide the equivalent functionality in PingAM that authentication journeys provide in PingOne Advanced Identity Cloud. The following tasks use the PingAM admin UI and refer to these resources as trees.

Task 1. Configure CORS

Cross-origin resource sharing (CORS) lets user agents make cross-domain server requests. In PingAM, you can configure CORS to allow browsers from trusted domains to access PingAM protected resources. For example, you might want a custom web application running on your own domain to get an end-user’s profile information using the PingAM REST API.

The Ping (ForgeRock) SDK for JavaScript samples and tutorials all use https://localhost:8443 as the host domain, which you should add to your CORS configuration.

For this Login Widget sample, also add http://localhost:9443 for the Todo API server when your CORS configuration requires it.

If you are using a different URL for hosting SDK applications, ensure you add them to the CORS configuration as accepted origin domains.

To enable CORS in PingAM, and create a CORS filter to allow requests from your configured domain names, follow these steps:

  1. Log in to the PingAM admin UI as an administrator.

  2. Navigate to Configure > Global Services > CORS Service > Configuration, and set the Enable the CORS filter property to true.

    If this property is not enabled, CORS headers are not added to responses from PingAM, and CORS is disabled entirely.

  3. On the Secondary Configurations tab, click Add a Secondary Configuration.

  4. In the Name field, enter OrchSDK.

  5. in the Accepted Origins field, enter any DNS aliases you use for your SDK apps.

    1. Add http://localhost:9443 for the Todo API server.

      This documentation assumes the following configuration:

      Property Values

      Accepted Origins

      https://localhost:8443

      http://localhost:9443

      Accepted Methods

      GET

      POST

      Accepted Headers

      content-type

      x-requested-with

      x-requested-platform

      accept-api-version

      authorization

      Exposed Headers

      authorization

      content-type

  6. Click Create.

    PingAM displays the configuration of your new CORS filter.

  7. On the CORS filter configuration page:

    1. Ensure Enable the CORS filter is enabled.

    2. Set the Max Age property to 600

    3. Ensure Allow Credentials is enabled.

  8. Click Save Changes.

Task 2. Create a demo user

The samples and tutorials in this documentation often require that you have an identity set up so that you can test authentication.

To create a demo user in PingAM, follow these steps:

  1. Log in to the PingAM admin UI as an administrator.

  2. Navigate to Identities, and then click Add Identity.

  3. Enter the following details:

    • User ID = demo

    • Password = Ch4ng3it!

    • Email Address = demo.user@example.com

  4. Click Create.

Task 3. Create an authentication tree

Authentication trees provide fine-grained authentication by allowing multiple paths and decision points throughout the authentication flow. Authentication trees are made up of nodes that define actions taken during authentication.

Each node performs a single task, such as collecting a username or making a simple decision. Nodes can have multiple outcomes rather than just success or failure.

To create a simple tree for use when testing the Ping (ForgeRock) SDKs, follow these steps:

The sample defaults to the tree names Login and Registration. Create or use a Login tree for authentication, and create a Registration tree if you want to test registration. If you use different names, set JOURNEY_LOGIN and JOURNEY_REGISTER to those names in the ReactJS application’s .env file.

  1. Under Realm Overview, click Authentication Trees, then click Create Tree.

  2. Enter a tree name, for example sdkUsernamePasswordJourney, and then click Create.

    The authentication tree designer appears, showing the Start entry point connected to the Failure exit point.

  3. Drag the following nodes from the Components panel on the left side into the designer area:

    • Page Node

    • Username Collector

    • Password Collector

    • Data Store Decision

  4. Drag and drop the Username Collector and Password Collector nodes onto the Page Node, so that they both appear on the same page when logging in.

  5. Connect the nodes as follows:

    trees node login example
    Figure 2. Example username and password authentication tree

  6. Select the Page Node, and in the Properties pane, set the Stage property to UsernamePassword.

    You can configure the node properties by selecting a node and altering properties in the right-hand panel.

    One of the samples uses this specific value to determine the custom UI to display.

  7. Click Save.

Task 4. Register a public OAuth 2.0 client

Public clients do not use a client secret to obtain tokens because they are unable to keep them hidden. The Ping (ForgeRock) SDKs commonly use this type of client to obtain tokens, as they cannot guarantee safekeeping of the client credentials in a browser or on a mobile device.

To register a public OAuth 2.0 client application for use with the SDKs in AM, follow these steps:

  1. Log in to the PingAM admin UI as an administrator.

  2. Navigate to Applications > OAuth 2.0 > Clients, and then click Add Client.

  3. In Client ID, enter sdkPublicClient.

  4. Leave Client secret empty.

  5. In Redirection URIs, enter the following values:

    https://localhost:8443/callback.html

    Also add any other domains where you will be hosting SDK applications.

  6. In Scopes, enter the following values:

    openid profile email

  7. Click Create.

    PingAM creates the new OAuth 2.0 client, and displays the properties for further configuration.

  8. On the Core tab:

    1. In Client type, select Public.

    2. Disable Allow wildcard ports in redirect URIs.

    3. Click Save Changes.

  9. On the Advanced tab:

    1. In Grant Types, enter the following values:

      Authorization Code
Refresh Token

    2. In Token Endpoint Authentication Method, select None.

    3. Enable the Implied consent property.

  10. Click Save Changes.

Task 5. Register a confidential OAuth 2.0 client

Confidential clients are able to store credentials securely and are commonly used for server-to-server communication.

To register a confidential OAuth 2.0 client application for use with the SDKs in AM, follow these steps:

  1. Log in to the PingAM admin UI as an administrator.

  2. Navigate to Applications > OAuth 2.0 > Clients, and then click Add Client.

  3. In Client ID, enter sdkConfidentialClient.

  4. In Client Secret, enter a strong password and make a note of it for later use.

    For example, 5tr0ngP@S5w0rd!

    The client secret is not available to view after this step.

    If you forget it, you must reset the secret and reconfigure any connected clients.

  5. In Default Scopes, enter am-introspect-all-tokens.

    PingAM creates the new OAuth 2.0 client and displays the properties for further configuration.

  6. On the Advanced tab:

    1. Enable the Implied consent property.

  7. Click Save Changes.

Task 6. Configure the OAuth 2.0 provider service

The provider specifies the supported OAuth 2.0 configuration options for a realm.

To ensure the PingAM OAuth 2.0 provider service is configured for use with the Ping (ForgeRock) SDKs, follow these steps:

  1. Log in to the PingAM admin UI as an administrator.

  2. In the left panel, click Services.

  3. In the list of services, click OAuth2 Provider.

  4. On the Core tab, ensure Issue Refresh Tokens is enabled.

  5. On the Consent tab, ensure Allow Clients to Skip Consent is enabled.

  6. Click Save Changes.

Next

Next, you can download the sample repository.