PingGateway 2024.6

PingGateway as a microgateway

This section describes how to use the ForgeRock Token Validation Microservice to resolve and cache OAuth 2.0 access tokens when protecting API resources. The section is based on the example in Introspecting stateful access tokens, in the Token Validation Microservice’s User guide.

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


Before you start, download and run the sample application as described in Use the sample application. The sample application acts as Microservice A.

  1. Set up the example in Introspect stateful access tokens, in the Token Validation Microservice’s 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

    • Windows

      "properties": {
        "introspectOAuth2Endpoint": ""
      "capture": "all",
      "name": "mgw",
      "baseURI": "",
      "condition": "${matches(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"

    Notice the following features of the route:

    • The route matches requests to PingGateway on, and rebases them to the sample application, on

    • 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:

      $ mytoken=$(curl -s \
      --request POST \
      --url \
      --user microservice-client:password \
      --data grant_type=client_credentials \
      --data scope=microservice-A --silent | jq -r .access_token)
    2. View the access token:

      $ echo $mytoken
    3. Call PingGateway to access microservice A:

      $ curl -v --header "Authorization: Bearer ${mytoken}"

      The home page of the sample application is displayed.

Copyright © 2010-2024 ForgeRock, all rights reserved.