Untitled | ForgeRock Identity Gateway

Studio

This guide gives an overview of how to use Studio to design and develop routes to protect applications.

Start with Studio

PingGateway Studio is a user interface to help you build and deploy your PingGateway configuration. There are two ways to create routes in Studio:

With the structured editor (deprecated) to build simple routes by using predefined menus and templates. The structured editor presents valid options and default values as you add filters, decorators, and other objects to your configuration.
With the FreeForm Designer to design complex, multi-branched routes. Drag handlers and filters from a side bar onto the canvas to begin designing the route. The FreeForm Designer helps you to visualize the chain, and track the path of requests, responses, and contexts.

After installation, PingGateway is by default in production mode. The /routes endpoint is not exposed or accessible, and Studio is effectively disabled. To access Studio, switch to development mode. For example, add the following configuration to admin.json, and restart PingGateway:

{
  "mode": "DEVELOPMENT",
  "connectors": [
    { "port" : 8080 }
  ]
}

For additional details, refer to Operating modes.

If you provide a custom config.json, include a main router named _router. If a custom config.json is not provided, PingGateway includes this router by default.

When PingGateway is installed and running in development mode, as described in Quick install, access Studio on http://ig.example.com:8080/openig/studio. The Routes screen is displayed:

The [.label]#Routes# screen is displayed in Studio.

During PingGateway upgrade, routes that were previously created in Studio are automatically transferred to the new version of PingGateway. Where possible, PingGateway replaces deprecated settings with the newer evolved setting. If PingGateway needs additional information to upgrade the route, the route status becomes Compatibility update required. Select the route and provide the requested information.

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

Upgrade from an earlier version of Studio

From PingGateway 2024.3, Studio manages the migration of deprecated objects for routes created and managed in earlier versions of Studio.

PingGateway doesn’t manage migration for the following:

Routes in Studio editor mode
Custom filters in routes
Migration for routes containing secrets
PingGateway automatically:

Updates the route to use SecretsProvider and SecretIds

Removes references to the password

You must manually create the required SecretsProvider in config.json and create its referenced secrets.
Migration for routes containing Splunk or ElasticSearch audit event handlers

PingGateway automatically deletes the Splunk or ElasticSearch audit event handlers from the route.

Create and edit routes with Structured Editor (deprecated)

This section describes basic tasks for creating and deploying routes in the structured editor of Studio.

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

Creating simple routes

In PingGateway Studio, create a route:
1. Go to http://ig.example.com:8080/openig/studio, and select Create a route.
2. Select Structured to use the structured editor.
Enter the URL of the application you want to protect, followed by a path condition to access the route. For example, enter http://app.example.com:8081/my-basic-route.

The route is created, and menus to add configuration objects to the route are displayed.

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

A route similar to this is displayed, where the path condition is used for the route name:

{
  "name": "my-basic-route",
  "baseURI": "http://app.example.com:8081",
  "condition": "${find(request.uri.path, '^/my-basic-route')}",
  "handler": "ReverseProxyHandler"
}

Change the basic settings of a route

In Studio, select ROUTES, and then select a route with the icon.
On the top-right of the screen select Route settings.
Using the on-screen hints for guidance, change the name, condition, or other features of the route, and save the changes.
On the top-right of the screen, select and Display to review the route.

Adding configuration to a route

After creating a route in the structured editor, you can add filters, decorators, scripts, and other configuration to the route.

Add other configuration to a route

In Studio, select ROUTES, and then select a route with the icon.
Select one of the configuration options, and follow the on-screen hints to select configuration settings.

For routes to test with the examples in the Gateway guide, refer to Example routes created with Structured Editor (deprecated).

Add other filters to a route

Use this procedure to add any filter type to the configuration.

In Studio, select ROUTES, and then select a route with the icon.
Select Other filters > New filter > Other filter.
In Create filter, select a filter type from the list, enter a name, and optionally enter a configuration for the filter.

Studio checks that the JSON is valid, but doesn’t check that the configuration of the filter is valid. If the filter configuration isn’t valid, when you deploy the route it fails to load.

When you save, the filter is added to the list of other filters but is not added to the configuration.
Enable the filter to add it to the configuration.

If you disable the filter again, it is removed from the route’s chain but the configuration is saved. Simply enable the filter again to add it back in the chain.

Managing the route chain

The Chain view lists the filters in the order that they appear in the configuration.

Some filters have a natural position in the chain. For example, so that an authenticated user is given the correct permissions, an authentication filter must come before an authorization filter. Similarly, so that an authorization token is transformed, an authorization filter always comes before a token transformation filter.

Other filters have a flexible position in the chain. For example, an AssignmentFilter can be used before a request is handled or after a response is handled.

When the position of a filter is fixed, it is automatically placed in the correct position in the chain; you cannot change the position. When the position of a filter is flexible, the icon is displayed, and you can drag the filter into a different position in the chain.

Select Chain to view and manage the filters in the chain as follows:

When the icon is displayed, drag a filter up or down the chain.
Select to edit a filter.
Select Realm Settings to disable and remove a filter from the chain.

For information about chains, refer to Chain.

Deploy and undeploy routes

Deploy a Route

In Studio, select ROUTES, and then select a route created with the structured editor (with the icon).
On the top-right of the screen, select and Display to review the route.
If the route is okay, select Deploy to push the route to the PingGateway configuration.

If the route configuration is not valid, or if a service that the route relies on, such as an AM service, is not available, the route fails to deploy.

If the route deploys successfully, Deployed is displayed and the Deploy button is greyed out.
Check the $HOME/.openig/config/routes folder in your PingGateway configuration to see that the route is there.

By default, routes are loaded automatically into the PingGateway configuration. You don’t need to stop and restart PingGateway. For more information, refer to Prevent the reload of routes.
Check the system log to confirm that the route was loaded successfully into the configuration. For information about logs, refer to Manage logs.

Undeploy a Route

In Studio, select ROUTES and then select a route with the status Deployed.
On the top-right of the screen, select and Undeploy, and then confirm your request.

The route is removed from the PingGateway configuration. On the Studio screen, the route status Deployed is no longer displayed and the Deploy option is active again.

Create and edit routes with Freeform Designer

The following sections describe how to create a simple route in the FreeForm Designer of Studio, and then add configuration to the route. For examples of routes created with the FreeForm Designer that can be tested with the examples in the Gateway guide, refer to Example routes created with Freeform Designer.

Create a simple route

In PingGateway Studio, create a route:
1. Go to http://ig.example.com:8080/openig/studio, and then select Create a route.
2. Select Freeform to use the FreeForm Designer.
Select Basic to create a route from a blank template.
Enter a URL for the application you want to protect, followed by a path condition to access the route. For example, enter http://app.example.com:8081/my-basic-route.

The route is displayed on the Flow tab of the canvas.

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

{
  "name": "my-basic-route",
  "baseURI": "http://app.example.com:8081",
  "condition": "${find(request.uri.path, '^/my-basic-route')}",
  "handler": "ReverseProxyHandler",
  "heap": [
    {
      "name": "ReverseProxyHandler",
      "type": "ReverseProxyHandler"
    },
    {
      "type": "BaseUriDecorator",
      "name": "baseUri"
    },
    {
      "type": "TimerDecorator",
      "name": "timer",
      "config": {
        "timeUnit": "ms"
      }
    },
    {
      "type": "CaptureDecorator",
      "name": "capture",
      "config": {
        "captureEntity": false,
        "captureContext": false,
        "maxEntityLength": 524288
      }
    }
  ]
}

Change the basic settings of a route

Using the route created in freeform.adoc#studio-create-route-ff, on the top-right of the screen select Route settings.
Using the on-screen hints for guidance, change the name, condition, or other features of the route, and save the changes.
On the top-right of the screen, select and Display to review the route.

Add objects to a route heap

Using the route created in freeform.adoc#studio-create-route-ff, select All Objects > Create Object.
In Node Type, select an object type from the drop down list. For example, create an AmService object, using the following values:
- Name: AmService-1
- URI: http://am.example.com:8088/openam/
- Agent:
  - Agent: ig-agent
  - Password: password
    
    Use secure passwords in a production environment. Consider using a password manager to generate secure passwords.
  When you save, the object is added to route heap but is not used in the route.
On the top-right of the screen, select and Display to review the route.

Add configuration to a route

Using the route created in freeform.adoc#studio-create-route-ff, select the Flow tab, and delete the connector between Start and ReverseProxyHandler.
Drag a Chain from the side bar onto the canvas, and then drag a SingleSignOnFilter into the chain.
In the menu for the SingleSignOnFilter, enter the name of the AmService object you created in freeform.adoc#studio-add-objects-ff, AmService-1. The filter uses the object previously defined in the heap.
Connect Start to Chain-1, and Chain-1 to ReverseProxyHandler.
On the top-right of the screen, select and Display to review the route.

Decorate objects in the route

Using the route created in freeform.adoc#studio-create-route-ff, select the All Objects tab.

A list of objects in the route is displayed. By default, all available decorators are included in the route heap, but they do not decorate any objects.
For the ReverseProxyHandler or filter, select , select the Decorations tab, and then enable one or more of the decorators.
On the top-right of the screen, select and Display to review the route.

Edit and import routes

The following sections describe basic tasks for Edit and import routes in Studio:

Edit routes in editor mode

After creating a route in Studio, you can edit it by using the options offered in Studio, or by switching to editor mode and using the JSON editor.

Routes created only in the menus of structured editor have the icon . Routes created only in the menus of FreeForm Designer have the icon . Imported routes and routes edited in editor mode have the icon { }.

When you go into editor mode, you can use the JSON editor to manually edit the route, but can no longer use the full Studio interface to add to or edit the configuration.

In Studio, select ROUTES, and then select a route created with the structured editor (with the icon).
Edit the route in Studio or manually:
- To edit in Studio, select options offered in Studio.
- To edit manually, select and Editor mode and use the JSON editor to edit the route.
If the route status is Deployed, it changes to Changes pending.
Deploy the route as described in Deploying and undeploying routes.

Import routes into Studio

When you import a route into Studio, it is imported in editor mode. You can use the JSON editor to manually edit the route, but can’t use the full Studio interface to add or edit filters.

In Studio, select ROUTES and then Import a route.
Click in the window to import a route, or drag a route from your filesystem.

If the route has a name property, the name is automatically used for the Name and ID fields in Studio.
If necessary, make the following changes, and then select Import:
- If the Name and ID fields are empty, enter a unique name and ID for the route.
- If the Name and ID fields are outlined in red, the route name or ID already exists in Studio. Change the name and ID to be unique.
- If an error message is displayed, the route is not valid JSON. Fix the route and then try again to import it.
The route is added to the list of routes on the ROUTES page.
Deploy the route as described in Deploying and undeploying routes.

View and search for routes in your configuration

All of the routes that exist in your backend configuration are displayed on the ROUTES page, including imported routes and routes created outside Studio.

To search for a route, select ROUTES, and type part of the route name in the search box. Matching routes are displayed as you enter the search criteria.

Restrict access to Studio

When PingGateway is running in development mode, by default the Studio endpoint is open and accessible. To allow only specific users to access Studio, configure a StudioProtectionFilter with a SingleSignOnFilter or CrossDomainSingleSignOnFilter.

The following example uses a SingleSignOnFilter to require users to authenticate with AM before they can access Studio, and protects the request from Cross Site Request Forgery (CSRF) attacks.

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 admin.json configuration to PingGateway:

{
  "mode": "DEVELOPMENT",
  "properties": {
    "SsoTokenCookieOrHeader": "iPlanetDirectoryPro"
  },
  "connectors": [
    {
      "port": 8080
    },
    {
      "port": 8443
    }
  ],
  "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/",
        "ssoTokenHeader": "&{SsoTokenCookieOrHeader}"
      }
    },
    {
      "name": "StudioProtectionFilter",
      "type": "ChainOfFilters",
      "config": {
        "filters": [
          {
            "type": "SingleSignOnFilter",
            "config": {
              "amService": "AmService-1"
            }
          },
          {
            "type": "CsrfFilter",
            "config": {
              "cookieName": "&{SsoTokenCookieOrHeader}",
              "failureHandler": {
                "type": "StaticResponseHandler",
                "config": {
                  "status": 403,
                  "headers": {
                    "Content-Type": [
                      "text/plain"
                    ]
                  },
                  "entity": "Request forbidden"
                }
              }
            }
          }
        ]
      }
    }
  ]
}

Notice the following features of the configuration:

The mode is development, so by default the Studio endpoint is open and unfiltered.
The properties object sets a configuration parameter for the value of the SSO token cookie or header, which is used in AmService and CorsFilter.
The AmService uses the PingGateway agent in AM for authentication.

The agent password for AmService is provided by a SystemAndEnvSecretStore in the heap.
The StudioProtectionFilter calls the SingleSignOnFilter to redirect unauthenticated requests to AM, and uses the CsrfFilter to protect requests from CSRF attacks. For more information, refer to SingleSignOnFilter and CsrfFilter.

Restart PingGateway to take into account the changes to admin.json.

Test the setup:
1. If you are logged in to AM, log out and clear any cookies.
2. Go to http://ig.example.com:8080/openig/studio. The SingleSignOnFilter redirects the request to AM for authentication.
3. Log in to AM with user demo, password Ch4ng31t. The Studio Routes screen is displayed.

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.

Example routes created with Freeform Designer

The following sections give examples of how to use the templates provided by the FreeForm Designer:

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

Use a basic template in FreeForm Designer

This section describes how to use a basic template in FreeForm Designer to set up SSO. For more information about setting up and testing 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 Freeform to use the FreeForm Designer.
Select Basic to create a route from a blank template.
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-ff
- Name: sso-ff
  
  The route is displayed on the Flow tab of the canvas. Select the All Objects tab to view a list of objects in the route.
  
  Double-click on any object to review or edit it. After double-clicking on an object, select the Decorations tab to decorate it.
Configure authentication with a SingleSignOnFilter:
1. In the Flow tab, delete the connector between Start and ReverseProxyHandler.
2. From the sidebar, drag a Chain onto the canvas, and then drag a SingleSignOnFilter into the chain.
3. In the Edit SingleSignOnFilter page, click , and create an AM service, with the following values:
  - URI: http://am.example.com:8088/openam
  - Secrets Provider: SystemAndEnvSecretStore-1
  - Agent:
    
    Username: ig_agent
    
    Password Secret ID : agent.secret.id
4. Connect Start to Chain-1, and Chain-1 to ReverseProxyHandler.

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

{
  "name": "sso-ff",
  "baseURI": "http://app.example.com:8081",
  "condition": "${find(request.uri.path, '^/home/sso-ff')}",
  "handler": "Chain-1",
  "heap": [
    {
      "name": "ReverseProxyHandler",
      "type": "ReverseProxyHandler"
    },
    {
      "type": "BaseUriDecorator",
      "name": "baseUri"
    },
    {
      "type": "TimerDecorator",
      "name": "timer",
      "config": {
        "timeUnit": "ms"
      }
    },
    {
      "type": "CaptureDecorator",
      "name": "capture",
      "config": {
        "captureEntity": false,
        "captureContext": false,
        "maxEntityLength": 524288
      }
    },
    {
      "name": "Chain-1",
      "type": "Chain",
      "config": {
        "handler": "ReverseProxyHandler",
        "filters": [
          "SingleSignOnFilter-1"
        ]
      }
    },
    {
      "name": "AmService-1",
      "type": "AmService",
      "config": {
        "url": "http://am.example.com:8088/openam",
        "realm": "/",
        "secretsProvider": "SystemAndEnvSecretStore-1",
        "agent": {
          "username": "ig_agent",
          "passwordSecretId": "agent.secret.id"
        },
        "sessionCache": {
          "enabled": false
        }
      }
    },
    {
      "name": "SingleSignOnFilter-1",
      "type": "SingleSignOnFilter",
      "config": {
        "amService": "AmService-1"
      }
    }
  ]
}

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.

Protect a web app with Freeform Designer

This section describes how to use FreeForm Designer to protect a web app, using AM for single sign-on and policy enforcement.

The generated route contains a chain of objects to authenticate the user, enforce an AM authorization policy, retrieve the user’s profile, insert it into the request, and, finally, forward the request to the web app.

Before you start, set up AM as described in 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 Freeform to use the FreeForm Designer.
Select Web SSO to use the template for protecting web apps.
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-ff
- Name : pep-sso-ff
- AM Configuration :
  - URI : http://am.example.com:8088/openam
  - Secrets Provider: SystemAndEnvSecretStore-1
  - Username : ig_agent
  - Password Secret ID : agent.secret.id
    
    The route is displayed on the Flow tab of the canvas. Select the All Objects tab to view a list of objects in the route.
    
    Double-click on any object to review or edit it. After double-clicking on an object, select the Decorations tab to decorate it.
On the Flow tab, double-click the Policy Enforcement object, and add a policy set with the following values:
- 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.

{
  "name": "pep-sso-ff",
  "baseURI": "http://app.example.com:8081",
  "condition": "${find(request.uri.path, '^/home/pep-sso-ff')}",
  "handler": "Chain",
  "heap": [
    {
      "name": "Chain",
      "type": "Chain",
      "config": {
        "handler": "ReverseProxyHandler",
        "filters": [
          "SSO",
          "Policy Enforcement",
          "GetEmail",
          "InjectEmail"
        ]
      }
    },
    {
      "name": "SSO",
      "type": "SingleSignOnFilter",
      "config": {
        "amService": "AmService"
      }
    },
    {
      "name": "ReverseProxyHandler",
      "type": "ReverseProxyHandler"
    },
    {
      "name": "AmService",
      "type": "AmService",
      "config": {
        "url": "http://am.example.com:8088/openam",
        "realm": "/",
        "secretsProvider": "SystemAndEnvSecretStore-1",
        "agent": {
          "username": "ig_agent",
          "passwordSecretId": "agent.secret.id"
        },
        "sessionCache": {
          "enabled": false
        }
      }
    },
    {
      "name": "Policy Enforcement",
      "type": "PolicyEnforcementFilter",
      "config": {
        "amService": "AmService",
        "ssoTokenSubject": "${contexts.ssoToken.value}",
        "cache": {
          "enabled": false
        },
        "application": "PEP-SSO"
      }
    },
    {
      "name": "GetEmail",
      "type": "UserProfileFilter",
      "config": {
        "username": "${contexts.ssoToken.info.uid}",
        "userProfileService": {
          "type": "UserProfileService",
          "config": {
            "amService": "AmService"
          }
        }
      }
    },
    {
      "name": "InjectEmail",
      "type": "HeaderFilter",
      "config": {
        "messageType": "REQUEST",
        "add": {
          "Email": [
            "${contexts.userProfile.username}"
          ]
        }
      }
    },
    {
      "type": "BaseUriDecorator",
      "name": "baseUri"
    },
    {
      "type": "TimerDecorator",
      "name": "timer",
      "config": {
        "timeUnit": "ms"
      }
    },
    {
      "type": "CaptureDecorator",
      "name": "capture",
      "config": {
        "captureEntity": false,
        "captureContext": false,
        "maxEntityLength": 524288
      }
    }
  ]
}

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.

Protect an API with Freeform Designer

This section describes how to use FreeForm Designer to protect APIs, using AM as an OAuth 2.0 Authorization Server.

The generated route contains a chain of objects to authenticate the user, throttle the rate of requests to the API, and, finally, forward the request to the sample app.

Before you start, 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 Freeform to use the FreeForm Designer.
Select API Security.
Select Advanced options on the right, and create a route with the following options:
- Base URI : http://app.example.com:8081
- Condition: Path : /home/rs-introspect-ff
- Name : rs-introspect-ff
- AM Configuration :
  - URI : http://am.example.com:8088/openam
  - Secrets Provider: SystemAndEnvSecretStore-1
  - Username : ig_agent
  - Password Secret ID : agent.secret.id
  - Scopes : mail, employeenumber
    
    The route is displayed on the Flow tab of the canvas.
    
    Notice that the Start, Chain, and ReverseProxyHandler objects are connected by solid lines, but other objects, such as Authenticate to Am Chain, are connected by a fading line. Objects connected by a fading line are used by other objects in the route.
    
    Select the All Objects tab to view a list of objects in the route. Double-click on any object to review or edit it. After double-clicking on an object, select the Decorations tab to decorate it.
On the Flow tab, double-click the OAuth2RS object, and edit it as follows:
- Require HTTPS : Deselect this option
- Realm : OpenIG
  
  Leave the other values as they are.

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

{
  "name": "rs-introspect-ff",
  "baseURI": "http://app.example.com:8081",
  "condition": "${find(request.uri.path, '^/home/rs-introspect-ff')}",
  "handler": "Chain",
  "properties": {
    "amSecretsProvider": "SystemAndEnvSecretStore-1",
    "amUsername": "ig_agent",
    "amPasswordSecretId": "agent.secret.id"
  },
  "heap": [
    {
      "name": "ClientHandler",
      "type": "ClientHandler"
    },
    {
      "name": "Chain",
      "type": "Chain",
      "config": {
        "handler": "ReverseProxyHandler",
        "filters": [
          "OAuth2RS",
          "Throttling"
        ]
      }
    },
    {
      "type": "OAuth2ResourceServerFilter",
      "name": "OAuth2RS",
      "config": {
        "requireHttps": false,
        "realm": "OpenIG",
        "scopes": [
          "mail",
          "employeenumber"
        ],
        "accessTokenResolver": "TokenIntrospectionAccessTokenResolver"
      }
    },
    {
      "type": "TokenIntrospectionAccessTokenResolver",
      "name": "TokenIntrospectionAccessTokenResolver",
      "config": {
        "amService": "AmService",
        "providerHandler": "Authenticate to AM Chain"
      }
    },
    {
      "name": "ReverseProxyHandler",
      "type": "ReverseProxyHandler"
    },
    {
      "name": "AmService",
      "type": "AmService",
      "config": {
        "url": "http://am.example.com:8088/openam",
        "realm": "/",
        "secretsProvider": "SystemAndEnvSecretStore-1",
        "agent": {
          "username": "ig_agent",
          "passwordSecretId": "agent.secret.id"
        },
        "sessionCache": {
          "enabled": false
        }
      }
    },
    {
      "name": "Authenticate to AM Chain",
      "type": "Chain",
      "config": {
        "handler": "ClientHandler",
        "filters": [
          "Authenticate to AM Filter"
        ]
      }
    },
    {
      "name": "Authenticate to AM Filter",
      "type": "HttpBasicAuthenticationClientFilter",
      "config": {
        "username": "ig_agent",
        "passwordSecretId": "password.secret.id",
        "secretsProvider": "SystemAndEnvSecretStore-1"
      }
    },
    {
      "name": "Throttling",
      "type": "ThrottlingFilter",
      "config": {
        "requestGroupPolicy": "${contexts.oauth2.info.sub}",
        "rate": {
          "numberOfRequests": 60,
          "duration": "60 s"
        }
      }
    },
    {
      "type": "BaseUriDecorator",
      "name": "baseUri"
    },
    {
      "type": "TimerDecorator",
      "name": "timer",
      "config": {
        "timeUnit": "ms"
      }
    },
    {
      "type": "CaptureDecorator",
      "name": "capture",
      "config": {
        "captureEntity": false,
        "captureContext": false,
        "maxEntityLength": 524288
      }
    }
  ]
}

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.

Test the setup:

In a terminal window, use a curl command similar to the following to retrieve an access token:

$ mytoken=$(curl -s \
--user "client-application:password" \
--data "grant_type=password&username=demo&password=Ch4ng31t&scope=mail%20employeenumber" \
http://am.example.com:8088/openam/oauth2/access_token | jq -r ".access_token")

Validate the access token returned in the previous step:
```
$ curl -v http://ig.example.com:8080/home/rs-introspect-ff --header "Authorization: Bearer ${mytoken}"
```
The HTML of the sample application is returned.

Appendix A: Summary of tasks, route status, and icons

The following tables summarize the basic tasks that you can do in Studio, and summarizes the icons and status displayed in Studio:

Task reference
To do this	Do this
Create a new route	Select ROUTES, Create a route.
Select a route	Select ROUTES, and then select a route to view.
Display the config of a selected route	Select a route, and then select and Display.
Deploy a selected route	Select a route, and then select Deploy.
Undeploy a selected route	Select a deployed route, and then select and Undeploy.
Change the basic config of a route	Select a route, and then select Route settings. Edit the route and save the changes.

Route status
Status	Description	Action
Undeployed	The route is saved in Studio but is not deployed to the backend.	Deploy the route. The status changes to Deployed.
Deployed	The route is saved in Studio and deployed to the backend.	None. The route has the same configuration in Studio and the backend.
Changes pending	The route has been deployed and then subsequently changed in Studio.	Deploy the route. The status changes to Deployed.
Out of sync	The route has been deployed and then subsequently changed in the backend, or in both Studio and the backend.	Select Deploy. A message informs you that a different version of the route is deployed in the backend. Select an option: Deploy: The version in Studio overwrites the backend. Import a route: The version in the backend overwrites Studio. When you import a route into Studio you go into editor mode. You can use the JSON editor to manually edit the route, but can no longer use the full Studio interface to add or edit filters.
Compatibility update required	The route was created in Studio in an earlier version of PingGateway. Some information is needed to complete the upgrade.	Enter the information as prompted, and then select Deploy to deploy the route.

Icons
Icon	Mode	Description
	Structured editor	The route was created and edited using the menus and options of structured editor.
{ }	Editor mode	The route was imported into Studio, or was created in Studio and then edited in editor mode.
	Freeform designer	The route was created on the canvas of FreeForm Designer.

PingGateway 2024.9

Studio

Start with Studio

Upgrade from an earlier version of Studio

Create and edit routes with Structured Editor (deprecated)

Creating simple routes

Change the basic settings of a route

Adding configuration to a route

Add other configuration to a route

Add other filters to a route

Managing the route chain

Deploy and undeploy routes

Deploy a Route

Undeploy a Route

Create and edit routes with Freeform Designer

Create a simple route

Change the basic settings of a route

Add objects to a route heap

Add configuration to a route

Decorate objects in the route

Edit and import routes

Edit routes in editor mode

Import routes into Studio

View and search for routes in your configuration

Restrict access to Studio

Example routes created with Structured Editor (deprecated)

Single sign-on in Structured Editor

Policy enforcement in Structured Editor

Policy enforcement for CDSSO in Structured Editor

Token validation using the introspection endpoint in Structured Editor

OpenID Connect in Structured Editor

Token transformation in Structured Editor

Simple throttling filter in Structured Editor

Mapped throttling filter in Structured Editor

Scriptable throttling filter in Structured Editor

Proxy for websocket traffic in Structured Editor

Example routes created with Freeform Designer

Use a basic template in FreeForm Designer

Protect a web app with Freeform Designer

Protect an API with Freeform Designer

Appendix A: Summary of tasks, route status, and icons