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.

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

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

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

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
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
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.

Add a StaticResponseHandler:

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.

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

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

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

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.
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
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.
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

Add a StaticResponseHandler:

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

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

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

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.
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
Select and enable Throttling.
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.
In RATE POLICY, select Fixed, and allow 6 requests each 10 seconds.
On the top-right of the screen, select and Display to review the route.
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.

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
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.
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
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.
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.
Select Chain, and change the order of the filters so Throttling comes after Authorization.
On the top-right of the screen, select and Display to review the route.
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.

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
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.
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
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.
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.
Select Chain, and change the order of the filters so Throttling comes after Authorization.
On the top-right of the screen, select and Display to review the route.
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.

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

PingGateway 2024.9