PingGateway 2024.9

PingOne as OIDC provider

This example sets up PingOne as an OIDC provider with PingGateway as a relying party.

Prepare PingOne

After you prepare the PingOne environment and test user, follow these steps to create a PingOne OIDC web application:

  1. In the test environment, create a web application with the following values:

    • Application Name: oidc_client

    • Description: OIDC client

    • Application Type: OIDC Web App

  2. In the application, select the Overview panel and click Protocol OpenID Connect.

  3. In the Redirect URIs field, add https://ig.example.com:8443/home/id_token/callback and save the application.

  4. In the Overview panel, click Resource Access, select the email and profile scopes in addition to the default openid scope, and click Save.

    Learn more from the PingOne documentation on Editing an application - OIDC.

  5. At the top-right of the page, click the slider to enable the application.

  6. Go to the Configuration panel and make a note of the following values in the URLs drop-down list:

    • OIDC Discovery Endpoint

    • Client ID

    • Client Secret

    You need the values to set up PingGateway.

Prepare PingGateway

  1. Add the following basic PingGateway configuration if you have not already done so:

    1. Set up PingGateway for HTTPS, as described in Configure PingGateway for TLS (server-side).

    2. Add the following route to PingGateway to serve the sample application .css and other static resources:

      • Linux

      • Windows

      $HOME/.openig/config/routes/00-static-resources.json
      %appdata%\OpenIG\config\routes\00-static-resources.json
      {
  "name" : "00-static-resources",
  "baseURI" : "http://app.example.com:8081",
  "condition": "${find(request.uri.path,'^/css') or matchesWithRegex(request.uri.path, '^/.*\\\\.ico$') or matchesWithRegex(request.uri.path, '^/.*\\\\.gif$')}",
  "handler": "ReverseProxyHandler"
}

  2. Base64-encode the OIDC application’s Client Secret and set the value as an environment variable:

    $ export OIDC_SECRET_ID='<base64-encoded-client-secret>'

  3. Add the following route to PingGateway, replacing the following property values with those of the OIDC application:

    • OIDC_Discovery_Endpoint: The OIDC discovery endpoint for the client application you registered.

    • Client_ID: The client ID of the application.

      • Linux

      • Windows

      $HOME/.openig/config/routes/oidc-ping.json
      %appdata%\OpenIG\config\routes\oidc-ping.json
      {
  "name": "oidc-ping",
  "condition": "${find(request.uri.path, '^/home/id_token')}",
  "properties": {
    "OIDC_Discovery_Endpoint": "OIDC Discovery endpoint of the web app",
    "Client_ID": "Client ID of the web app"
  },
  "heap": [
    {
      "name": "SystemAndEnvSecretStore-1",
      "type": "SystemAndEnvSecretStore"
    },
    {
      "name": "AuthenticatedRegistrationHandler-1",
      "type": "Chain",
      "config": {
        "filters": [
          {
            "name": "ClientSecretBasicAuthenticationFilter-1",
            "type": "ClientSecretBasicAuthenticationFilter",
            "config": {
              "clientId": "&{Client_ID}",
              "clientSecretId": "oidc.secret.id",
              "secretsProvider": "SystemAndEnvSecretStore-1"
            }
          }
        ],
        "handler": "ForgeRockClientHandler"
      }
    }
  ],
  "handler": {
    "type": "Chain",
    "config": {
      "filters": [
        {
          "name": "AuthorizationCodeOAuth2ClientFilter-1",
          "type": "AuthorizationCodeOAuth2ClientFilter",
          "config": {
            "clientEndpoint": "/home/id_token",
            "failureHandler": {
              "type": "StaticResponseHandler",
              "config": {
                "status": 500,
                "headers": {
                  "Content-Type": [
                    "text/html; charset=UTF-8"
                  ]
                },
                "entity": "<html><body>Error in OAuth 2.0 setup.<br> ${contexts.oauth2Failure.exception.message}</body></html>"
              }
            },
            "registrations": [
              {
                "name": "oauth2-client",
                "type": "ClientRegistration",
                "config": {
                  "clientId": "${Client_ID}",
                  "issuer": {
                    "name": "PingOne",
                    "type": "Issuer",
                    "config": {
                      "wellKnownEndpoint": "&{OIDC_Discovery_Endpoint}"
                    }
                  },
                  "scopes": [
                    "openid",
                    "profile",
                    "email"
                  ],
                  "authenticatedRegistrationHandler": "AuthenticatedRegistrationHandler-1"
                }
              }
            ],
            "requireHttps": false,
            "cacheExpiration": "disabled"
          }
        }
      ],
      "handler": {
        "type": "StaticResponseHandler",
        "name": "HTMLResponse",
        "config": {
          "status": 200,
          "entity": "<!DOCTYPE html><html><head><title>Authentication Success</title></head><body><p>Welcome, ${attributes.openid.user_info.preferred_username}!</p><code>${attributes.openid.user_info}</code></body></html>",
          "headers": {
            "Content-Type": [
              "text/html"
            ]
          }
        }
      }
    }
  }
}

  4. Restart PingGateway.

Validation

  1. In your browser’s privacy or incognito mode, go to https://ig.example.com:8443/home/id_token.

    PingOne displays the sign-on page.

  2. Sign on to PingOne as the test user.

    The route displays a welcome page:

    Welcome, wolkig!

{sub=..., preferred_username=wolkig, given_name=Wilhelm, updated_at=..., family_name=Wolkig, email=wolkig@example.com, ...}