Identity Gateway 2023.11

Configuration files and routes

IG processes requests and responses by using the following JSON files: admin.json, config.json, Route, and Router.

Configuration location

The following table summarizes the default location of the IG configuration and logs.

Purpose Default location on Linux Default location on Windows

Log messages from IG and third-party dependencies

$HOME/.openig/logs

%appdata%\OpenIG\logs

Administration (admin.json)

Gateway (config.json)

$HOME/.openig/config

%appdata%\OpenIG\config

Routes (Route)

$HOME/.openig/config/routes

%appdata%\OpenIG\config\routes

SAML 2.0

$HOME/.openig/SAML

%appdata%\OpenIG\OpenIG\SAML

Groovy scripts for scripted filters and handlers, and other objects

$HOME/.openig/scripts/groovy

%appdata%\OpenIG\scripts\groovy

Temporary directory

To change the directory, configure temporaryDirectory in admin.json

$HOME/.openig/tmp

%appdata%\OpenIG\OpenIG\tmp

JSON schema for custom audit

To change the directory, configure topicsSchemasDirectory in AuditService.

$HOME/.openig/audit-schemas

%appdata%\OpenIG\OpenIG\audit-schemas

Configuration security

Allow the following access to $HOME/.openig/logs, $HOME/.openig/tmp, and all configuration directories:

  • Highest privilege the IG system account.

  • Least priviledge for specific accounts, on a case-by-case basis

  • No priviledge for all other accounts, by default

Change the base location

By default, the base location for IG configuration files is in the following directory:

  • Linux

  • Windows

$HOME/.openig
%appdata%\OpenIG

Change the location in the following ways:

  • Edit the prefix property of admin.json.

  • Use an argument with the startup command. The following example reads the configuration from the config directory under /path/to/config-dir:

    • Linux

    • Windows

    $ /path/to/identity-gateway-2023.11.0/bin/start.sh /path/to/config-dir
    C:\path\to\identity-gateway-2023.11.0\bin\start.bat /path/to/config-dir

    == Route names, IDs, and filenames

The filenames of routes have the extension .json, in lowercase.

The router scans the $HOME/.openig/config/routes folder for files with the .json extension. It uses the route name property to order the routes in the configuration. If the route does not have a name property, the router uses the route ID.

The route ID is managed as follows:

  • When you add a route manually to the routes folder, the route ID is the value of the _id field. If there is no _id field, the route ID is the filename of the added route.

  • When you add a route through the Common REST endpoint, the route ID is the value of the mandatory _id field.

  • When you add a route through Studio, you can edit the default route ID.

The filename of a route can’t be default.json, and the route’s name property and route ID can’t be default.

Inline and heap objects

If you use an object only once in the configuration, you can declare it inline in the route and don’t need to name it. However, when you need use an object multiple times, declare it in the heap, and then refer to it by name in the route.

The following route shows an inline declaration for a handler. The handler is a router to route requests to separate route configurations:

{
  "handler": {
    "type": "Router"
  }
}

The following route shows a named router in the heap, and a handler references the router by its name:

{
  "handler": "My Router",
  "heap": [
    {
      "name": "My Router",
      "type": "Router"
    }
  ]
}

Notice that the heap is an array. Because the heap holds all configuration objects at the same level, you can impose any hierarchy or order when referring to objects. Note that when you declare all objects in the heap and refer to them by name, neither hierarchy nor ordering are obvious from the structure of the configuration file alone.

Comment the configuration

JSON format doesn’t specify a notation for comments. If IG does not recognize a JSON field name, it ignores the field. As a result, it’s possible to use comments in configuration files.

The following conventions are available for commenting:

  • A comment field to add text comments. The following example includes a text comment.

    {
  "name": "capture",
  "type": "CaptureDecorator",
  "comment": "Write request and response information to the logs",
  "config": {
    "captureEntity": true
  }
}

  • An underscore (_) to comment a field temporarily. The following example comments out "captureEntity": true, and as a result it uses the default setting ("captureEntity": false).

    {
  "name": "capture",
  "type": "CaptureDecorator",
  "config": {
    "_captureEntity": true
  }
}

Restart after configuration change

You can change routes or change a property that’s read at runtime or that relies on a runtime expression without needing to restart IG to take the change into account.

Stop and restart IG only when you make the following changes:

  • Change the configuration of any route, when the scanInterval of Router is disabled (see Router).

  • Add or change an external object used by the route, such as an environment variable, system property, external URL, or keystore.

  • Add or update config.json or admin.json.

Prevent reload of routes

To prevent routes from being reloaded after startup, stop IG, edit the router scanInterval, and restart IG. When the interval is set to disabled, routes are loaded only at startup:

{
  "name": "Router",
  "type": "Router",
  "config": {
    "scanInterval": "disabled"
  }
}

The following example changes the location where the router looks for the routes:

{
  "name": "Router",
  "type": "Router",
  "config": {
    "directory": "/path/to/safe/routes",
    "scanInterval": "disabled"
  }
}

Reserved routes

For information about reserved routes, refer to Reserved routes.

Copyright © 2010-2024 ForgeRock, all rights reserved.