---
title: PingGateway as a microgateway
description: This page describes how to use the ForgeRock Token Validation Microservice to resolve and cache OAuth 2.0 access tokens when protecting API resources. It's based on the example in Introspecting stateful access tokens in the Token Validation Microservice User guide.
component: pinggateway
version: 2026
page_id: pinggateway:gateway-guide:microgateway-protect-service
canonical_url: https://docs.pingidentity.com/pinggateway/2026/gateway-guide/microgateway-protect-service.html
revdate: 2025-10-15T18:45:22Z
keywords: ["Configuration", "Microgateway", "OAuth 2.0"]
---

# PingGateway as a microgateway

This page describes how to use the ForgeRock Token Validation Microservice to resolve and cache OAuth 2.0 access tokens when protecting API resources. It's based on the example in *Introspecting stateful access tokens* in the Token Validation Microservice [*User guide*](https://cdn-docs.pingidentity.com/archive/pdf/tvm/1/Token-Validation-Microservice-1-User-Guide.pdf).

For information about the architecture, refer to [PingGateway as a microgateway](../about/about-microgateway.html). The following figure illustrates the flow of information when a client requests access to a protected microservice, providing a stateful access token as credentials:

![mgw](https://kroki.io/plantuml/svg/eNqFk79u20AMxvd7CsJLliYpPHQwigJGhqJDgKB22yXL-URJRM9HlXcnxX2jvkafrDzJduzCdScJ4kd-P_6Rub8x8MDdTqhpE_z-BfO38znclsc7eKLQwKcKQ6K0U5l0LDYRB2Ng3VIExxWCPhPDBiFHrABfnM-RevQ7oKCKENCVHBgotVdKQuQ6DVYQWCCi9OQw3pl_ZwAH9eC6RokQs2svVihsHhvrYaxAGA0MLUNreyyfUBSagqosbChUxc1rYogIthHErYr-w35nbu6NsTlxyNsNiumsJHLUWU2dPZIT3uPAgyfNn4GN-1ez4ReYPQknHZOinKpnFwo1NuFgd2OFx4_frlgtR82y6wyGSl3OpWv-jgG-Wk_VNM0z45KpsfOUZU4tC_2c9CuVokweq9PmzdQY3H4ogLCAz_gjY0wgGDmLktXCW-iOLW9PnN88Bw30NO4hJm22zh6s002WVRZmNXS6tLIG66MpHmqltK9Ok7A_Nmc0Cu9VtVwtYH0pOMEutKswnoMCdfu7Vezs08FH53lNpeGj6oueUGrxolARn0OFjvQHGlpUmZRLtd7zAG4a4NT1oeQr3mGOB6Rp3n8H_wCpJV00)

Before you begin, follow the instructions in [Using the sample application](../getting-started/start-sampleapp.html) to have the sample application listening at `https://app.example.com:8444` with PingGateway trusting it for HTTPS and ready to serve static resources. The sample application acts as Microservice A.

1. Set up the example in *Introspecting stateful access tokens* in the Token Validation Microservice *User guide*.

2. In AM, edit the microservice client to add a scope to access the protected microservice:

   1. Select Applications > OAuth 2.0 > Clients.

   2. Select `microservice-client`, and add the scope `microservice-A`.

3. Add the following route to PingGateway:

   * Linux

     `$HOME/.openig/config/routes/mgw.json`

   * Windows

     `%appdata%\OpenIG\config\routes\mgw.json`

   ```json
   {
     "properties": {
       "introspectOAuth2Endpoint": "http://mstokval.example.com:9090"
     },
     "capture": "all",
     "name": "mgw",
     "baseURI": "https://app.example.com:8444",
     "condition": "${find(request.uri.path, '^/home/mgw')}",
     "handler": {
       "type": "Chain",
       "config": {
         "filters": [
           {
             "name": "OAuth2ResourceServerFilter-1",
             "type": "OAuth2ResourceServerFilter",
             "config": {
               "requireHttps": false,
               "accessTokenResolver": {
                 "name": "TokenIntrospectionAccessTokenResolver-1",
                 "type": "TokenIntrospectionAccessTokenResolver",
                 "config": {
                   "endpoint": "&{introspectOAuth2Endpoint}/introspect",
                   "providerHandler": "ForgeRockClientHandler"
                 }
               },
               "scopes": ["microservice-A"]
             }
           }
         ],
         "handler": "ReverseProxyHandler"
       }
     }
   }
   ```

   Source: [mgw.json](../_attachments/config/routes/mgw.json)

   Notice the following features of the route:

   * The route matches requests to PingGateway on `http://ig.example.com:8080/home/mgw`, and rebases them to the sample application, on `https://app.example.com:8444`.

   * The OAuth2ResourceServerFilter expects an OAuth 2.0 access token in the header of the incoming authorization request, with the scope `microservice-A`.

   * If the filter successfully validates the access token, the ReverseProxyHandler passes the request to the sample application.

4. Test the setup:

   1. With AM, PingGateway, the Token Validation Microservice, and the sample application running, get an access token from AM, using the scope `microservice-A`:

      ```console
      $ mytoken=$(curl -s \
      --request POST \
      --url http://am.example.com:8088/openam/oauth2/access_token \
      --user microservice-client:password \
      --data grant_type=client_credentials \
      --data scope=microservice-A --silent | jq -r .access_token)
      ```

   2. View the access token:

      ```console
      $ echo $mytoken
      ```

   3. Call PingGateway to access microservice A:

      ```console
      $ curl -v --header "Authorization: Bearer ${mytoken}" http://ig.example.com:8080/home/mgw
      ```

      The sample application returns its home page HTML.