Untitled | ForgeRock Identity Gateway

PingOne Advanced Identity Cloud

This guide provides examples of how to use PingGateway with PingOne Advanced Identity Cloud for Single Sign-On and API Security. It is for PingOne Advanced Identity Cloud evaluators, administrators, and architects.

Example installation for this guide

Unless otherwise stated, the examples in this guide assume the following installation:

PingGateway installed on http://ig.example.com:8080, as described in the Install .
Sample application installed on http://app.example.com:8081, as described in Use the sample application.
An PingOne Advanced Identity Cloud tenant with the default configuration, as described in the PingOne Advanced Identity Cloud documentation.

When using PingOne Advanced Identity Cloud, you need to know the value of the following properties:

The root URL of your PingOne Advanced Identity Cloud tenant. For example, https://myTenant.forgeblocks.com.

The URL of the PingAM component of PingOne Advanced Identity Cloud is the root URL of your PingOne Advanced Identity Cloud tenant followed by /am. For example, https://myTenant.forgeblocks.com/am.
The realm where you work. The examples in this document use alpha.

Prefix each realm in the hierarchy with the realms keyword. For example, /realms/root/realms/alpha.

If you use a different configuration, substitute in the procedures accordingly.

Authenticate a PingGateway agent to PingOne Advanced Identity Cloud

PingGateway agents are automatically authenticated to PingOne Advanced Identity Cloud by a non-configurable authentication module. Authentication chains and modules are deprecated in PingOne Advanced Identity Cloud and replaced by journeys.

You can now authenticate PingGateway agents to PingOne Advanced Identity Cloud with a journey. The procedure is currently optional, but will be required when authentication chains and modules are removed in a future release of PingOne Advanced Identity Cloud.

For more information, refer to PingOne Advanced Identity Cloud’s Journeys.

This section describes how to create a journey to authenticate an PingGateway agent to PingOne Advanced Identity Cloud. The journey has the following requirements:

It must be called Agent
Its nodes must pass the agent credentials to the Agent Data Store Decision node.

When you define a journey in PingOne Advanced Identity Cloud, that same journey is used for all instances of PingGateway, Java agent, and Web agent. Consider this point if you change the journey configuration.

Log in to the PingOne Advanced Identity Cloud admin UI as an administrator.
Click Journeys > New Journey.
Add a journey with the following information and click Create journey:
- Name: Agent
- Identity Object: The user or device to authenticate.
- (Optional) Description: Authenticate a PingGateway agent to PingOne Advanced Identity Cloud
The journey designer is displayed, with the Start entry point connected to the Failure exit point, and a Success node.
Using the Filter nodes bar, find and then drag the following nodes from the Components panel into the designer area:
- Zero Page Login Collector node to check whether the agent credentials are provided in the incoming authentication request, and use their values in the following nodes.
  
  This node is required for compatibility with Java agent and Web agent.
- Page node to collect the agent credentials if they are not provided in the incoming authentication request, and use their values in the following nodes.
- Agent Data Store Decision node to verify the agent credentials match the registered PingGateway agent profile.
Many nodes can be configured in the panel on the right side of the page. Unless otherwise stated, do not configure the nodes, and use only the default values.
Drag the following nodes from the Components panel into the Page node:
- Platform Username node to prompt the user to enter their username.
- /auth-node-ref/latest/auth-node-platform-password.html[Platform Password] node to prompt the user to enter their password.
Connect the nodes as follows and save the journey:

Register a PingGateway agent in PingOne Advanced Identity Cloud

This procedure registers an agent that acts on behalf of PingGateway.

Log in to the PingOne Advanced Identity Cloud admin UI as an administrator.
Click verified_user Gateways & Agents > New Gateway/Agent > Identity Gateway > Next, and add an agent profile:
- ID: agent-name
- Password: agent-password
- Redirect URLs: URL for CDSSO
Use secure passwords in a production environment. Consider using a password manager to generate secure passwords.
Click Save Profile > Done. The agent profile page is displayed.

Click open_in_new Native Consoles > Access Management and make the following optional changes in the AM admin UI.

Change Action

Change	Action
Store the agent password in AM’s secret service.	Set a Secret Label Identifier, and configure a mapping to the corresponding secret. If AM finds a matching secret in a secret store, it uses that secret instead of the agent password configured in Step 2. The secret label has the format `am.application.agents.identifier.secret`, where identifier is the Secret Label Identifier. The Secret Label Identifier can contain only characters `a-z`, `A-Z`, `0-9`, and periods (`.`). It can’t start or end with a period. Note the following points: Set a Secret Label Identifier that clearly identifies the agent. If you update or delete the Secret Label Identifier, AM updates or deletes the corresponding mapping for the previous identifier provided no other agent shares the mapping. When you rotate a secret, update the corresponding mapping.
Direct login to a custom URL instead of the default AM login page.	Configure Login URL Template for CDSSO.
Apply a different introspection scope.	Click Token Introspection and select a scope from the drop-down list.

Store the agent password in AM’s secret service.

Set a Secret Label Identifier, and configure a mapping to the corresponding secret. If AM finds a matching secret in a secret store, it uses that secret instead of the agent password configured in Step 2.

The secret label has the format am.application.agents.identifier.secret, where identifier is the Secret Label Identifier.

The Secret Label Identifier can contain only characters a-z, A-Z, 0-9, and periods (.). It can’t start or end with a period.

Note the following points:

Set a Secret Label Identifier that clearly identifies the agent.
If you update or delete the Secret Label Identifier, AM updates or deletes the corresponding mapping for the previous identifier provided no other agent shares the mapping.
When you rotate a secret, update the corresponding mapping.

Direct login to a custom URL instead of the default AM login page.

Configure Login URL Template for CDSSO.

Apply a different introspection scope.

Click Token Introspection and select a scope from the drop-down list.

Set up a demo user in PingOne Advanced Identity Cloud

This procedure sets up a demo user in the alpha realm.

Log in to the PingOne Advanced Identity Cloud admin UI as an administrator.
Go to group Identities > Manage > settings_system_daydream Alpha realm - Users, and add a user with the following values:
- Username: demo
- First name: demo
- Last name: user
- Email Address: demo@example.com
- Password: Ch4ng3!t

Recommendations

Use PingGateway with PingOne Advanced Identity Cloud as you would with any other service.

During updates, individual PingOne Advanced Identity Cloud tenant servers go offline temporarily. PingGateway can receive HTTP 502 Bad Gateway responses for some requests during the update.

In your ClientHandler and ReverseProxyHandler configurations, configure PingGateway to retry operations when this occurs:
```
"retries": {
    "enabled": true,
    "condition": "${response.status.code == 502}"
}
```
json
Update PingGateway to use the latest version you can to benefit from fixes and improvements.

About PingGateway and PingOne Advanced Identity Cloud

PingOne Advanced Identity Cloud simplifies the consumption of ForgeRock as an Identity Platform. However, many organizations have business web applications and APIs deployed across multiple clouds, or on-premise.

PingGateway facilitates non-intrusive integration of your web applications and APIs with PingOne Advanced Identity Cloud, for SSO and API Security. The following image illustrates how PingGateway bridges your business to PingOne Advanced Identity Cloud:

PingGateway bridges business applications and APIs to PingOne Advanced Identity Cloud.

Learn more about PingOne Advanced Identity Cloud from the PingOne Advanced Identity Cloud documentation.

OAuth 2.0

This example sets up OAuth 2.0, using the standard introspection endpoint, where PingOne Advanced Identity Cloud is the Authorization Server and PingGateway is the resource server.

For more information about PingGateway as an OAuth 2.0 resource server, refer to Validate access tokens through the introspection endpoint.

This procedure uses the Resource Owner Password Credentials grant type. According to information in the The OAuth 2.0 Authorization Framework, minimize use of this grant type and utilize other grant types whenever possible.

Before you start, prepare PingOne Advanced Identity Cloud, PingGateway, and the sample application as described in Example installation for this guide.

Set up PingOne Advanced Identity Cloud:

Log in to the PingOne Advanced Identity Cloud admin UI as an administrator.
Make sure you are managing the alpha realm. If not, click the current realm at the top of the screen, and switch realm.
Go to group Identities > Manage > settings_system_daydream Alpha realm - Users, and add a user with the following values:
- Username: demo
- First name: demo
- Last name: user
- Email Address: demo@example.com
- Password: Ch4ng3!t
Go to Applications > CustomApplication > OIDC - OpenId Connect > Web and add a web application with the following values:
- Name: oauth2-client
- Owners: demo user
- Client Secret: password
- Sign On > Grant Types: Authorization Code, Resource owner Password Credentials
- Sign On > Scopes: mail
  
  For more information, refer to PingOne Advanced Identity Cloud’s Application management.
Register a PingGateway agent with the following values, as described in Register a PingGateway agent in PingOne Advanced Identity Cloud:
- ID: ig_agent
- Password: password

(Optional) Authenticate a PingGateway agent to PingOne Advanced Identity Cloud.

PingGateway agents are automatically authenticated to PingOne Advanced Identity Cloud by a deprecated authentication module in PingOne Advanced Identity Cloud. This step is currently optional, but will be required when authentication chains and modules are removed in a future release of PingOne Advanced Identity Cloud.

Set up PingGateway:

Set up PingGateway for HTTPS, as described in Configure PingGateway for TLS (server-side).
Set an environment variable for the PingGateway agent password, and then restart PingGateway:
```
$ export AGENT_SECRET_ID='cGFzc3dvcmQ='
```
bash
The password is retrieved by a SystemAndEnvSecretStore, and must be base64-encoded.

Add the following route to PingGateway, replacing the value for the property amInstanceUrl:

Linux
Windows

$HOME/.openig/config/routes/oauth2rs-idc.json

%appdata%\OpenIG\config\routes\oauth2rs-idc.json

{
  "name": "oauth2rs-idc",
  "baseURI": "http://app.example.com:8081",
  "condition": "${find(request.uri.path, '^/oauth2rs-idc')}",
  "properties": {
    "amInstanceUrl": "https://myTenant.forgeblocks.com/am"
  },
  "heap": [
    {
      "name": "SystemAndEnvSecretStore-1",
      "type": "SystemAndEnvSecretStore"
    },
    {
      "name": "AmService-1",
      "type": "AmService",
      "config": {
        "url": "&{amInstanceUrl}",
        "realm": "/alpha",
        "agent": {
          "username": "ig_agent",
          "passwordSecretId": "agent.secret.id"
        },
        "secretsProvider": "SystemAndEnvSecretStore-1"
      }
    }
  ],
  "handler": {
    "type": "Chain",
    "config": {
      "filters": [
        {
          "name": "OAuth2ResourceServerFilter-1",
          "type": "OAuth2ResourceServerFilter",
          "config": {
            "scopes": [
              "mail"
            ],
            "requireHttps": false,
            "realm": "OpenIG",
            "accessTokenResolver": {
              "name": "TokenIntrospectionAccessTokenResolver-1",
              "type": "TokenIntrospectionAccessTokenResolver",
              "config": {
                "amService": "AmService-1",
                "providerHandler": {
                  "type": "Chain",
                  "config": {
                    "filters": [
                      {
                        "type": "HttpBasicAuthenticationClientFilter",
                        "config": {
                          "username": "ig_agent",
                          "passwordSecretId": "agent.secret.id",
                          "secretsProvider": "SystemAndEnvSecretStore-1"
                        }
                      }
                    ],
                    "handler": "ForgeRockClientHandler"
                  }
                }
              }
            }
          }
        }
      ],
      "handler": {
        "type": "StaticResponseHandler",
        "config": {
          "status": 200,
          "headers": {
            "Content-Type": [ "text/html; charset=UTF-8" ]
          },
          "entity": "<html><body><h2>Decoded access_token: ${contexts.oauth2.accessToken.info}</h2></body></html>"
        }
      }
    }
  }
}

json

Notice the following features of the route compared to rs-introspect.json in Validate access tokens through the introspection endpoint, where a local PingAM instance is the Authorization Server:

The AmService URL points to PingAM in PingOne Advanced Identity Cloud.
The AmService realm points to the realm where you have configured your web application and the PingGateway agent.

Test the setup:

In a terminal, export an environment variable for the URL of PingAM in PingOne Advanced Identity Cloud:
```
$ export amInstanceUrl='myAmInstanceUrl'
```

Use a curl command similar to the following to retrieve an access token:

$ mytoken=$(curl -s \
--user "oauth2-client:password" \
--data 'grant_type=password&username=demo&password=Ch4ng3!t&scope=mail' \
$amInstanceUrl/oauth2/realms/alpha/access_token | jq -r ".access_token")

Validate the access token returned in the previous step:

$ curl -v \
--cacert /path/to/secrets/ig.example.com-certificate.pem \
--header "Authorization: Bearer ${mytoken}" \
https://ig.example.com:8443/oauth2rs-idc 

{
  active = true,
  scope = mail,
  realm = /alpha,
  client_id = oauth2-client,
  ...
}

PingOne Advanced Identity Cloud as an OpenID Connect provider

This example sets up PingOne Advanced Identity Cloud as an OpenID Connect identity provider, and PingGateway as a relying party.

For more information about PingGateway and OpenID Connect, refer to OpenID Connect.

Before you start, prepare PingOne Advanced Identity Cloud, PingGateway, and the sample application as described in Example installation for this guide.

Set up PingOne Advanced Identity Cloud:
1. Log in to the PingOne Advanced Identity Cloud admin UI as an administrator.
2. Make sure you are managing the alpha realm. If not, click the current realm at the top of the screen, and switch realm.
3. Go to group Identities > Manage > settings_system_daydream Alpha realm - Users, and add a user with the following values:
  - Username: demo
  - First name: demo
  - Last name: user
  - Email Address: demo@example.com
  - Password: Ch4ng3!t
4. Go to Applications > CustomApplication > OIDC - OpenId Connect > Web and add a web application with the following values:
  - Name: oidc_client
  - Owners: demo user
  - Client Secret: password
  - Sign On > Sign-in URLs: https://ig.example.com:8443/home/id_token/callback
  - Sign On > Grant Types: Authorization Code
  - Sign On > Scopes: openid, profile, email
  - Show advanced settings > Authentication > Implied Consent: On
For more information, refer to PingOne Advanced Identity Cloud’s Application management.

Set up PingGateway:

Set an environment variable for the oidc_client password, and then restart PingGateway:
```
$ export OIDC_SECRET_ID='cGFzc3dvcmQ='
```
bash

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"
}

json

Add the following route to PingGateway, replacing the value for the property amInstanceUrl:

Linux
Windows

$HOME/.openig/config/routes/oidc-idc.json

%appdata%\OpenIG\config\routes\oidc-idc.json

{
  "name": "oidc-idc",
  "baseURI": "http://app.example.com:8081",
  "condition": "${find(request.uri.path, '^/home/id_token')}",
  "properties": {
    "amInstanceUrl": "https://myTenant.forgeblocks.com/am"
  },
  "heap": [
    {
      "name": "SystemAndEnvSecretStore-1",
      "type": "SystemAndEnvSecretStore"
    },
    {
      "name": "AuthenticatedRegistrationHandler-1",
      "type": "Chain",
      "config": {
        "filters": [
          {
            "name": "ClientSecretBasicAuthenticationFilter-1",
            "type": "ClientSecretBasicAuthenticationFilter",
            "config": {
              "clientId": "oidc_client",
              "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/plain"
                  ]
                },
                "entity": "Error in OAuth 2.0 setup."
              }
            },
            "registrations": [
              {
                "name": "oauth2-client",
                "type": "ClientRegistration",
                "config": {
                  "clientId": "oidc_client",
                  "issuer": {
                    "name": "Issuer",
                    "type": "Issuer",
                    "config": {
                      "wellKnownEndpoint": "&{amInstanceUrl}/oauth2/realms/alpha/.well-known/openid-configuration"
                    }
                  },
                  "scopes": [
                    "openid",
                    "profile",
                    "email"
                  ],
                  "authenticatedRegistrationHandler": "AuthenticatedRegistrationHandler-1"
                }
              }
            ],
            "requireHttps": false,
            "cacheExpiration": "disabled"
          }
        }
      ],
      "handler": "ReverseProxyHandler"
    }
  }
}

json

Compared to 07-openid.json in AM as a single OpenID Connect provider, where PingAM is running locally, the ClientRegistration wellKnownEndpoint points to PingOne Advanced Identity Cloud.

Test the setup:
1. In your browser’s privacy or incognito mode, go to https://ig.example.com:8443/home/id_token.
  
  The PingOne Advanced Identity Cloud login page is displayed.
2. Log in to PingOne Advanced Identity Cloud as user demo, password Ch4ng3!t. The home page of the sample application is displayed.

Cross-domain single sign-on

For organizations relying on AM’s session and policy services with SSO, consider cross-Domain Single Sign-On (CDSSO) as an alternative to SSO through OpenID Connect.

This example sets up PingOne Advanced Identity Cloud as an SSO authentication server for requests processed by PingGateway. For more information about about PingGateway and CDSSO, refer to Authenticate with CDSSO.

Before you start, prepare PingOne Advanced Identity Cloud, PingGateway, and the sample application as described in Example installation for this guide.

Set up PingOne Advanced Identity Cloud:

Log in to the PingOne Advanced Identity Cloud admin UI as an administrator.
Make sure you are managing the alpha realm. If not, click the current realm at the top of the screen, and switch realm.
Go to group Identities > Manage > settings_system_daydream Alpha realm - Users, and add a user with the following values:
- Username: demo
- First name: demo
- Last name: user
- Email Address: demo@example.com
- Password: Ch4ng3!t
Register a PingGateway agent with the following values, as described in Register a PingGateway agent in PingOne Advanced Identity Cloud:
- ID: ig_agent
- Password: password
- Redirect URLs: https://ig.ext.com:8443/home/cdsso/redirect

(Optional) Authenticate a PingGateway agent to PingOne Advanced Identity Cloud.

Add a Validation Service:
1. In PingOne Advanced Identity Cloud, select open_in_new Native Consoles > Access Management. The AM admin UI is displayed.
2. Select Services, and add a validation service with the following Valid goto URL Resources:
  - https://ig.ext.com:8443/*
  - https://ig.ext.com:8443/*?*

Set up PingGateway:

Set up PingGateway for HTTPS, as described in Configure PingGateway for TLS (server-side).
Add the following session configuration to admin.json, to ensure that the browser passes the session cookie in the form-POST to the redirect endpoint (step 6 of Information flow during CDSSO):
```
{
  "connectors": […],
  "session": {
    "cookie": {
      "sameSite": "none",
      "secure": true
    }
  },
  "heap": […]
}
```
This step is required for the following reasons:
- When sameSite is strict or lax, the browser does not send the session cookie, which contains the nonce used in validation. If PingGateway doesn’t find the nonce, it assumes that the authentication failed.
- When secure is false, the browser is likely to reject the session cookie.
  
  For more information, refer to admin.json.
Set an environment variable for the PingGateway agent password, and then restart PingGateway:
```
$ export AGENT_SECRET_ID='cGFzc3dvcmQ='
```
bash
The password is retrieved by a SystemAndEnvSecretStore, and must be base64-encoded.

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"
}

json

Add the following route to PingGateway, and correct the value for the property amInstanceUrl:

Linux
Windows

$HOME/.openig/config/routes/cdsso-idc.json

%appdata%\OpenIG\config\routes\cdsso-idc.json

{
  "name": "cdsso-idc",
  "baseURI": "http://app.example.com:8081",
  "condition": "${find(request.uri.path, '^/home/cdsso')}",
  "properties": {
    "amInstanceUrl": "https://myTenant.forgeblocks.com/am"
  },
  "heap": [
    {
      "name": "SystemAndEnvSecretStore-1",
      "type": "SystemAndEnvSecretStore"
    },
    {
      "name": "AmService-1",
      "type": "AmService",
      "config": {
        "url": "&{amInstanceUrl}",
        "realm": "/alpha",
        "agent": {
          "username": "ig_agent",
          "passwordSecretId": "agent.secret.id"
        },
        "secretsProvider": "SystemAndEnvSecretStore-1",
        "sessionCache": {
          "enabled": false
        }
      }
    }
  ],
  "handler": {
    "type": "Chain",
    "config": {
      "filters": [
        {
          "name": "CrossDomainSingleSignOnFilter-1",
          "type": "CrossDomainSingleSignOnFilter",
          "config": {
            "redirectEndpoint": "/home/cdsso/redirect",
            "authCookie": {
              "path": "/home",
              "name": "ig-token-cookie"
            },
            "amService": "AmService-1"
          }
        }
      ],
      "handler": "ReverseProxyHandler"
    }
  }
}

json

Notice the following features of the route compared to cdsso.json in CDSSO for PingGateway in standalone mode, where PingAM is running locally:

The AmService URL points to PingAM in PingOne Advanced Identity Cloud.
The AmService realm points to the realm where you configure your PingGateway agent.

Restart PingGateway.

Test the setup:
1. In your browser’s privacy or incognito mode, go to https://ig.ext.com:8443/home/cdsso.
  
  The PingOne Advanced Identity Cloud login page is displayed.
2. Log in to PingOne Advanced Identity Cloud as user demo, password Ch4ng3!t.
  
  PingAM calls /home/cdsso/redirect, and includes the CDSSO token. The CrossDomainSingleSignOnFilter passes the request to sample app.

Password replay

Password replay brings SSO to legacy web applications without the need to edit, upgrade, or recode them.

Use PingGateway with an appropriate PingOne Advanced Identity Cloud journey to capture and replay username password credentials. PingGateway and PingOne Advanced Identity Cloud share a secret key to encrypt and decrypt the password and keep it safe.

When running AM in a self-hosted deployment, also refer to Password replay from AM.

Request flow

Figure 1. Password replay sequence diagram

PingGateway intercepts the browser’s HTTP GET request.
PingGateway redirects the user to the appropriate PingOne Advanced Identity Cloud journey for authentication.
PingOne Advanced Identity Cloud authenticates the user and stores the encrypted password in a JWT.
PingOne Advanced Identity Cloud redirects the browser back to the protected application with the JWT.
PingGateway intercepts the browser’s HTTP GET request again:
- The user is authenticated.
- PingGateway gets the password from the JWT and decrypts it.
- PingGateway gets the username from PingOne Advanced Identity Cloud based on the user _id.
PingGateway replaces the request with an HTTP POST to the application, taking the credentials from the context.
The sample application validates the credentials from the HTTP POST request.
The sample application responds with the user’s profile page.
PingGateway passes the response from the sample application to the browser.

Tasks

Before you start

Make sure you can access the PingOne Advanced Identity Cloud tenant as an administrator.
Choose the realm to use in the PingOne Advanced Identity Cloud tenant.

The following tasks use the alpha realm.
Prepare hostnames for PingGateway and the sample application.

The following tasks use ig.example.com for PingGateway and app.example.com for the sample application.

Task 1: Run the sample application

Download the sample application.
Open a command-line window and start the sample application:
```
$ java -jar PingGateway-sample-application-2024.6.0-jar-with-dependencies.jar
```
bash
The sample application runs in the foreground until you stop it.
Check you can access the sample application by browsing http://app.example.com:8081/login.

The sample application displays a login screen.

Task 2: Install PingGateway

This task installs PingGateway, but doesn’t configure it for password replay yet.

Download and unpack PingGateway.
Configure PingGateway for HTTPS.
Set a top-level session field in admin.json alongside the heap and connections:
```
"session": {
        "cookie": {
            "sameSite": "none",
            "secure": true
        }
    }
```
PingOne Advanced Identity Cloud prompts the browser to send a session cookie on successful authentication.
- When sameSite is strict or lax, the browser does not send the session cookie with the nonce used in validation. If PingGateway doesn’t find the nonce, it assumes that the authentication failed.
- When secure is false, the browser is likely to reject the session cookie.
Add a base configuration file.

Comment captures in the handler to avoid flooding the PingGateway log, "_capture": "all".
Configure static routes for use with the sample application.
Check you can access the sample application through PingGateway by browsing https://ig.example.com:8443/static.

You might have used a self-signed certificate for the PingGateway HTTPS configuration. If your browser doesn’t recognize the PingGateway certificate and flags it as a security risk, choose to continue.

PingGateway displays a basic profile page for the demo user.

PingGateway now has the configuration required as a basis on which to build password replay.

Task 3: Register PingGateway with PingOne Advanced Identity Cloud

If you have not yet registered PingGateway with PingOne Advanced Identity Cloud, follow these steps:

Configure an Agent journey PingGateway uses to authenticate with PingOne Advanced Identity Cloud.

Field Value Description

Field	Value	Description
ID	`ig-agent`	The PingGateway username when connecting to the `AmService` in PingOne Advanced Identity Cloud.
Password	`password`	The PingGateway password when connecting to the `AmService` in PingOne Advanced Identity Cloud. In production tenants, use a strong password.
Redirect URLs	`https://ig.example.com:8443/replay/redirect`	The PingGateway endpoint to process the encrypted JWT from PingOne Advanced Identity Cloud.

ig-agent

The PingGateway username when connecting to the AmService in PingOne Advanced Identity Cloud.

Password

password

The PingGateway password when connecting to the AmService in PingOne Advanced Identity Cloud.

In production tenants, use a strong password.

Redirect URLs

https://ig.example.com:8443/replay/redirect

The PingGateway endpoint to process the encrypted JWT from PingOne Advanced Identity Cloud.

PingOne Advanced Identity Cloud is now ready for PingGateway to connect. You will share the credentials with PingGateway in Task 6: Configure PingGateway.

Task 4: Prepare a shared secret

PingGateway and PingOne Advanced Identity Cloud share a secret symmetric key to encrypt and decrypt the password.

Generate a random AES 256-bit key to use as a shared secret.

How you generate the secret key is up to you; for example:
```
$ openssl rand -base64 32
YWJjZGVmZ2hpamtsbW5vcHFyc3R1dnd5eHowMTIzNDU=
```
bash
Keep the secret safe.

Store the shared secret key as an ESV in PingOne Advanced Identity Cloud.

Log in to the PingOne Advanced Identity Cloud admin UI as an administrator and go to Tenant Settings > Global Settings > Environment Secrets & Variables.
Click Variables > + Add Variable.

In the Add a Variable modal window, enter the following settings:

Field Value Description

Field	Value	Description
Name	`esv-ig-shared-secret`	The ESV name for the secret.
Value	`YWJjZGVmZ2hpamtsbW5vcHFyc3R1dnd5eHowMTIzNDU=`	The base64-encoded random AES 256-bit key.

Name

esv-ig-shared-secret

The ESV name for the secret.

Value

YWJjZGVmZ2hpamtsbW5vcHFyc3R1dnd5eHowMTIzNDU=

The base64-encoded random AES 256-bit key.

Click Save to create the variable.

PingOne Advanced Identity Cloud can now access the secret through the esv.ig.shared.secret system property. You will share the secret with PingGateway in Task 6: Configure PingGateway.

Task 5: Prepare PingOne Advanced Identity Cloud

Update the PingOne Advanced Identity Cloud validation service for PingGateway, create a script to capture the password, and a journey to use the script.

Log in to the PingOne Advanced Identity Cloud admin UI as an administrator and go to open_in_new Native Consoles > Access Management, select Services, and the following Valid goto URL Resources to the Validation Service:
- https://ig.example.com:8443/*
- https://ig.example.com:8443/*?*

Go to Scripts > Auth Scripts, click + New Script and create a Journey Decision Node script with the Legacy engine named Password replay and the following JavaScript content.

The script adds a JWT encrypted with the shared secret key to the session:

Show script

var fr = JavaImporter(
  org.forgerock.openam.auth.node.api.Action,
  org.forgerock.openam.auth.node.api,
  javax.security.auth.callback.TextOutputCallback,
  org.forgerock.json.jose.builders.JwtBuilderFactory,
  org.forgerock.json.jose.jwt.JwtClaimsSet,
  org.forgerock.json.jose.jwe.JweAlgorithm,
  org.forgerock.json.jose.jwe.EncryptionMethod,
  javax.crypto.spec.SecretKeySpec,
  org.forgerock.secrets.SecretBuilder,
  org.forgerock.util.encode.Base64
);

var NodeOutcome = {
  ERROR: 'false',
  SUCCESS: 'true'
};

var config = {
  encryptionKey: systemEnv.getProperty("esv.ig.shared.secret")
};

function getKey () {
  logger.message("encKey: " + config.encryptionKey)
  return new fr.SecretKeySpec(fr.Base64.decode(config.encryptionKey), 'AES');
}

function buildJwt (claims) {
  logger.message('Building response JWT');
  var encryptionKey = getKey();
  var jwtClaims = new fr.JwtClaimsSet;
  jwtClaims.setClaims(claims);
  var jwt = new fr.JwtBuilderFactory()
                  .jwe(encryptionKey)
                  .headers()
                  .alg(fr.JweAlgorithm.DIRECT)
                  .enc(fr.EncryptionMethod.A128CBC_HS256)
                  .done()
                  .claims(jwtClaims)
                  .build();
  return jwt;
}

try {
  password=nodeState.get("password").asString()
  var registrationClaims = { password: password };
  passwordJwt = buildJwt(registrationClaims);
  action = fr.Action.goTo(NodeOutcome.SUCCESS).putSessionProperty("sunIdentityUserPassword", passwordJwt).build();
} catch (e) {
  logger.error('ERROR ' + e);
  action = fr.Action.send(new fr.TextOutputCallback(fr.TextOutputCallback.ERROR, e.toString())).build();
}

javascript

You can download the script as password-replay.js.

Go to Journeys, click + New Journey, and create a journey named Password replay whose Identity Object is managed/alpha_user.
Configure and save the journey with the nodes shown in this screenshot:
- The Page node presents a page with input fields to prompt for the username and password.
  - The Platform Username node collects and injects the userName into the shared node state.
  - The Platform Password node collects and injects the password into the shared node state.
- The Data Store Decision node uses the username and password to determine whether authentication is successful.
- The Scripted Decision node references your script and has the same outcomes: true and false.
- The Increment Login Count node updates the login count on successful authentication.
In your browser’s privacy or incognito mode, go to the new journey and log in with the credentials of a known user in the alpha realm.

PingOne Advanced Identity Cloud authenticates you and displays the user profile page.

You can now configure PingGateway to use the journey to capture the password.

Task 6: Configure PingGateway

The password replay configuration includes the PingGateway password to connect to PingOne Advanced Identity Cloud, the shared secret, and a route.

Set an environment variable locally on the computer running PingGateway to access the agent password:
```
# The base64-encoded PingGateway agent "password":
$ export AGENT_SECRET_ID='cGFzc3dvcmQ='
```
bash
PingGateway retrieves the password with a SystemAndEnvSecretStore, which requires it to be base64-encoded.

The password must match the agent profile password you set in PingOne Advanced Identity Cloud. PingGateway uses the password to connect to PingOne Advanced Identity Cloud.
Set an environment variable locally on the computer running PingGateway to access the shared secret key:
```
# The base64-encoded shared secret key:
$ export AES_KEY='YWJjZGVmZ2hpamtsbW5vcHFyc3R1dnd5eHowMTIzNDU='
```
bash
PingGateway retrieves the shared secret with a SystemAndEnvSecretStore, which requires it to be base64-encoded.

The shared secret key must match the secret key you stored in the PingOne Advanced Identity Cloud ESV. PingOne Advanced Identity Cloud uses the secret key to encrypt the password to replay. PingGateway uses the secret key to decrypt the password to replay.

Add a route for password replay.

Linux
Windows

$HOME/.openig/config/routes/04-replay-aic.json

%appdata%\OpenIG\config\routes\04-replay-aic.json

Show route

{
    "name": "04-replay",
    "condition": "${find(request.uri.path, '^/replay')}",
    "properties": {
        "amInstanceUrl": "https://myTenant.forgeblocks.com/am/"
    },
    "heap": [
        {
            "name": "SystemAndEnvSecretStore-1",
            "type": "SystemAndEnvSecretStore",
            "config": {
                "mappings": [
                    {
                        "secretId": "aes.key",
                        "format": {
                            "type": "SecretKeyPropertyFormat",
                            "config": {
                                "format": "BASE64",
                                "algorithm": "AES"
                            }
                        }
                    }
                ]
            }
        },
        {
            "name": "AmService-1",
            "type": "AmService",
            "config": {
                "url": "&{amInstanceUrl}",
                "realm": "/alpha",
                "agent": {
                    "username": "ig-agent",
                    "passwordSecretId": "agent.secret.id"
                },
                "secretsProvider": "SystemAndEnvSecretStore-1"
            },
            "sessionCache": {
                "enabled": false
            }
        },
        {
            "name": "CapturedUserPasswordFilter-1",
            "type": "CapturedUserPasswordFilter",
            "config": {
                "ssoToken": "${contexts.ssoToken.value}",
                "keySecretId": "aes.key",
                "keyType": "AES",
                "secretsProvider": "SystemAndEnvSecretStore-1",
                "amService": "AmService-1"
            }
        }
    ],
    "handler": {
        "type": "Chain",
        "config": {
            "filters": [
                {
                    "name": "CrossDomainSingleSignOnFilter-1",
                    "type": "CrossDomainSingleSignOnFilter",
                    "config": {
                        "redirectEndpoint": "/replay/redirect",
                        "authCookie": {
                            "path": "/replay",
                            "name": "ig-token-cookie"
                        },
                        "amService": "AmService-1",
                        "authenticationService": "Password replay"
                    }
                },
                {
                    "name": "UserProfileFilter-1",
                    "type": "UserProfileFilter",
                    "config": {
                        "username": "${contexts.ssoToken.info.uid}",
                        "userProfileService": {
                            "type": "UserProfileService",
                            "config": {
                                "amService": "AmService-1",
                                "profileAttributes": [
                                    "username"
                                ]
                            }
                        }
                    }
                },
                {
                    "name": "PasswordReplayFilter-1",
                    "type": "PasswordReplayFilter",
                    "config": {
                        "loginPage": "${true}",
                        "credentials": "CapturedUserPasswordFilter-1",
                        "request": {
                            "method": "POST",
                            "uri": "http://app.example.com:8081/login",
                            "form": {
                                "username": [
                                    "${contexts.userProfile.username}"
                                ],
                                "password": [
                                    "${contexts.capturedPassword.value}"
                                ]
                            }
                        }
                    },
                    "capture": [
                        "all"
                    ]
                }
            ],
            "handler": "ReverseProxyHandler"
        }
    }
}

json

You can download the route as 04-replay.json.

The route:

Matches requests whose path starts with /replay.
Sets an amInstanceUrl property to the access management service in PingOne Advanced Identity Cloud.

Update the URL to target your tenant.
Loads the aes.key secret key from the local AES_KEY environment variable.
Connects to PingOne Advanced Identity Cloud as ig-agent with the agent.secret.id password from the local AGENT_SECRET_ID environment variable.
Extracts the captured password from the SSO token context and decrypts it with the aes.key secret key.
Uses a CrossDomainSingleSignOnFilter to redirect to the PingOne Advanced Identity Cloud Password replay journey for authentication, getting the authentication information from the ig-token-cookie.
Queries the access management service in PingOne Advanced Identity Cloud to retrieve the username for logging in.

You can retrieve other profile attributes with the UserProfileFilter, such as the email address or first and last names. The sample application expects the username in this example, so the route gets the username.
Logs in to the sample application with the username and password.
Returns the result to the browser.

In production, remove "capture": ["all"] from the PasswordReplayFilter to avoid recording credentials in the logs.

Restart PingGateway to read the secrets from the environment and load the new route.

In the PingGateway output, make sure the route loaded successfully with no errors or warnings: @system - Loaded the route with id '04-replay-aic' registered with the name '04-replay-aic'.

Task 7: Create a test user in PingOne Advanced Identity Cloud

The sample application validates the credentials for password replay. It must recognize the username and password you use.

The sample application has built-in username-password combinations. The username and password credentials shown in the following steps are one of the built-in pairs.

In your browser’s privacy or incognito mode, go to the default login journey for the realm you’re using.

For example, https://myTenant.forgeblocks.com/am/XUI/?realm=/alpha#/.

Click the Create an account link and enter the following settings in the Sign Up page:

Field Value

Field	Value
Username	`wolkig`
First name	`Wilhelm`
Last name	`Wolkig`
Email Address	`wolkig@example.com`
Password	`Geh3imnis!`
Select a security question	`What’s your favorite color?`
Answer	`Red`

Username

wolkig

First name

Wilhelm

Last name

Wolkig

Email Address

wolkig@example.com

Password

Geh3imnis!

Select a security question

What’s your favorite color?

Answer

Red

Click Next to complete account creation and view the user profile.
Sign out.

Validation

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

PingGateway redirects to the PingOne Advanced Identity Cloud journey.
Log in as user wolkig with password Geh3imnis!.

PingGateway successfully replays the credentials against the sample application. The sample application displays its user profile page:

Review the PingGateway output.

On success, the output displays the credentials and the profile page:

...INFO  o.f.o.d.c.C.c.PasswordReplayFilter-1 @04-replay-aic -

[CONTINUED]--- (filtered-request) exchangeId:<id> - transactionId:<id> --->

[CONTINUED]POST http://app.example.com:8081/login HTTP/1.1
[CONTINUED]Content-Length: 37
[CONTINUED]Content-Type: application/x-www-form-urlencoded

[CONTINUED]password=Geh3imnis%21&username=wolkig

...INFO  o.f.o.d.c.C.c.PasswordReplayFilter-1 @04-replay-aic -

[CONTINUED]<--- (response) exchangeId:<id> - transactionId:<id> ---

[CONTINUED]HTTP/1.1 200 OK
...

[CONTINUED]<!DOCTYPE html>
...

You have successfully demonstrated password replay with PingGateway and PingOne Advanced Identity Cloud.

If password replay fails, consider the outcome of the HTTP POST from PingGateway to the sample application:

HTTP 401 Unauthorized: PingGateway is not replaying the credentials.

Review the PingGateway output to determine whether the username or password is missing when PingGateway replays the credentials.

If the password is missing, make sure PingGateway and PingOne Advanced Identity Cloud share the same AES secret key.
HTTP 403 Forbidden: PingGateway is not replaying the right credentials.

Make sure you’re using a username-password combination known to the sample application.

Policy enforcement

The following procedure gives an example of how to request and enforce policy decisions from PingOne Advanced Identity Cloud.

Enforce a simple policy

Before you start, set up and test the example in Cross-domain single sign-on.

Set up PingOne Advanced Identity Cloud:
1. In the PingOne Advanced Identity Cloud admin UI, select open_in_new Native Consoles > Access Management. The AM admin UI is displayed.
2. Select Authorization > Policy Sets > New Policy Set, and add a policy set with the following values:
  - Id : PEP-CDSSO
  - Resource Types : URL
3. In the new policy set, add a policy with the following values:
  - Name : CDSSO
  - Resource Type : URL
  - Resource pattern : *://*:*/*
  - Resource value : http://app.example.com:8081/home/cdsso
    
    This policy protects the home page of the sample application.
4. On the Actions tab, add an action to allow HTTP GET.
5. On the Subjects tab, remove any default subject conditions, add a subject condition for all Authenticated Users.

Set up PingGateway:

Replace cdsso-idc.json with the following route, and correct the value for the property amInstanceUrl:

Linux
Windows

$HOME/.openig/config/routes/pep-cdsso-idc.json

%appdata%\OpenIG\config\routes\pep-cdsso-idc.json

{
  "name": "pep-cdsso-idc",
  "baseURI": "http://app.example.com:8081",
  "condition": "${find(request.uri.path, '^/home/cdsso')}",
  "properties": {
    "amInstanceUrl": "https://myTenant.forgeblocks.com/am"
  },
  "heap": [
    {
      "name": "SystemAndEnvSecretStore-1",
      "type": "SystemAndEnvSecretStore"
    },
    {
      "name": "AmService-1",
      "type": "AmService",
      "config": {
        "url": "&{amInstanceUrl}",
        "realm": "/alpha",
        "agent": {
          "username": "ig_agent",
          "passwordSecretId": "agent.secret.id"
        },
        "secretsProvider": "SystemAndEnvSecretStore-1",
        "sessionCache": {
          "enabled": false
        }
      }
    }
  ],
  "handler": {
    "type": "Chain",
    "config": {
      "filters": [
        {
          "name": "CrossDomainSingleSignOnFilter-1",
          "type": "CrossDomainSingleSignOnFilter",
          "config": {
            "redirectEndpoint": "/home/cdsso/redirect",
            "authCookie": {
              "path": "/home",
              "name": "ig-token-cookie"
            },
            "amService": "AmService-1"
          }
        },
        {
          "name": "PolicyEnforcementFilter-1",
          "type": "PolicyEnforcementFilter",
          "config": {
            "application": "PEP-CDSSO",
            "ssoTokenSubject": "${contexts.cdsso.token}",
            "amService": "AmService-1"
          }
        }
      ],
      "handler": "ReverseProxyHandler"
    }
  }
}

json

Note the following feature of the route compared to cdsso-idc.json:

The CrossDomainSingleSignOnFilter is followed by a PolicyEnforcementFilter to enforce the policy PEP-CDSSO.

Test the setup:
1. Go to https://ig.ext.com:8443/home/cdsso.
  
  If you have warnings that the site is not secure respond to the warnings to access the site.
  
  PingGateway redirects you to PingOne Advanced Identity Cloud for authentication.
2. Log in to PingOne Advanced Identity Cloud as user demo, password Ch4ng3!t.
  
  PingOne Advanced Identity Cloud redirects you back to the request URL, and PingGateway requests a policy decision. PingOne Advanced Identity Cloud returns a policy decision that grants access to the sample application.

Step up authorization for a transaction

Before you start, set up and test the example in pep.adoc#pep-cdsso.

In the PingOne Advanced Identity Cloud admin UI, select code Scripts > Auth Scripts > New Script > Journey Decision Node > Next, and add a default Journey Decision Node Script script called TxTestPassword:

/*
  - Data made available by nodes that have already executed are available in the sharedState variable.
  - The script should set outcome to either "true" or "false".
 */

var givenPassword = nodeState.get("password").asString()

if (givenPassword.equals("7890")) {
  outcome = "true"
} else {
  outcome = "false"
}

javascript

Configure a journey:
1. Click account_tree Journeys and add a journey with the following configuration:
  - Name: Tx01_Tree
  - Identity Object: Alpha realm users
    
    The journey canvas is displayed.
2. In Nodes > Basic Authentication, drag a Password Collector node onto the canvas.
3. In Nodes > Utilities, drag a Scripted decision node onto the canvas.
4. Configure the scripted decision node as follows:
  - Script: select TxTestPassword
  - Outcomes: enter true and false
5. Connect the nodes as shown:
  
  For information about configuring trees, refer to PingOne Advanced Identity Cloud Docs
Edit the authorization policy:
1. In the PingOne Advanced Identity Cloud admin UI, select open_in_new Native Consoles > Access Management. The AM admin UI is displayed.
2. Select Authorization > Policy Sets > PEP-CDSSO, and add the following environment condition to the CDSSO policy:
  - All of
  - Type: Transaction
  - Script name: Authenticate to tree
  - Strategy Specifier: Tx01_Tree
Test the setup:
1. In a browser, go to https://ig.ext.com:8443/home/cdsso.
  
  If you have not previously authenticated to PingOne Advanced Identity Cloud, the CrossDomainSingleSignOnFilter redirects the request to PingOne Advanced Identity Cloud for authentication.
2. Log in to PingOne Advanced Identity Cloud as user demo, password Ch4ng3!t.
3. Enter the password 7890 required by the script TxTestPassword.
  
  PingOne Advanced Identity Cloud redirects you back to the request URL, and PingGateway requests a policy decision. PingOne Advanced Identity Cloud returns a policy decision based on the authentication journey.

PingOne Protect integration

Use PingOne Protect risk evaluations with web applications protected by PingGateway. PingGateway routes requests based on the level of risk PingOne Protect associates with them.

This capability is available in Technology preview. It isn’t yet supported, may be functionally incomplete, and is subject to change without notice.

Risk management

PingOne Protect monitors end-user requests and generates a risk score of low, medium, or high based on the user’s activity and device context. You configure and fine-tune risk policies and train risk models prior to using PingGateway with PingOne Protect. Learn more in Threat Protection using PingOne Protect.

You configure PingGateway routes to react to risk scores from PingOne Protect dynamically. For example, if the risk score is medium, PingGateway can direct the user to complete additional verification. If the risk score is high, PingGateway can deny access to the resource instead.

The following sequence diagram shows the PingGateway configuration objects involved in a risk management flow:

The PingOneProtectEvaluationFilter calls PingOne Protect.
It populates the PingOneProtectEvaluationContext based on the response.
The PingOneProtectThreatLevelRoutingHandler dispatches the request based on its risk level.
After prompting the user to complete additional actions following a risk evaluation, the PingOneProtectFeedbackFilter records information about the outcome and can override the risk level in the session context.

At present, PingGateway doesn’t send the result to PingOne Protect.

The initial request enters a Chain configured for risk evaluation with PingOne Protect.
The PingOneProtectEvaluationFilter includes data about the request in an API call to PingOne Protect.
PingOne Protect provides a risk evaluation response.
The PingOneProtectEvaluationFilter populates the PingOneProtectEvaluationContext with the risk level based on the evaluation response and passes control to the PingOneProtectThreatLevelRoutingHandler.
-10. The PingOneProtectThreatLevelRoutingHandler dispatches the request based on the risk level. The downstream handler returns a response to the initial request that is appropriate for the risk level. The downstream handlers can prompt additional actions to verify the user’s identity.

Although not shown in the sequence diagram, when a MEDIUM risk level leads to additional authentication steps, a PingOneProtectFeedbackFilter included in the process records the outcome.

PingGateway runs at the outer edge of your systems, the place where all inbound traffic first arrives and all outbound traffic leaves, just inside the network infrastructure.

PingGateway is well-placed to capture signals about the traffic and its risk profile.

Example: protect against session degradation

Session degradation arises when a valid user session gets used in unexpected ways, increasing the risk the session has been hijacked or otherwise compromised. Session degradation is why we can’t let users stay signed in forever unless we can authenticate them again.

Together, PingGateway and PingOne Protect help you automate fine-grained risk evaluation, avoiding the distraction of additional authentication steps unless they’re required for a risky request. Users stay signed in with their current session, which they experience as a keep me signed in feature. You nevertheless protect their assets from hijacking without needing constantly to verify their identity.

This example demonstrates risk management where the principal already has a valid session. The example does not demonstrate how to configure PingOne Protect.

When PingOne Protect returns a risk evaluation, PingGateway responds based on the risk level. This example demonstrates the following responses:

High risk: Deny access to the requested resource.

Although not shown in this brief example, you could route the request to a honeypot.
Medium risk: Prompt the user to re-authenticate to verify their identity.

The user can perform step up or transactional authentication at this point.
Low risk: Let the request pass through unchanged.

Before you start

Configure PingOne Protect. Learn more in Threat Protection using PingOne Protect.
Implement CDSSO with PingOne Advanced Identity Cloud or CDSSO for self-managed AM. This example opts for CDSSO with PingOne Advanced Identity Cloud, so adapt the configuration as necessary when using self-managed AM.
For additional protection with medium-risk requests, implement Step up authorization for a transaction.
Verify you can successfully authenticate with CDSSO to the sample application.

Configure PingGateway

What follows extends the CDSSO route to protect against session degradation:

Sign on to the PingOne environment with PingOne Protect as an administrator and add an application for PingGateway.

Use the following hints regarding non-default configuration settings:

Setting Value

Application Name

PingGateway

Application Type

Worker

Application profile > Roles

Environment Admin
Identity Data Admin

Setting	Value
Application Name	PingGateway
Application Type	Worker
Application profile > Roles	Environment Admin Identity Data Admin

In the PingOne environment, find and record the values of the following settings:

Property Description

Property	Description
Environment UUID	This is `<env-uuid>` in other property examples.
Evaluation endpoint	For risk evaluation requests. Example: `https://api.pingone.eu/v1/environments/<env-uuid>/riskEvaluations`
PingGateway client ID	PingGateway credentials to access PingOne as the application you registered.
PingGateway client secret
Policy set UUID	The PingOne Protect policy for risk evaluation requests.
Token endpoint	For PingGateway to get an access token. Example: `https://auth.pingone.eu/<env-uuid>/as/token`

Environment UUID

This is <env-uuid> in other property examples.

Evaluation endpoint

For risk evaluation requests.

Example: https://api.pingone.eu/v1/environments/<env-uuid>/riskEvaluations

PingGateway client ID

PingGateway credentials to access PingOne as the application you registered.

PingGateway client secret

Policy set UUID

The PingOne Protect policy for risk evaluation requests.

Token endpoint

For PingGateway to get an access token.

Example: https://auth.pingone.eu/<env-uuid>/as/token

Set an environment variable for the PingGateway client secret.

PingGateway uses a SystemAndEnvSecretStore to retrieve the client secret, so you must base64-encode the value you found in the PingOne application profile:
```
$ export CLIENT_SECRET_ID='<base-64-encoded-client-secret>'
```
bash
Restart PingGateway to load the environment variable.

Update the CDSSO route to add risk management:

{
  "name": "risk",
  "baseURI": "http://app.example.com:8081",
  "condition": "${find(request.uri.path, '^/home/cdsso')}",
  "properties": {
    "amInstanceUrl": "https://myTenant.forgeblocks.com/am",
    "clientId": "my-application-client-id",
    "evaluationEndpoint": "https://api.pingone.eu/v1/environments/my-environment-id/riskEvaluations",
    "policySetId": "my-policy-set-id",
    "tokenEndpoint": "https://auth.pingone.eu/my-environment-id/as/token"
  },
  "heap": [
    {
      "name": "SystemAndEnvSecretStore-1",
      "type": "SystemAndEnvSecretStore"
    },
    {
      "name": "AmService-1",
      "type": "AmService",
      "config": {
        "url": "&{amInstanceUrl}",
        "realm": "/alpha",
        "agent": {
          "username": "ig_agent",
          "passwordSecretId": "agent.secret.id"
        },
        "secretsProvider": "SystemAndEnvSecretStore-1",
        "sessionCache": {
          "enabled": false
        }
      }
    },
    {
      "name": "ClientCredentialsOAuth2ClientFilter-1",
      "type": "ClientCredentialsOAuth2ClientFilter",
      "config": {
        "tokenEndpoint": "&{tokenEndpoint}",
        "scopes": [
          "openid",
          "profile"
        ],
        "endpointHandler": {
          "name": "AccessTokenHandler",
          "type": "Chain",
          "config": {
            "filters": [
              {
                "type": "ClientSecretBasicAuthenticationFilter",
                "config": {
                  "clientId": "&{clientId}",
                  "clientSecretId": "client.secret.id",
                  "secretsProvider": "SystemAndEnvSecretStore-1"
                }
              }
            ],
            "handler": "ForgeRockClientHandler"
          }
        }
      }
    },
    {
      "name": "EvaluationEndpointHandler",
      "type": "Chain",
      "config": {
        "filters": [
          "ClientCredentialsOAuth2ClientFilter-1"
        ],
        "handler": "ForgeRockClientHandler"
      }
    },
    {
      "name": "FailureHandler",
      "type": "StaticResponseHandler",
      "config": {
        "status": 403,
        "headers": {
          "Content-Type": [
            "text/plain; charset=UTF-8"
          ]
        },
        "entity": "HTTP 403 Forbidden"
      }
    },
    {
      "name": "StepUpHandler",
      "type": "Chain",
      "config": {
        "filters": [
          {
            "name": "PolicyEnforcementFilter-1",
            "type": "PolicyEnforcementFilter",
            "config": {
              "application": "PEP-CDSSO",
              "ssoTokenSubject": "${contexts.cdsso.token}",
              "amService": "AmService-1"
            }
          }
        ],
        "handler": "ReverseProxyHandler"
      }
    }
  ],
  "handler": {
    "type": "Chain",
    "config": {
      "filters": [
        {
          "name": "CrossDomainSingleSignOnFilter-1",
          "type": "CrossDomainSingleSignOnFilter",
          "config": {
            "redirectEndpoint": "/home/cdsso/redirect",
            "authCookie": {
              "path": "/home",
              "name": "ig-token-cookie"
            },
            "amService": "AmService-1"
          }
        },
        {
          "name": "PingOneProtectEvaluationFilter-1",
          "type": "PingOneProtectEvaluationFilter",
          "config": {
            "evaluationEndpoint": "&{evaluationEndpoint}",
            "endpointHandler": "EvaluationEndpointHandler",
            "policySet": "&{policySetId}",
            "userId": "${contexts.cdsso.claimsSet.getClaim('subname')}",
            "nonEvaluatedUrls" : "${find(request.uri.path, '/home/cdsso/redirect')}"
          }
        }
      ],
      "handler": {
        "name": "PingOneProtectThreatLevelRoutingHandler-1",
        "type": "PingOneProtectThreatLevelRoutingHandler",
        "config": {
          "levels": [
            {
              "level": "LOW",
              "handler": "ReverseProxyHandler"
            },
            {
              "level": "MEDIUM",
              "handler": "StepUpHandler"
            },
            {
              "level": "HIGH",
              "handler": "FailureHandler"
            }
          ],
          "fallbackHandler": "FailureHandler"
        }
      }
    }
  }
}

json

Notice the following features of the updated route:

The route properties use the settings you collected from the PingOne environment.

Replace the placeholders in the route properties with the settings you collected.
The heap has an evaluation endpoint handler to get an access token for risk evaluation requests.
The PingOneProtectEvaluationFilter uses the evaluation endpoint handler to make the risk evaluation request and populate the PingOneProtectEvaluationContext (implicit in the configuration).
The PingOneProtectThreatLevelRoutingHandler uses the context to route the request based on the risk level:
- Low-risk requests pass through unchanged.
- Medium-risk requests use step up authorization for the request.
- High-risk requests and requests where the PingOneProtectEvaluationFilter failed to update the context get denied.

Verify the route

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

PingOne Advanced Identity Cloud displays the login page.
Log in to PingOne Advanced Identity Cloud as user demo, password Ch4ng3!t.

After authentication, PingGateway gets an access token and uses it to make a risk evaluation request. The PingOneProtectThreatLevelRoutingHandler routes the result:
- Low-risk requests go directly to the sample app.
- Medium-risk requests prompt the user for the authorization passcode 7890.
- PingGateway denies access to other requests.

You’ve successfully demonstrated risk management to prevent session degradation. Adapt the route to the specifics of your use case.

Pass runtime data downstream in a JWT

This example sets up PingOne Advanced Identity Cloud as an identity provider, to pass identity or other runtime information downstream, in a JWT signed with a PEM.

For more information about using runtime data, refer to Passing data along the chain. To help with development, the sample application includes a /jwt endpoint to display the JWT, verify its signature, and decrypt it.

Before you start, prepare PingOne Advanced Identity Cloud, PingGateway, and the sample application as described in Example installation for this guide.

Set up secrets:
1. Locate a directory for secrets, and go to it:
  $ cd /path/to/secrets
  
  bash
2. Create the following secret key and certificate pair as PEM files:
  $ openssl req \ -newkey rsa:2048 \ -new \ -nodes \ -x509 \ -days 3650 \ -subj "/CN=ig.example.com/OU=example/O=com/L=fr/ST=fr/C=fr" \ -keyout ig.example.com-key.pem \ -out ig.example.com-certificate.pem
  
  bash
  Two PEM files are created, one for the secret key, and another for the associated certificate.
3. Map the key and certificate to the same secret ID in PingGateway:
  $ cat ig.example.com-key.pem ig.example.com-certificate.pem > key.manager.secret.id.pem
  
  bash
4. Generate PEM files to sign and verify the JWT:
  $ openssl req \ -newkey rsa:2048 \ -new \ -nodes \ -x509 \ -days 3650 \ -subj "/CN=ig.example.com/OU=example/O=com/L=fr/ST=fr/C=fr" \ -keyout id.key.for.signing.jwt.pem \ -out id.key.for.verifying.jwt.pem
  
  bash
5. Make sure the following files have been added to your secrets directory:
  - id.key.for.signing.jwt.pem
  - id.key.for.verifying.jwt.pem
  - key.manager.secret.id.pem
  - ig.example.com-certificate.pem
  - ig.example.com-key.pem

Set up PingOne Advanced Identity Cloud:

Log in to the PingOne Advanced Identity Cloud admin UI as an administrator.
Go to group Identities > Manage > settings_system_daydream Alpha realm - Users, and add a user with the following values:
- Username: demo
- First name: demo
- Last name: user
- Email Address: demo@example.com
- Password: Ch4ng3!t
Register a PingGateway agent with the following values, as described in Register a PingGateway agent in PingOne Advanced Identity Cloud:
- ID: ig_agent_jwt
- Password: password
- Redirect URLs: https://ig.example.com:8443/jwt/redirect

(Optional) Authenticate a PingGateway agent to PingOne Advanced Identity Cloud.

Add a Validation Service:
1. In PingOne Advanced Identity Cloud, select open_in_new Native Consoles > Access Management. The AM admin UI is displayed.
2. Select Services, and add a validation service with the following Valid goto URL Resources:
  - https://ig.example.com:8443/*
  - https://ig.example.com:8443/*?*

Set up PingGateway:

Set up TLS by adding the following file to PingGateway, replacing the value for the property secretsDir:

Linux
Windows

$HOME/.openig/config/admin.json

%appdata%\OpenIG\config\admin.json

{
  "mode": "DEVELOPMENT",
  "properties": {
    "secretsDir": "/path/to/secrets"
  },
  "connectors": [
    {
      "port": 8080
    },
    {
      "port": 8443,
      "tls": "ServerTlsOptions-1"
    }
  ],
  "session": {
    "cookie": {
      "sameSite": "none",
      "secure": true
    }
  },
  "heap": [
    {
      "name": "ServerTlsOptions-1",
      "type": "ServerTlsOptions",
      "config": {
        "keyManager": {
          "type": "SecretsKeyManager",
          "config": {
            "signingSecretId": "key.manager.secret.id",
            "secretsProvider": "ServerIdentityStore"
          }
        }
      }
    },
    {
      "name": "ServerIdentityStore",
      "type": "FileSystemSecretStore",
      "config": {
        "format": "PLAIN",
        "directory": "&{secretsDir}",
        "suffix": ".pem",
        "mappings": [{
          "secretId": "key.manager.secret.id",
          "format": {
            "type": "PemPropertyFormat"
          }
        }]
      }
    }
  ]
}

json

Set an environment variable for the PingGateway agent password, and then restart PingGateway:
```
$ export AGENT_SECRET_ID='cGFzc3dvcmQ='
```
bash
The password is retrieved by a SystemAndEnvSecretStore, and must be base64-encoded.

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"
}

json

Add the following route to PingGateway, replacing the value for the properties secretsDir and amInstanceUrl:

Linux
Windows

$HOME/.openig/config/routes/jwt-idc.json

%appdata%\OpenIG\config\routes\jwt-idc.json

{
  "name": "jwt-idc",
  "condition": "${find(request.uri.path, '/jwt')}",
  "baseURI": "http://app.example.com:8081",
  "properties": {
    "secretsDir": "/path/to/secrets",
    "amInstanceUrl": "https://myTenant.forgeblocks.com/am"
  },
  "heap": [
    {
      "name": "SystemAndEnvSecretStore-1",
      "type": "SystemAndEnvSecretStore"
    },
    {
      "name": "AmService-1",
      "type": "AmService",
      "config": {
        "url": "&{amInstanceUrl}",
        "realm": "/alpha",
        "agent": {
          "username": "ig_agent_jwt",
          "passwordSecretId": "agent.secret.id"
        },
        "secretsProvider": "SystemAndEnvSecretStore-1",
        "sessionCache": {
          "enabled": false
        }
      }
    },
    {
      "name": "pemPropertyFormat",
      "type": "PemPropertyFormat"
    },
    {
      "name": "FileSystemSecretStore-1",
      "type": "FileSystemSecretStore",
      "config": {
        "format": "PLAIN",
        "directory": "&{secretsDir}",
        "suffix": ".pem",
        "mappings": [{
          "secretId": "id.key.for.signing.jwt",
          "format": "pemPropertyFormat"
        }]
      }
    }
  ],
  "handler": {
    "type": "Chain",
    "config": {
      "filters": [
        {
          "name": "CrossDomainSingleSignOnFilter-1",
          "type": "CrossDomainSingleSignOnFilter",
          "config": {
            "redirectEndpoint": "/jwt/redirect",
            "authCookie": {
              "path": "/jwt",
              "name": "ig-token-cookie"
            },
            "amService": "AmService-1"
          }
        },
        {
          "name": "UserProfileFilter",
          "type": "UserProfileFilter",
          "config": {
            "username": "${contexts.ssoToken.info.uid}",
            "userProfileService": {
              "type": "UserProfileService",
              "config": {
                "amService": "AmService-1"
              }
            }
          }
        },
        {
          "name": "JwtBuilderFilter-1",
          "type": "JwtBuilderFilter",
          "config": {
            "template": {
              "name": "${contexts.userProfile.commonName}",
              "email": "${contexts.userProfile.rawInfo.mail[0]}"
            },
            "secretsProvider": "FileSystemSecretStore-1",
            "signature": {
              "secretId": "id.key.for.signing.jwt",
              "algorithm": "RS512"
            }
          }
        },
        {
          "name": "HeaderFilter-1",
          "type": "HeaderFilter",
          "config": {
            "messageType": "REQUEST",
            "add": {
              "x-openig-user": ["${contexts.jwtBuilder.value}"]
            }
          }
        }
      ],
      "handler": "ReverseProxyHandler"
    }
  }
}

json

Test the setup:
1. Go to https://ig.example.com:8443/jwt.
  
  If you receive warnings that the site is not secure, respond to the warnings to access the site. The PingOne Advanced Identity Cloud login page is displayed.
2. Log in to PingOne Advanced Identity Cloud as user demo, password Ch4ng3!t. The sample app displays the signed JWT along with its header and payload.
3. In USE PEM FILE, enter the absolute path to id.key.for.verifying.jwt.pem to verify the JWT signature.

Secure the OAuth 2.0 access token endpoint

This section uses a GrantSwapJwtAssertionOAuth2ClientFilter to transform requests for OAuth 2.0 access tokens into secure JWT bearer grant type requests. It propagates the transformed requests to PingOne Advanced Identity Cloud to obtain an access token.

Use GrantSwapJwtAssertionOAuth2ClientFilter to increase the security of less-secure grant-type requests, such as Client credentials grant requests or Resource owner password credentials grant requests.

The GrantSwapJwtAssertionOAuth2ClientFilter obtains access tokens from the /oauth2/access_token endpoint. To prevent unwanted or malicious access to the endpoint, make sure only a well-defined set of clients can use this filter.

Consider the following options to secure access to the GrantSwapJwtAssertionOAuth2ClientFilter:

Deploy PingGateway on a trusted network.
Use mutual TLS (mTLS) and X.509 certificates for authentication between clients and PingGateway. For more information, refer to OAuth 2.0 Mutual TLS Client Authentication and Certificate Bound Access Tokens.
Configure an AllowOnlyFilter in front of the GrantSwapJwtAssertionOAuth2ClientFilter to control access within a route.
Define restrictive Route conditions to allow access only for expected grant-type requests. For example, define a route condition that requires a specific client ID, grant-type, or scope.
Configure a ScriptableFilter in front of the GrantSwapJwtAssertionOAuth2ClientFilter to validate requests.

The following figure shows the flow of information for a grant swap:

Before you start, prepare PingOne Advanced Identity Cloud, PingGateway, and the sample application as described in Example installation for this guide.

Set up PingOne Advanced Identity Cloud:
1. Log in to the PingOne Advanced Identity Cloud admin UI as an administrator.
2. Create a service account with the following values, as described in Create a new service account:
  - Name: myServiceAccount
  - Scopes: fr:idm:* All Identity Management APIs
    
    The service account ID is displayed and you are prompted to download the private key. The public key is held in PingOne Advanced Identity Cloud.
    
    For more information, refer to Service accounts.
3. Make a note of the service account ID and download the private key to your secrets directory.
4. Rename the key to match the regex format (\.[a-zA-Z0-9])*. For example, rename myServiceAccount_privateKey.jwk to privateKey.jwk.

Set up PingGateway:

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

Add the following route to PingGateway:

Linux
Windows

$HOME/.openig/config/routes/grant-swap.json

%appdata%\OpenIG\config\routes\grant-swap.json

{
  "name" : "grant-swap",
  "properties": {
    "idcInstanceUrl": "https://myTenant.forgeblocks.com",
    "issuer": "service-account-id",
    "secretsDir": "path-to-secrets",
    "privateKeyFilename": "privateKey.jwk"
  },
  "condition" : "#{find(request.uri.path, '^/am/oauth2/access_token') && request.entity.form['grant_type'][0] == 'client_credentials'}",
  "baseURI" : "&{idcInstanceUrl}:443/",
  "heap" : [ {
    "name": "JwkPropertyFormat-01",
    "type": "JwkPropertyFormat"
  },
    {
      "name": "FileSystemSecretStore-01",
      "type": "FileSystemSecretStore",
      "config": {
        "format": "JwkPropertyFormat-01",
        "directory": "&{secretsDir}",
        "mappings": [ {
          "secretId": "&{privateKeyFilename}",
          "format": "JwkPropertyFormat-01"
        }
        ]
      }
    }
  ],
  "handler" : {
    "type" : "Chain",
    "capture" : "all",
    "config" : {
      "filters" : [
        {
          "name" : "GrantSwapJwtAssertionOAuth2ClientFilter-01",
          "description": "access /access_token endpoint with jwt-bearer-profile",
          "type" : "GrantSwapJwtAssertionOAuth2ClientFilter",
          "capture" : "all",
          "config" : {
            "clientId" : "service-account",
            "assertion" : {
              "issuer" : "&{issuer}",
              "audience" : "&{idcInstanceUrl}/am/oauth2/access_token",
              "subject" : "&{issuer}",
              "expiryTime": "2 minutes"
            },
            "signature": {
              "secretId": "&{privateKeyFilename}",
              "includeKeyId": false
            },
            "secretsProvider": "FileSystemSecretStore-01",
            "scopes" : {
              "type": "RequestFormResourceAccess"
            }
          }
        }
      ],
      "handler" : "ForgeRockClientHandler"
    }
  }
}

json

In the route, replace the values for the following properties with your values:
- idcInstanceUrl: The root URL of your PingOne Advanced Identity Cloud tenant.
- issuer: The ID of the service account created in PingOne Advanced Identity Cloud
- secretsDir: The directory containing the downloaded private key
- privateKeyFilename: The filename of the downloaded private key
Notice the following features of the route:
- The condition intercepts only client_credentials grant-type requests on the path /am/oauth2/access_token. A more secure condition can be set on the client ID.
- Requests are rebased to the PingOne Advanced Identity Cloud URL.
- A FileSystemSecretStore loads the private-key JWK used to sign the JWT.
- The GrantSwapJwtAssertionOAuth2ClientFilter:
  - Requires the core JWT claims issuer, subject, audience, and expiryTime.
  - Uses RequestFormResourceAccess to extract scopes from the inbound request for inclusion in the JWT-assertion grant-type request propagated to AM.
  - Signs the JWT with the JWK provided by the service account.
- The GrantSwapJwtAssertionOAuth2ClientFilter clientId refers to the OAuth 2.0 client ID created by AM. The value must be service-account.

Add the following route to PingGateway to return a standard OAuth 2.0 error response if the request fails the route condition:

Linux
Windows

$HOME/.openig/config/routes/zz-returns-invalid-request.json

%appdata%\OpenIG\config\routes\zz-returns-invalid-request.json

{
  "name" : "zz-returns-invalid-request",
  "handler" : {
    "type" : "StaticResponseHandler",
    "capture" : "all",
    "config" : {
      "status": 400,
      "headers": {"Content-Type": ["application/json; charset=UTF-8"]},
      "entity": "{\"error\": \"Invalid_request\", \"error_description\": \"Invalid request\"}"
    }
  }
}

json

Test the setup by accessing the route with a curl command similar to this:
```
$ curl  \
    --cacert /path/to/secrets/ig.example.com-certificate.pem \
    --location \
    --request POST 'https://ig.example.com:8443/am/oauth2/access_token' \
    --header 'Content-Type: application/x-www-form-urlencoded' \
    --data-urlencode 'client_id=myServiceAccount' \
    --data-urlencode 'grant_type=client_credentials' \
    --data-urlencode 'scope=fr:idm:*'

{"access_token":"eyJ...","scope":"fr:idm:*","token_type":"Bearer","expires_in":899}
```
The command makes a client_credentials grant-type request on the path /am/oauth2/access_token, supplying the client ID and scopes. PingGateway transforms the request into a JWT-assertion grant-type request and propagates it to PingOne Advanced Identity Cloud.

Because the service account in PingOne Advanced Identity Cloud supports the requested scope, the GrantSwapJwtAssertionOAuth2ClientFilter returns an access token.

PingGateway 2024.6

PingOne Advanced Identity Cloud

Example installation for this guide

Authenticate a PingGateway agent to PingOne Advanced Identity Cloud

Register a PingGateway agent in PingOne Advanced Identity Cloud

Set up a demo user in PingOne Advanced Identity Cloud

Recommendations

About PingGateway and PingOne Advanced Identity Cloud

OAuth 2.0

PingOne Advanced Identity Cloud as an OpenID Connect provider

Cross-domain single sign-on

Password replay

Request flow

Tasks

Before you start

Task 1: Run the sample application

Task 2: Install PingGateway

Task 3: Register PingGateway with PingOne Advanced Identity Cloud

Task 4: Prepare a shared secret

Task 5: Prepare PingOne Advanced Identity Cloud

Task 6: Configure PingGateway

Task 7: Create a test user in PingOne Advanced Identity Cloud

Validation

Policy enforcement

Enforce a simple policy

Step up authorization for a transaction

PingOne Protect integration

Risk management

Example: protect against session degradation

Before you start

Configure PingGateway

Verify the route

Pass runtime data downstream in a JWT

Secure the OAuth 2.0 access token endpoint