Not-enforced URIs

By default, PingGateway routes protect access to resources for all requests matching the route’s condition path. For assets that don’t need protection, like the welcome page of a website, public images, and favicons, you can avoid enforcing protection.

The following sections show routes that don’t enforce authentication for some request URLs or URL patterns.

With a SwitchFilter

Before you start:

Prepare PingGateway and the sample app as described in the Quick install

Install and configure AM on http://am.example.com:8088/openam, using the default configuration.

On your system, add the following data in a comma-separated value file:

Linux
Windows

/tmp/userfile.txt

C:\Temp\userfile.txt

username,password,fullname,email
george,C0stanza,George Costanza,george@example.com
kramer,N3wman12,Kramer,kramer@example.com
bjensen,H1falutin,Babs Jensen,bjensen@example.com
demo,Ch4ng31t,Demo User,demo@example.com
kvaughan,B5ibery12,Kirsten Vaughan,kvaughan@example.com
scarter,S9rain12,Sam Carter,scarter@example.com

Set up AM:

Select Services > Add a Service and add a Validation Service with the following Valid goto URL Resources:
- https://ig.example.com:8443/*
- https://ig.example.com:8443/*?*
Register a PingGateway agent with the following values, as described in Register a PingGateway agent in AM:
- Agent ID: ig_agent
- Password: password
  
  Use secure passwords in a production environment. Consider using a password manager to generate secure passwords.

(Optional) Authenticate the agent to AM as described in Authenticate a PingGateway agent to AM.

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

Set up PingGateway:

Set an environment variable for the PingGateway agent password, and then restart PingGateway:
```
$ export AGENT_SECRET_ID='cGFzc3dvcmQ='
```
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"
}

Add the following route to PingGateway:

Linux
Windows

$HOME/.openig/config/routes/not-enforced-switch.json

%appdata%\OpenIG\config\routes\not-enforced-switch.json

{
  "properties": {
    "notEnforcedPathPatterns": "^/home|^/favicon.ico|^/css"
  },
  "heap": [
    {
      "name": "SystemAndEnvSecretStore-1",
      "type": "SystemAndEnvSecretStore"
    },
    {
      "name": "AmService-1",
      "type": "AmService",
      "config": {
        "agent": {
          "username": "ig_agent",
          "passwordSecretId": "agent.secret.id"
        },
        "secretsProvider": "SystemAndEnvSecretStore-1",
        "url": "http://am.example.com:8088/openam/"
      }
    }
  ],
  "name": "not-enforced-switch",
  "condition": "${find(request.uri.path, '^/')}",
  "baseURI": "http://app.example.com:8081",
  "handler": {
    "type": "Chain",
    "config": {
      "filters": [
        {
          "name": "SwitchFilter-1",
          "type": "SwitchFilter",
          "config": {
            "onRequest": [{
              "condition": "${find(request.uri.path, '&{notEnforcedPathPatterns}')}",
              "handler": "ReverseProxyHandler"
            }]
          }
        },
        {
          "type": "SingleSignOnFilter",
          "config": {
            "amService": "AmService-1"
          }
        },
        {
          "type": "PasswordReplayFilter",
          "config": {
            "loginPage": "${true}",
            "credentials": {
              "type": "FileAttributesFilter",
              "config": {
                "file": "/tmp/userfile.txt",
                "key": "email",
                "value": "${contexts.ssoToken.info.uid}@example.com"
              }
            },
            "request": {
              "method": "POST",
              "uri": "http://app.example.com:8081/login",
              "form": {
                "username": [
                  "${contexts.fileAttributes.record.username}"
                ],
                "password": [
                  "${contexts.fileAttributes.record.password}"
                ]
              }
            }
          }
        }
      ],
      "handler": "ReverseProxyHandler"
    }
  }
}

Notice the following features of the route:

The route condition is /, so the route matches all requests.
The SwitchFilter passes requests on the path ^/home, ^/favicon.ico, and ^/css directly to the ReverseProxyHandler. All other requests continue the along the chain to the SingleSignOnFilter.
If the request does not have a valid AM session cookie, the SingleSignOnFilter redirects the request to AM for authentication. The SingleSignOnFilter stores the cookie value in an SsoTokenContext.
Because the PasswordReplayFilter detects that the response is a login page, it uses the FileAttributesFilter to replay the password, and logs the request into the sample application.

Test the setup:
1. If you are logged in to AM, log out and clear any cookies.
2. Access the route on the not-enforced URL http://ig.example.com:8080/home. The home page of the sample app is displayed without authentication.
3. Access the route on the enforced URL http://ig.example.com:8080/profile. The SingleSignOnFilter redirects the request to AM for authentication.
4. Log in to AM as user demo, password Ch4ng31t. The PasswordReplayFilter replays the credentials for the demo user. The request is passed to the sample app’s profile page for the demo user.

With a DispatchHandler

To use a DispatchHandler for not-enforced URIs, replace the route in With a SwitchFilter with the following route. If the request is on the path ^/home, ^/favicon.ico, or ^/css, the DispatchHandler sends it directly to the ReverseProxyHandler, without authentication. It passes all other requests into the Chain for authentication.

{
  "properties": {
    "notEnforcedPathPatterns": "^/home|^/favicon.ico|^/css"
  },
  "heap": [
    {
      "name": "SystemAndEnvSecretStore-1",
      "type": "SystemAndEnvSecretStore"
    },
    {
      "name": "AmService-1",
      "type": "AmService",
      "config": {
        "agent": {
          "username": "ig_agent",
          "passwordSecretId": "agent.secret.id"
        },
        "secretsProvider": "SystemAndEnvSecretStore-1",
        "url": "http://am.example.com:8088/openam/"
      }
    }
  ],
  "name": "not-enforced-dispatch",
  "condition": "${find(request.uri.path, '^/')}",
  "baseURI": "http://app.example.com:8081",
  "handler": {
    "type": "DispatchHandler",
    "config": {
      "bindings": [
        {
          "condition": "${find(request.uri.path, '&{notEnforcedPathPatterns}')}",
          "handler": "ReverseProxyHandler"
        },
        {
          "handler": {
            "type": "Chain",
            "config": {
              "filters": [
                {
                  "type": "SingleSignOnFilter",
                  "config": {
                    "amService": "AmService-1"
                  }
                },
                {
                  "type": "PasswordReplayFilter",
                  "config": {
                    "loginPage": "${true}",
                    "credentials": {
                      "type": "FileAttributesFilter",
                      "config": {
                        "file": "/tmp/userfile.txt",
                        "key": "email",
                        "value": "${contexts.ssoToken.info.uid}@example.com"
                      }
                    },
                    "request": {
                      "method": "POST",
                      "uri": "http://app.example.com:8081/login",
                      "form": {
                        "username": [
                          "${contexts.fileAttributes.record.username}"
                        ],
                        "password": [
                          "${contexts.fileAttributes.record.password}"
                        ]
                      }
                    }
                  }
                }
              ],
              "handler": "ReverseProxyHandler"
            }
          }
        }
      ]
    }
  }
}

PingGateway 2024.9

Not-enforced URIs

With a SwitchFilter

With a DispatchHandler