PingGateway 2024.9

Example routes created with Structured Editor (deprecated)

The following sections give examples of how to set up some of the routes used in the Gateway guide by using the structured editor of Studio.

The structured editor of Studio is deprecated. For more information, refer to the Deprecated section of the Release Notes.

SecretsProviders can’t be configured in Studio. Documentation examples generated with Studio might refer to SecretsProviders that must be configured separately in config.json.

Single sign-on in Structured Editor

This section describes how to set up SSO in the structured editor of Studio. For more information about setting up SSO, refer to Authentication.

  1. In PingGateway Studio, create a route:

    1. Go to http://ig.example.com:8080/openig/studio, and then select Create a route.

    2. Select Structured to use the structured editor.

  2. Select Advanced options on the right, and create a route with the following options:

    • Base URI: http://app.example.com:8081

    • Condition: Path: /home/sso-studio

    • Name : sso-studio

  3. Configure authentication:

    1. Select Authentication.

    2. Select Single Sign-On, and enter the following information:

      • AM service : Configure an AM service to use for authentication:

        • URI: http://am.example.com:8088/openam

        • Secrets Provider: SystemAndEnvSecretStore-1

        • Agent :

          • Username : ig_agent

          • Password Secret ID : password.secret.id

      Leave all other values as default.

  4. On the top-right of the screen, select and Display to review the route.

  5. Select Deploy to push the route to the PingGateway configuration.

    You can check the $HOME/.openig/config/routes folder to see that the route is there.

Policy enforcement in Structured Editor

This section describes how to set up PingGateway as a policy enforcement point in the structured editor of Studio. For more information about setting up policy enforcement, refer to Enforce AM policy decisions.

  1. In PingGateway Studio, create a route:

    1. Go to http://ig.example.com:8080/openig/studio, and then select Create a route.

    2. Select Structured to use the structured editor.

  2. Select Advanced options on the right, and create a route with the following options:

    • Base URI: http://app.example.com:8081

    • Condition: Path: /home/pep-sso

    • Name : pep-sso

    The structured editor is displayed.

  3. Configure authentication:

    1. Select Authentication.

    2. Select Single Sign-On, and enter the following information:

      • AM service : Configure an AM service to use for authentication:

        • URI: http://am.example.com:8088/openam

        • Secrets Provider: SystemAndEnvSecretStore-1

        • Agent : The credentials of the agent you created in AM.

          • Username : ig_agent

          • Password Secret ID : password.secret.id

    Leave all other values as default.

  4. Configure a PolicyEnforcementFilter:

    1. Select Authorization.

    2. Select AM Policy Enforcement, and then select the following options:

      • Access Management configuration:

        • AM service : http://am.example.com:8088/openam (/).

      • Access Management policies:

        • Policy set : PEP-SSO

        • AM SSO token : ${contexts.ssoToken.value}

      Leave all other values as default.

  5. On the top-right of the screen, select and Display to review the route.

  6. Select Deploy to push the route to the PingGateway configuration.

    You can check the $HOME/.openig/config/routes folder to see that the route is there.

Policy enforcement for CDSSO in Structured Editor

This section describes how to set up PingGateway as a policy enforcement point for CDSSO in the structured editor of Studio. For more information about how to set up SSO, refer to Decisions in different domains

  1. In PingGateway Studio, create a route:

    1. Go to http://ig.example.com:8080/openig/studio, and then select Create a route.

    2. Select Structured to use the structured editor.

  2. Select Advanced options on the right, and create a route with the following options:

    • Base URI: http://app.example.com:8081

    • Condition: Path: /home/pep-cdsso

    • Name : pep-cdsso

  3. Configure authentication:

    1. Select Authentication.

    2. Select Cross-Domain Single Sign-On, and enter the following information:

      • AM service :

        • URI: http://am.example.com:8088/openam

        • Secrets Provider: SystemAndEnvSecretStore-1

        • Agent : The credentials of the agent you created in AM.

          • Username : ig_agent_cdsso

          • Password Secret ID : password.secret.id

      • Redirect endpoint : /home/pep-cdsso/redirect

      • Authentication cookie :

        • Path : /home

    Leave all other values as default.

  4. Configure a PolicyEnforcementFilter:

    1. Select Authorization.

    2. Select AM Policy Enforcement, and select the following options to reflect the configuration of the PingGateway agent in AM:

      • Access Management configuration:

        • AM service : http://am.example.com:8088/openam (/).

      • Access Management policies:

        • Policy set : PEP-CDSSO

        • AM SSO token ID : ${contexts.cdsso.token}

      Leave all other values as default.

  5. On the top-right of the screen, select and Display to review the route.

  6. Select Deploy to push the route to the PingGateway configuration.

    You can check the $HOME/.openig/config/routes folder to see that the route is there.

Token validation using the introspection endpoint in Structured Editor

This section sets up PingGateway as an OAuth 2.0 resource server, using the introspection endpoint, in the structured editor of Studio.

  1. Set up AM as described in Validate access tokens with introspection. In addition, create an OAuth 2.0 Client authorized to introspect tokens with the following values:

    • Client ID : resource-server

    • Client secret password

    • Scope(s) : am-introspect-all-tokens

  2. In PingGateway Studio, create a route:

    1. Go to http://ig.example.com:8080/openig/studio, and then select Create a route.

    2. Select Structured to use the structured editor.

    3. Create a route with the following option:

      • Application URL: http://app.example.com:8081/rs-introspect-se

  3. Configure authorization:

    1. Select Authorization > OAuth 2.0 Resource Server, and then select the following options:

      • Token resolver configuration:

        • Access token resolver: OAuth 2.0 introspection endpoint

        • Introspection endpoint URI: http://am.example.com:8088/openam/oauth2/introspect

        • Client name and Client secret : resource-server and password

          This is the name and password of the OAuth 2.0 client with the scope to examine (introspect) tokens, configured in AM.

      • Scope configuration:

        • Evaluate scopes: Statically

        • Scopes: mail, employeenumber

      • OAuth 2.0 Authorization settings:

        • Require HTTPS: Deselect this option

        • Enable cache: Deselect this option

    Leave all other values as default.

  4. Add a StaticResponseHandler:

    1. On the top-right of the screen, select and Editor mode to switch into editor mode.

      After switching to Editor mode, you cannot go back. You will be able to use the JSON file editor to manually edit the route but will no longer be able use the full Studio interface to add or edit filters.
    2. Replace the last ReverseProxyHandler in the route with the following StaticResponseHandler, and then save the route:

      "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>"
        }
      }
  5. On the top-right of the screen, select and Display to review the route.

  6. Select Deploy to push the route to the PingGateway configuration.

    You can check the $HOME/.openig/config/routes folder to see that the route is there.

OpenID Connect in Structured Editor

This section describes how to set up PingGateway as an OpenID Connect relying party in the structured editor of Studio. For more information, refer to AM as OIDC provider.

  1. In PingGateway Studio, create a route:

    1. Go to http://ig.example.com:8080/openig/studio, and then select Create a route.

    2. Select Structured to use the structured editor.

  2. Select Advanced options on the right, and create a route with the following options:

    • Base URI: http://app.example.com:8081

    • Condition: Path: /home/id_token

    • Name: 07-openid

  3. Configure authentication:

    1. Select Authentication.

    2. Select OpenID Connect, and then select the following options:

      • Client Filter:

        • Client Endpoint: /home/id_token

        • Require HTTPS: Deselect this option

      • Client Registration:

        • Client ID: oidc_client

        • Client secret: password

        • Scopes: openid, profile, and email

        • Basic authentication: Select this option

      • Issuer:

        • Well-known Endpoint: http://am.example.com:8088/openam/oauth2/.well-known/openid-configuration

      Leave all other values as default.

  4. On the top-right of the screen, select and Display to review the route.

  5. Select Deploy to push the route to the PingGateway configuration.

    You can check the $HOME/.openig/config/routes folder to see that the route is there.

Token transformation in Structured Editor

This section describes how to set up token transformation in the structured editor of Studio. For more information about setting up token transformation, refer to OIDC ID tokens to SAML assertions.

  1. In PingGateway Studio, create a route:

    1. Go to http://ig.example.com:8080/openig/studio, and then select Create a route.

    2. Select Structured to use the structured editor.

  2. Select Advanced options on the right, and create a route with the following options:

    • Base URI: http://app.example.com:8081

    • Condition: Path: /home/id_token

    • Name : 50-idtoken

  3. Configure authentication:

    1. Select Authentication.

    2. Select OpenID Connect, and enter the following information:

      • Client Filter :

        • Client Endpoint: /home/id_token

        • Require HTTPS: Deselect this option

      • Client Registration :

        • Client ID : oidc_client

        • Client secret : password

        • Scopes: openid, profile, and email

        • Basic authentication: Select this option

      • Issuer :

        • Well-known endpoint: http://am.example.com:8088/openam/oauth2/.well-known/openid-configuration

    Leave all other values as default, and save your settings.

  4. Set up token transformation:

    1. Select and enable Token transformation.

    2. Enter the following information:

      • AM service : Configure an AM service to use for authentication and REST STS requests.

        • URI: http://am.example.com:8088/openam

        • Secrets Provider: SystemAndEnvSecretStore-1

        • Agent : The credentials of the agent you created in AM.

          • Username : ig_agent

          • Password Secret ID : password.secret.id

      • Username : oidc_client

      • Password : password

      • id_token : ${attributes.openid.id_token}

      • Instance : openig

  5. Add a StaticResponseHandler:

    1. On the top-right of the screen, select and Editor mode to switch into editor mode.

      After switching to Editor mode, you cannot go back. You will be able to use the JSON file editor to manually edit the route but will no longer be able use the full Studio interface to add or edit filters.
    2. Replace the last ReverseProxyHandler in the route with the following StaticResponseHandler, and then save the route:

      "handler": {
        "type": "StaticResponseHandler",
        "config": {
          "status": 200,
          "headers": {
            "Content-Type": [ "text/plain; charset=UTF-8" ]
          },
          "entity": "{\"id_token\":\n\"${attributes.openid.id_token}\"} \n\n\n{\"saml_assertions\":\n\"${contexts.sts.issuedToken}\"}"
        }
      }
  6. On the top-right of the screen, select and Display to review the route.

  7. Select Deploy to push the route to the PingGateway configuration.

    You can check the $HOME/.openig/config/routes folder to see that the route is there.

Simple throttling filter in Structured Editor

This section describes how to set up a simple throttling filter in the structured editor of Studio. For more information about how to set up throttling, refer to Configure simple throttling.

  1. In PingGateway Studio, create a route:

    1. Go to http://ig.example.com:8080/openig/studio, and then select Create a route.

    2. Select Structured to use the structured editor.

  2. Select Advanced options on the right, and create a route with the following options:

    • Base URI: http://app.example.com:8081

    • Condition: Path: /home/throttle-simple

    • Name : 00-throttle-simple

  3. Select and enable Throttling.

  4. In GROUPING POLICY, apply the rate to a single group.

    All requests are grouped together, and the default throttling rate is applied to the group. By default, no more than 100 requests can access the sample application each second.

  5. In RATE POLICY, select Fixed, and allow 6 requests each 10 seconds.

  6. On the top-right of the screen, select and Display to review the route.

  7. Select Deploy to push the route to the PingGateway configuration.

    You can check the $HOME/.openig/config/routes folder to see that the route is there.

Mapped throttling filter in Structured Editor

This section describes how to set up a mapped throttling filter in the structured editor of Studio. For more information about how to set up throttling, refer to Configure mapped throttling.

  1. Set up AM as described in Validate access tokens with introspection. In addition, create an OAuth 2.0 Client authorized to introspect tokens with the following values:

    • Client ID : resource-server

    • Client secret password

    • Scope(s) : am-introspect-all-tokens

  2. In PingGateway Studio, create a route:

    1. Go to http://ig.example.com:8080/openig/studio, and then select Create a route.

    2. Select Structured to use the structured editor.

  3. Select Advanced options on the right, and create a route with the following options:

    • Base URI: http://app.example.com:8081

    • Condition: Path: /home/throttle-mapped-se

    • Name : 00-throttle-mapped-se

  4. Configure authorization:

    1. Select Authorization > OAuth 2.0 Resource Server, and then select the following options:

      • Token resolver configuration:

        • Access token resolver: OAuth 2.0 introspection endpoint

        • Introspection endpoint URI: http://am.example.com:8088/openam/oauth2/introspect

        • Client name and Client secret : resource-server and password

          This is the name and password of the OAuth 2.0 client with the scope to examine (introspect) tokens, configured in AM.

      • Scope configuration:

        • Evaluate scopes: Statically

        • Scopes: mail, employeenumber

      • OAuth 2.0 Authorization settings:

        • Require HTTPS: Deselect this option

        • Enable cache: Deselect this option

    Leave all other values as default.

  5. Configure throttling:

    1. Select and enable Throttling.

    2. Set up the grouping policy:

      1. In GROUPING POLICY, apply the rate to independent groups of requests.

        Requests are split into different groups according to criteria, and the throttling rate is applied to each group.

      2. Select to group requests by custom criteria.

        Enter ${contexts.oauth2.accessToken.info.mail} as the custom expression. This expression defines the subject in the OAuth2Context.

    3. Set up the rate policy:

      1. In RATE POLICY, select Mapped.

      2. Select to map requests by custom criteria.

      3. Enter the custom expression ${contexts.oauth2.accessToken.info.status}.

      4. In Default Rate, select Edit and change default rate to 1 request each 10 seconds.

      5. In Mapped Rates, add the following rate for gold status:

        • Match Value : gold

        • Number of requests : 6

        • Period : 10 seconds

      6. Add a different rate for silver status:

        • Match Value : silver

        • Number of requests : 3

        • Period : 10 seconds

      7. Add a different rate for bronze status:

        • Match Value : bronze

        • Number of requests : 1

        • Period : 10 seconds

      8. Save the rate policy.

  6. Select Chain, and change the order of the filters so Throttling comes after Authorization.

  7. On the top-right of the screen, select and Display to review the route.

  8. Select Deploy to push the route to the PingGateway configuration.

    You can check the $HOME/.openig/config/routes folder to see that the route is there.

Scriptable throttling filter in Structured Editor

This section describes how to set up a scriptable throttling filter in the structured editor of Studio. For more information about how to set up throttling, refer to Configure scriptable throttling.

  1. Set up AM as described in Validate access tokens with introspection. In addition, create an OAuth 2.0 Client authorized to introspect tokens with the following values:

    • Client ID: resource-server

    • Client secret: password

    • Scope(s): am-introspect-all-tokens

  2. In PingGateway Studio, create a route:

    1. Go to http://ig.example.com:8080/openig/studio, and then select Create a route.

    2. Select Structured to use the structured editor.

  3. Select Advanced options on the right, and create a route with the following options:

    • Base URI: http://app.example.com:8081

    • Condition: Path: /home/throttle-scriptable-se

    • Name: 00-throttle-scriptable-se

  4. Configure authorization:

    1. Select Authorization > OAuth 2.0 Resource Server, and then select the following options:

      • Token resolver configuration:

        • Access token resolver: OAuth 2.0 introspection endpoint

        • Introspection endpoint URI: http://am.example.com:8088/openam/oauth2/introspect

        • Client name and Client secret : resource-server and password

          This is the name and password of the OAuth 2.0 client with the scope to examine (introspect) tokens, configured in AM.

      • Scope configuration:

        • Evaluate scopes: Statically

        • Scopes: mail, employeenumber

      • OAuth 2.0 Authorization settings:

        • Require HTTPS: Deselect this option

        • Enable cache: Deselect this option

    Leave all other values as default.

  5. Configure throttling:

    1. Select and enable Throttling.

    2. Set up the grouping policy:

      1. In GROUPING POLICY, apply the rate to independent groups of requests.

        Requests are split into different groups according to criteria, and the throttling rate is applied to each group.

      2. Select to group requests by custom criteria.

      3. Enter ${contexts.oauth2.accessToken.info.mail} as the custom expression.

    3. Set up the rate policy:

      1. In RATE POLICY, select Scripted.

      2. Select to create a new script, and name it X-User-Status. So that you can easily identify the script, use a name that describes the content of the script.

      3. Add the following argument/value pairs:

        • argument: status, value: gold

        • argument: rate, value: 6

        • argument: duration, value: 10 seconds

          • Replace the default script with the content of a valid Groovy script. For example, enter the following script:

            if (contexts.oauth2.accessToken.info.status == status) {
              return new ThrottlingRate(rate, duration)
            } else {
              return null
            }

            Alternatively, skip the step to define arguments, and add the following script instead:

            if (contexts.oauth2.accessToken.info.status == 'gold') {
              return new ThrottlingRate(6, '10 seconds')
            } else {
              return null
            }
            Studio does not check the validity of the Groovy script.
      4. Enable the default rate, and set it to 1 request each 10 seconds.

      5. Save the rate policy. The script is added to the list of reference scripts available to use in scriptable throttling filters.

  6. Select Chain, and change the order of the filters so Throttling comes after Authorization.

  7. On the top-right of the screen, select and Display to review the route.

  8. Select Deploy to push the route to the PingGateway configuration.

    You can check the $HOME/.openig/config/routes folder to see that the route is there.

Proxy for websocket traffic in Structured Editor

This section describes how to set up PingGateway to proxy WebSocket traffic, in the structured editor of Studio. For more information about how to set up proxying for WebSocket traffic, refer to WebSocket traffic.

  1. In PingGateway Studio, create a route:

    1. Go to http://ig.example.com:8080/openig/studio, and then select Create a route.

    2. Select Structured to use the structured editor.

  2. Select Advanced options on the right, and create a route with the following options:

    • Base URI: http://app.example.com:8081

    • Condition: Path: /websocket-se

    • Name : websocket-se

    • Enable WebSocket: Select this option

      1. Select Authentication.

      2. Select Single Sign-On, and enter the following information:

        • AM service : Configure an AM service to use for authentication:

          • URI: http://am.example.com:8088/openam

          • Secrets Provider: SystemAndEnvSecretStore-1

          • Agent :

            • Username : ig_agent

            • Password Secret ID : password.secret.id

      Leave all other values as default.

  3. On the top-right of the screen, select and Display to review the route.

  4. Select Deploy to push the route to the PingGateway configuration.

    You can check the $HOME/.openig/config/routes folder to see that the route is there.

Copyright © 2010-2024 ForgeRock, all rights reserved.