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.