PingOne

This guide illustrates how to configure IBM Application Gateway (IAG) as an OIDC relying party for PingOne.

This guide was written in October 2023, the steps below may change if a third-party provider modifies their administrative interfaces.

Pre-requisites

Review the Third-Party Providers documentation for high-level information about using IAG with third-party identity providers.
An active PingOne subscription. A trial account with a Workforce Solution Environment can be used.

Reference Resources

The following PingOne documentation was used to prepare these configuration instructions:

Configuration

PingOne Configuration Steps

Browse to Connections > Applications and click + to add an Application. Complete the Application Name field, set the Application Type to OIDC Web App, and click Save.

The application must be enabled before it can be used by toggling the enable switch. Browse to the Overview tab and note the Client ID and Client Secret value.

In IAG, the Client ID is used in the client_id field, and the Client Secret is used in the client_secret field.

The generated Client ID and Client Secret values in this example are:

client_id c5683508-acee-4435-a871-2b7a19c86610
clientsecret `zF57tApDDikZqg7Zj2kMARYHkzvr1cenWdBt.tq8~xw-haIjXqZ0EuAgLodxRZD`

The configuration for the application must be updated to include the IAG redirect URI. To edit the application configuration, on the Overview tab click Protocol OpenID Connect to open the Edit Configuration window. Complete the Redirect URIs field and click Save. None of the other parameters on the Edit Configuration window need to be updated.

The Redirect URI is of the format https://<iag>/pkmsoidc.

The OIDC metadata URL for PingOne is documented as part of the PingOne Platform API Reference. In IAG, this is the discovery_endpoint value.

This URL is a combination of:

A region-specific authPath URL, established when the PingOne subscription is created.
The Environment ID, which is retrieved from the application's Overview tab.

The authPath of the subscription that is used in this example scenario is https://auth.pingone.asia. The Environment ID of the application that was created in this example scenario is 43e8fbac-657d-4583-a8dc-cb0d7fea1ec8.

The format of the OIDC metadata URL is <authPath>/<Environment ID>/as/.well-known/openid-configuration.

In this example scenario, the complete OIDC metadata URL is https://auth.pingone.asia/43e8fbac-657d-4583-a8dc-cb0d7fea1ec8/as/.well-known/openid-configuration.

IAG Configuration Steps

Using the values retrieved in the previous steps, complete the IAG configuration. The sample configuration contains enough information to allow IAG to perform single sign-on with PingOne.

identity:
  oidc:
    discovery_endpoint: "https://auth.pingone.asia/43e8fbac-657d-4583-a8dc-cb0d7fea1ec8/as/.well-known/openid-configuration"
    client_id:          "c5683508-acee-4435-a871-2b7a19c86610"
    client_secret:      "zF57tApDDikZqg7Zj2kMARYHkzvr1cenWdBt_.tq8~xw-haIjXqZ0EuAgLodxRZD"
    scopes:
      - "email"
      - "profile"
    ssl:
      certificate:
        - "@pingone_ca.pem"

The sample configuration contains a identity/oidc/ssl/certificate entry. This is an optional part of IAG's OIDC configuration, and is required for PingOn as the default CA certificates provided with IAG do not contain the trusted root signer CAs in use at the PingOne metadata and token endpoints. They must be added manually.

To retrieve the certificate data, browse to the OIDC metadata URL and downloaded the root and intermediate CA certificates. The PEM formatted root and intermediate certificates are concatenated together into a single file named pingone_ca.pem. At the time of writing, the content of pingone_ca.pem is:

This technique helps ensure that IAG is connecting to trusted OIDC provider server URLs. If the required TLS server signer certificates are not known to IAG, the IAG log produces an error message when an attempt is made to retrieve the metadata URL.

DPWIV1228W   IAG could not establish a secure connection to the server, auth.pingone.asia, for the default junction (Function call: gsk_secure_soc_init; failed error: 0x19e GSK_ERROR_BAD_CERT).
2023-10-05-03:34:14.234+00:00I----- 0x38983425 iag ERROR wad general AMWJsonClient.cpp 706 0xffffae14e1c0
DPWAD1061E   Failed to connect to the server: auth.pingone.asia:443.

For more information, see Certificate Management.

Extra Configuration

Supplying extra user attributes in the id_token

A protected application often requires extra user attributes from the third-party identity provider. The user attributes need to be propagated to IAG as claims in the id_token.

To configure extra attributes in PingOne, browse to the Attribute Mappings tab and then click Add. Complete the Attributes field and select the appropriate PingOne Mapping for the attribute. Click Save once all required attributes are added.

This example illustrates adding the email and preferred_username attributes.

Testing the PingOne Integration

To test the configuration:

Browse to the IAG credential viewer application. For more information, see Common IAG Configuration for information about this URL. In this example, the URL is https://www.mysp.ibm.com:8443/ivcreds.

The browser is redirected to PingOne for authentication. The browser will be returned to the credential viewer application after authentication is completed.

The credential viewer application is displayed. Observe that the configured id_token attributes (see Supplying extra user attributes in the id_token) are displayed.