Ping SDKs

Part 1. Configuring your PingAM server or PingOne Advanced Identity Cloud tenant

In this section you configure your PingAM server or PingOne Advanced Identity Cloud tenant with an OAuth 2.0 client to accept connections from the sample client apps.

The OAuth 2.0 client also contains the configuration to redirect your users to authenticate using the custom UI sample app running on your local IP address.

Lastly, you configure Cross-origin Resource Sharing (CORS) to allow the sample UI app, and the client JavaScript app to connect to protected endpoints.

Step 1. Configure an OAuth 2.0 client

The initial request to authenticate a user from your client application requires an OAuth 2.0 client is setup.

This client also contains the configuration for your custom UI application. This means that you can have different UI applications for different clients, allowing you to apply different branding to each.

In this step you configure a suitable OAuth 2.0 client in either your PingAM server of PingOne Advanced Identity Cloud tenant, by using the Access Management native console.

How to open the native console in an PingOne Advanced Identity Cloud tenant

If you are using an PingOne Advanced Identity Cloud tenant, follow these steps to open the Access Management native console:

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

  2. Navigate to Native Consoles > Access Management.

In the Access Management native console, complete these steps to register an OAuth 2.0 client for this tutorial:

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

  2. On the New OAuth 2.0 Client page:

    1. In Client ID, enter an identifier for the client.

      For example, sdkCustomUI

    2. In Redirection URIs, enter the URIs that will be hosting your client applications.

      • Add the DNS alias you created earlier for the JavaScript sample client app:

        https://sdkapp.example.com:8443

      • If you want to test your setup with the Android or iOS sample apps, also add the following:

        org.forgerock.demo://oauth2redirect

  3. In Scopes, enter each of the following:

    • openid

    • profile

    • email

    • phone

    • address

  4. Click Create.

    The authorization server creates the client and navigates to the edit page for it.

  5. On the Core tab:

    1. In Client type, select Public.

    2. Click Save Changes.

      You must click Save Changes before changing tabs otherwise the page discards any changes you made on the tab.

  6. On the Advanced tab:

    1. In Token Endpoint Authentication Method, select none.

    2. Set Implied Consent to Enabled.

    3. Click Save Changes.

  7. On the OAuth2 Provider Overrides tab:

    1. Set Enable OAuth2 Provider Overrides to Enabled.

    2. In Custom Login URL Template, enter the URL of the custom UI application, followed by the query parameters required to navigate between the client, custom UI, and authorization server.

      For this tutorial, use the local IP address of your computer that you obtained earlier, and the port number you configured for the custom UI sample app (9443):

      https://192.168.0.35:9443?goto=${goto}<#if acrValues??>&acr_values=${acrValues}</#if><#if realm??>&realm=${realm}</#if><#if module??>&module=${module}</#if><#if service??>&service=${service}</#if><#if locale??>&locale=${locale}</#if>

    3. Set Use Client-Side Access & Refresh Tokens to Enabled.

    4. Set Allow Clients to Skip Consent to Enabled

    5. Click Save Changes.

You have now configured the OAuth 2.0 client to issue tokens to your client applications, and redirect login requests to your custom UI application.

Step 2. Configure CORS

Cross-origin resource sharing (CORS) lets user agents make cross-domain server requests. Configure CORS to allow browsers from trusted addresses to access your protected resources.

For this tutorial you configure CORS to allow the client JavaScript application to access OAuth 2.0 endpoints, and the custom UI application to access your authentication journeys.

To configure CORS, select your authorization server:

  • PingOne Advanced Identity Cloud

  • PingAM

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 available, click ForgeRockSDK.

    • If you haven’t added any CORS configurations to the tenant, click Add a CORS Configuration, select Ping SDK, and then click Next.

  5. Add the IP addresses and port numbers of where you are hosting the custom UI app and the client sample app to the Accepted Origins property.

  6. Complete the remaining fields to suit your environment.

    An example configuration for this tutorial is as follows:

    Property

    Values

    https://sdkapp.example.com:8443

    https://192.168.0.35:9443

    Accepted Methods

    GET

    POST

    Accepted Headers

    accept-api-version

    x-requested-with

    content-type

    authorization

    if-match

    x-requested-platform

    iPlanetDirectoryPro [1]

    ch15fefc5407912 [2]

    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.

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 Click Add a Secondary Configuration.

  4. In the Name field, enter ForgeRockSDK.

  5. In the Accepted Origins field, enter the IP addresses and port numbers of where you are hosting the custom UI app and the client sample app.

    An example configuration for this tutorial is as follows:

    Property

    Values

    https://sdkapp.example.com:8443

    https://192.168.0.35:9443

    Accepted Methods

    GET

    POST

    Accepted Headers

    accept-api-version

    x-requested-with

    content-type

    authorization

    if-match

    x-requested-platform

    iPlanetDirectoryPro [1]

    ch15fefc5407912 [2]

    Exposed Headers

    authorization

    content-type

    Enable Caching

    True

    Max Age

    600

    Allow Credentials

    True

  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.

You are now ready to configure and run the sample JavaScript app to act as the custom UI.

1. Cookie name value in PingAM servers.
2. In PingOne Advanced Identity Cloud tenants, go to Tenant Settings > Global Settings > Cookie to find this dynamic cookie name value.