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

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.

PingGateway 2024.6