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

  1. Review the Third-Party Providers documentation for high-level information about using IAG with third-party identity providers.
  2. 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.

1379

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.

1379

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.

602

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:

-----BEGIN CERTIFICATE-----
MIIDQTCCAimgAwIBAgITBmyfz5m/jAo54vB4ikPmljZbyjANBgkqhkiG9w0BAQsF
ADA5MQswCQYDVQQGEwJVUzEPMA0GA1UEChMGQW1hem9uMRkwFwYDVQQDExBBbWF6
b24gUm9vdCBDQSAxMB4XDTE1MDUyNjAwMDAwMFoXDTM4MDExNzAwMDAwMFowOTEL
MAkGA1UEBhMCVVMxDzANBgNVBAoTBkFtYXpvbjEZMBcGA1UEAxMQQW1hem9uIFJv
b3QgQ0EgMTCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBALJ4gHHKeNXj
ca9HgFB0fW7Y14h29Jlo91ghYPl0hAEvrAIthtOgQ3pOsqTQNroBvo3bSMgHFzZM
9O6II8c+6zf1tRn4SWiw3te5djgdYZ6k/oI2peVKVuRF4fn9tBb6dNqcmzU5L/qw
IFAGbHrQgLKm+a/sRxmPUDgH3KKHOVj4utWp+UhnMJbulHheb4mjUcAwhmahRWa6
VOujw5H5SNz/0egwLX0tdHA114gk957EWW67c4cX8jJGKLhD+rcdqsq08p8kDi1L
93FcXmn/6pUCyziKrlA4b9v7LWIbxcceVOF34GfID5yHI9Y/QCB/IIDEgEw+OyQm
jgSubJrIqg0CAwEAAaNCMEAwDwYDVR0TAQH/BAUwAwEB/zAOBgNVHQ8BAf8EBAMC
AYYwHQYDVR0OBBYEFIQYzIU07LwMlJQuCFmcx7IQTgoIMA0GCSqGSIb3DQEBCwUA
A4IBAQCY8jdaQZChGsV2USggNiMOruYou6r4lK5IpDB/G/wkjUu0yKGX9rbxenDI
U5PMCCjjmCXPI6T53iHTfIUJrU6adTrCC2qJeHZERxhlbI1Bjjt/msv0tadQ1wUs
N+gDS63pYaACbvXy8MWy7Vu33PqUXHeeE6V/Uq2V8viTO96LXFvKWlJbYK8U90vv
o/ufQJVtMVT8QtPHRh8jrdkPSHCa2XV4cdFyQzR1bldZwgJcJmApzyMZFo6IQ6XU
5MsI+yMRQ+hDKXJioaldXgjUkK642M4UwtBV8ob2xJNDd2ZhwLnoQdeXeGADbkpy
rqXRfboQnoZsG4q5WTP468SQvvG5
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
MIIEXjCCA0agAwIBAgITB3MSSkvL1E7HtTvq8ZSELToPoTANBgkqhkiG9w0BAQsF
ADA5MQswCQYDVQQGEwJVUzEPMA0GA1UEChMGQW1hem9uMRkwFwYDVQQDExBBbWF6
b24gUm9vdCBDQSAxMB4XDTIyMDgyMzIyMjUzMFoXDTMwMDgyMzIyMjUzMFowPDEL
MAkGA1UEBhMCVVMxDzANBgNVBAoTBkFtYXpvbjEcMBoGA1UEAxMTQW1hem9uIFJT
QSAyMDQ4IE0wMjCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBALtDGMZa
qHneKei1by6+pUPPLljTB143Si6VpEWPc6mSkFhZb/6qrkZyoHlQLbDYnI2D7hD0
sdzEqfnuAjIsuXQLG3A8TvX6V3oFNBFVe8NlLJHvBseKY88saLwufxkZVwk74g4n
WlNMXzla9Y5F3wwRHwMVH443xGz6UtGSZSqQ94eFx5X7Tlqt8whi8qCaKdZ5rNak
+r9nUThOeClqFd4oXych//Rc7Y0eX1KNWHYSI1Nk31mYgiK3JvH063g+K9tHA63Z
eTgKgndlh+WI+zv7i44HepRZjA1FYwYZ9Vv/9UkC5Yz8/yU65fgjaE+wVHM4e/Yy
C2osrPWE7gJ+dXMCAwEAAaOCAVowggFWMBIGA1UdEwEB/wQIMAYBAf8CAQAwDgYD
VR0PAQH/BAQDAgGGMB0GA1UdJQQWMBQGCCsGAQUFBwMBBggrBgEFBQcDAjAdBgNV
HQ4EFgQUwDFSzVpQw4J8dHHOy+mc+XrrguIwHwYDVR0jBBgwFoAUhBjMhTTsvAyU
lC4IWZzHshBOCggwewYIKwYBBQUHAQEEbzBtMC8GCCsGAQUFBzABhiNodHRwOi8v
b2NzcC5yb290Y2ExLmFtYXpvbnRydXN0LmNvbTA6BggrBgEFBQcwAoYuaHR0cDov
L2NydC5yb290Y2ExLmFtYXpvbnRydXN0LmNvbS9yb290Y2ExLmNlcjA/BgNVHR8E
ODA2MDSgMqAwhi5odHRwOi8vY3JsLnJvb3RjYTEuYW1hem9udHJ1c3QuY29tL3Jv
b3RjYTEuY3JsMBMGA1UdIAQMMAowCAYGZ4EMAQIBMA0GCSqGSIb3DQEBCwUAA4IB
AQAtTi6Fs0Azfi+iwm7jrz+CSxHH+uHl7Law3MQSXVtR8RV53PtR6r/6gNpqlzdo
Zq4FKbADi1v9Bun8RY8D51uedRfjsbeodizeBB8nXmeyD33Ep7VATj4ozcd31YFV
fgRhvTSxNrrTlNpWkUk0m3BMPv8sg381HhA6uEYokE5q9uws/3YkKqRiEz3TsaWm
JqIRZhMbgAfp7O7FUwFIb7UIspogZSKxPIWJpxiPo3TcBambbVtQOcNRWz5qCQdD
slI2yayq0n2TXoHyNCLEH8rpsJRVILFsg0jc7BaFrMnF462+ajSehgj12IidNeRN
4zl+EoNaWdpnWndvSpAEkq2P
-----END CERTIFICATE-----

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.

1379

Testing the PingOne Integration

To test the configuration:

  1. 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.
972
  1. The browser is redirected to PingOne for authentication. The browser will be returned to the credential viewer application after authentication is completed.
395
  1. The credential viewer application is displayed. Observe that the configured id_token attributes (see Supplying extra user attributes in the id_token) are displayed.
748