What is the ForgeRock Identity Gateway Route configuration and how does it work?

ForgeRock Identity Gateway (IG) is configured through a route-based model. Every inbound HTTP request is matched against a set of Routes, and the first matching route's handler chain processes the request. Routes are defined as JSON files (or via the Studio UI) stored in IG's configuration directory at ~/.openig/config/routes/.

A Route consists of:

• Condition — A boolean expression using IG's expression language that determines whether this route applies to the request. For example: ${matches(request.uri.path, '^/api/')} matches any request path starting with /api/.
• Handler — The processing chain that runs if the condition matches. This is typically a Chain handler containing an ordered list of filters followed by a final handler that forwards the request to the backend.
• Name — A unique identifier for the route, also used as the filename.

A minimal example route that validates an OAuth2 token and forwards to the backend:

{
  "name": "api-protection",
  "condition": "${matches(request.uri.path, '^/api/')}",
  "handler": {
    "type": "Chain",
    "config": {
      "filters": [
        {
          "type": "OAuth2ResourceServerFilter",
          "config": {
            "introspectionEndpoint": "https://am.example.com/oauth2/introspect",
            "clientId": "ig-client",
            "clientSecret": "changeit"
          }
        }
      ],
      "handler": "ReverseProxyHandler"
    }
  }
}

IG evaluates routes in filename order (alphabetical) and stops at the first match. A default catch-all route should be placed last to handle unmatched requests. Routes can be hot-reloaded — IG monitors the routes directory for file changes and reloads affected routes without restart, enabling live configuration updates in production.

Invest now in Acorns!!! 🚀
Join Acorns and get your $5 bonus!

Acorns is a micro-investing app that automatically invests your "spare change" from daily purchases into diversified, expert-built portfolios of ETFs. It is designed for beginners, allowing you to start investing with as little as $5. The service automates saving and investing. Disclosure: I may receive a referral bonus.

Invest now!!! Get Free equity stock (US, UK only)!

Use Robinhood app to invest in stocks. It is safe and secure. Use the Referral link to claim your free stock when you sign up!.

The Robinhood app makes it easy to trade stocks, crypto and more.

Webull! Receive free stock by signing up using the link: Webull signup.