IG 2023.2

IG 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 Introspect stateful access tokens, in the Token Validation Microservice’s User guide.

For information about the architecture, refer to IG 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 Using 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 IG:

    • Linux

    • Windows

      "properties": {
        "introspectOAuth2Endpoint": "http://mstokval.example.com:9090"
      "capture": "all",
      "name": "mgw",
      "baseURI": "http://app.example.com:8081",
      "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 IG on http://ig.example.com:8080/home/mgw, and rebases them to the sample application, on http://app.example.com:8081.

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

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

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

      The home page of the sample application is displayed.

Copyright © 2010-2023 ForgeRock, all rights reserved.