Ping (ForgeRock) SDKs

Configure your Authorization Server

You need to set up your PingOne Advanced Identity Cloud or PingAM instance with an OAuth 2.0 client and suitable CORS configuration.

Configure an OAuth 2.0 client

Follow the instructions below to create the public OAuth 2.0 client the Token Vault requires:

PingOne Advanced Identity Cloud

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, and then click Create Application.

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

  9. On the Sign On tab:

    1. In Sign-In URLs, enter the following values:

      Also add any other domains where you host SDK applications.

    2. In Grant Types, enter the following values:

      Authorization Code

      Refresh Token

    3. In Scopes, enter the following values:

      openid profile email address

  10. Click Show advanced settings, and on the Authentication tab:

    1. In Token Endpoint Authentication Method, select none.

    2. In Client Type, select Public.

    3. Enable the Implied Consent property.

  11. 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.

Self-managed PingAM server

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.

In addition to the instructions above, perform the following steps:

  1. Add the fully-qualified URL where you will host the Token Vault Proxy.

    For example, https://proxy.example.com, or when testing locally http://localhost:5175.

    Add this value to either the Redirection URIs (self-managed PingAM) or the Sign-in URLs (PingOne Advanced Identity Cloud) property.

In Advanced Identity Cloud and PingAM, adding a sign-in URL to an OAuth 2.0 client automatically adds the relevant origin URLs to the client’s JavaScript Origins property.

The server collects values from that property into the list of accepted CORS origins, so an entry there grants CORS access even if it is absent from the CORS configuration.

To check that your application’s origin does not appear in the JavaScript Origins property:

  1. If you are using Advanced Identity Cloud, in the admin console, navigate to Native Consoles > Access Management.

  2. In the native PingAM console, click OAuth2 Clients, and select your client ID.

  3. On the Advanced tab, check the JavaScript Origins property.

    If your main application’s origin is present, remove it, and save your changes.

  1. Enable refresh tokens in your authorization server:

    1. Add refresh_token to either the Advanced > Response Types (self-managed PingAM) or the Access > Response Types (PingOne Advanced Identity Cloud) property.

    2. Ensure Refresh Token is added to either the Advanced > Grant Types (self-managed PingAM) or the Sign On > Grant Types (PingOne Advanced Identity Cloud) property.

    Generally, we do not recommend the use of OAuth 2.0 refresh tokens with typical web-based applications, but using the Token Vault mitigates a number of the security concerns with using refresh tokens, so they can be enabled to allow refreshing the access tokens without user intervention.

Configure CORS

Follow the instructions below to configure CORS to allow the Token Vault to connect to your server:

PingOne Advanced Identity Cloud

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 a Token Vault deployment, only the origin where you host your Token Vault Proxy should be able to contact PingOne Advanced Identity Cloud directly from a browser.

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 (ForgeRock) SDK, and then click Next.

  5. Add the origin where you will host your Token Vault Proxy, and any DNS aliases of that origin, to the Accepted Origins property.

    Do not add your main application’s origin here, or in the OAuth 2.0 client’s JavaScript Origins property.

In Advanced Identity Cloud and PingAM, adding a sign-in URL to an OAuth 2.0 client automatically adds the relevant origin URLs to the client’s JavaScript Origins property.

The server collects values from that property into the list of accepted CORS origins, so an entry there grants CORS access even if it is absent from the CORS configuration.

To check that your application’s origin does not appear in the JavaScript Origins property:

  1. If you are using Advanced Identity Cloud, in the admin console, navigate to Native Consoles > Access Management.

  2. In the native PingAM console, click OAuth2 Clients, and select your client ID.

  3. On the Advanced tab, check the JavaScript Origins property.

    If your main application’s origin is present, remove it, and save your changes.

  1. Complete the remaining fields to suit your environment.

    This documentation assumes the following configuration:

Property Values

Accepted Origins

https://proxy.example.com (the Token Vault Proxy origin)

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.

  1. Click Save CORS Configuration.

Self-managed PingAM server

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 a Token Vault deployment, only the origin where you host your Token Vault Proxy should be able to contact PingAM directly from a browser.

To enable CORS in PingAM, and create a CORS filter to allow requests from your Token Vault Proxy origin, 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 origin where you will host your Token Vault Proxy, plus any DNS aliases of that proxy origin.

    Do not add your main application’s origin here, or in the OAuth 2.0 client’s JavaScript Origins property.

In Advanced Identity Cloud and PingAM, adding a sign-in URL to an OAuth 2.0 client automatically adds the relevant origin URLs to the client’s JavaScript Origins property.

The server collects values from that property into the list of accepted CORS origins, so an entry there grants CORS access even if it is absent from the CORS configuration.

To check that your application’s origin does not appear in the JavaScript Origins property:

  1. If you are using Advanced Identity Cloud, in the admin console, navigate to Native Consoles > Access Management.

  2. In the native PingAM console, click OAuth2 Clients, and select your client ID.

  3. On the Advanced tab, check the JavaScript Origins property.

    If your main application’s origin is present, remove it, and save your changes.

+ This documentation assumes the following configuration:

+

Property Values

Accepted Origins

https://proxy.example.com (the Token Vault Proxy origin)

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

  1. Click Create.

    PingAM displays the configuration of your new CORS filter.

  2. 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.

  3. Click Save Changes.

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.