PingGateway 2024.11

Configuration files and routes

PingGateway 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 PingGateway configuration and logs.

Purpose Default location on Linux Default location on Windows

Log messages from PingGateway 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\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\tmp

JSON schema for custom audit

To change the directory, configure topicsSchemasDirectory in AuditService.

$HOME/.openig/audit-schemas

%appdata%\OpenIG\audit-schemas

Configuration security

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

  • Highest privilege the PingGateway system account.

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

  • No privilege for all other accounts, by default

Change the base location

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

  • Linux

  • Windows

$HOME/.openig
%appdata%\OpenIG

Change the location by using 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-2024.11.0/bin/start.sh /path/to/config-dir
C:\path\to\identity-gateway-2024.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 doesn’t 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

Inline objects

An inline object is declared in a route or configuration, outside of the heap.

The following example shows an inline declaration for a handler to route requests:

{
  "handler": {
    "name": "My Router",
    "type": "Router"
  }
}

The name property for inline objects is optional but useful for logging.

Other objects in the configuration can never refer to named or unnamed inline objects.

Heap objects

A heap object is declared inside the heap.

The following example shows a named router in the heap, and a handler that refers to the router by its name:

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

The name property for heap objects is required. Other objects in the configuration or its child configirations can refer to the heap obect by its name property.

Comment the configuration

JSON format doesn’t specify a notation for comments. If PingGateway 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 PingGateway to take the change into account.

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

  • Change the configuration of any route, when the scanInterval of Router is disabled (refer to 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 PingGateway, edit the router scanInterval, and restart PingGateway. 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.