Processing Requests and Responses

The following sections describe how IG processes requests and responses:

IG Object Model

IG processes HTTP requests and responses by passing them through user-defined chains of filters and handlers. The filters and handlers provide access to the request and response at each step in the chain, and make it possible to alter the request or response, and collect contextual information.

The following image illustrates a typical sequence of events when IG processes a request and response through a chain:

Flow Inside a Chain

When IG processes a request, it first builds an object representation of the request, including parsed query/form parameters, cookies, headers, and the entity. IG initializes a runtime context to provide additional metadata about the request and applied transformations. IG then passes the request representation into the chain.

In the request flow, filters modify the request representation and can enrich the runtime context with computed information. In the ClientHandler, the entity content is serialized, and additional query parameters can be encoded as described in RFC-3986.

In the response flow, filters build a response representation with headers and the entity.

The route configuration in "Adding Headers and Logging Results" demonstrates the flow through a chain to a protected application.

Configuring IG

The way that IG processes requests and responses is defined by the configuration files admin.json and config.json, and by Route configuration files. For information about the different files used by IG, see "Configuration Directories and Files".

Configuration files are flat JSON files that define objects with the following parts:

  • name: A unique string to identify the object. When you declare inline objects, the name is not required.

  • type: The type name of the object. IG defines many object types for different purposes.

  • config: Additional configuration settings for the object. The content of the configuration object depends on its type. For information about each object type available in the IG configuration, see the Configuration Reference.

    If all of the configuration settings for the type are optional, the config field is also optional. The object uses default settings when the config field isn't configured, or is configured as an empty object ("config": {}), or is configured as null ("config": null).

    Filters, handlers, and other objects whose configuration settings are defined by strings, integers, or booleans, can be defined by expressions that match the expected type.

For information about the objects available, see "AdminHttpApplication (admin.json)" "GatewayHttpApplication (config.json)" and "Route". An IG route typically contains at least the following parts:

  • handler: An object to specify the point where the request enters the route. If the handler type is a Chain, the request is dispatched to a list of filters, and then to another handler.

    Handler objects produce a response for a request, or delegate the request to another handler. Filter objects transform data in the request, response, or context, or perform an action when the request or response passes through the filter.

  • baseURI: A handler decorator to override the scheme, host, and port of the request URI. After a route processes a request, it reroutes the request to the baseURI, which most usually points to the application or service that IG is protecting.

  • heap: A collection of named objects configured in the top level of config.json or in individual routes. Heap objects can be configured once and used multiple times in the configuration.

    A heap object in a route can be used in that route. A heap object in config.json can be used across the whole configuration, unless it is overridden in a route.

  • condition: An object to define a condition that a request must meet. A route can handle a request if condition is not defined, or if the condition resolves to true.

Routes inherit settings from their parent configurations. This means that you can configure objects in the config.json heap, for example, and then reference those objects by name in any other IG configuration.

Configuration Directories and Files

By default, IG configuration files are located under $HOME/.openig on Linux, macOS, and UNIX systems, and %appdata%\OpenIG on Windows systems. For information about how to change the default locations, see "Changing the Default Location of the Configuration Folders".

IG uses the following configuration directories:

IG Configuration Directories and Files
Purpose Default location on Linux, macOS, and UNIX systems Default location on Windows

Administration and gateway configuration, admin.json and config.json. For more information, see "AdminHttpApplication (admin.json)" and "GatewayHttpApplication (config.json)"

$HOME/.openig/config

%appdata%\OpenIG\config

Route configuration files. For more information, see Configuring Routers and Routes.

$HOME/.openig/config/routes

%appdata%\OpenIG\config\routes

SAML 2.0 configuration files. For more information, see Acting As a SAML 2.0 Service Provider.

$HOME/.openig/SAML

%appdata%\OpenIG\SAML

Script files, for Groovy scripted filters and handlers. For more information, see Extending IG.

$HOME/.openig/scripts/groovy

%appdata%\OpenIG\scripts\groovy

Temporary storage files.

To change the directory, configure the property temporaryDirectory in admin.json. For more information, see "AdminHttpApplication (admin.json)".

$HOME/.openig/tmp

%appdata%\OpenIG\tmp

JSON schema for the topic of a custom audit event. For more information, see "Recording Custom Audit Events".

To change the directory, configure the property topicsSchemasDirectory in AuditService. For more information, see "AuditService".

$HOME/.openig/audit-schemas

%appdata%\OpenIG\audit-schemas


Using Comments in IG Configuration Files

The JSON format does not specify a notation for comments. If IG does not recognize a JSON field name, it ignores the field. As a result, it is 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
  }
}
Read a different version of :