GatewayHttpApplication (`config.json` )

The GatewayHttpApplication is the entry point for all incoming gateway requests. It is responsible for initializing a heap of objects, described in Heap objects, and providing the main Handler that receives all the incoming requests.

The configuration is loaded from a JSON-encoded file, expected by default at $HOME/.openig/config/config.json. Objects configured in config.json can be used by config.json and any PingGateway route. They cannot be used by admin.json.

If you provide a config.json, the PingGateway configuration is loaded from that file. If there is no file, the default configuration is loaded. For the default configuration, and the example config.json used in many of the examples in the documentation, refer to the Examples section of this page.

Routes endpoint

The endpoint is defined by the presence and content of config.json, as follows:

When config.json is not provided, the routes endpoint includes the name of the main router in the default configuration, _router.
When config.json is provided with an unnamed main router, the routes endpoint includes the main router name router-handler.
When config.json is provided with a named main router, the routes endpoint includes the provided name or the transformed, URL-friendly name.

Studio deploys and undeploys routes through a main router named _router, which is the name of the main router in the default configuration. If you use a custom config.json, make sure it contains a main router named _router.

Default objects

PingGateway creates objects by default in config.json. To override a default object, configure an object with the same name in config.json.

Configure default objects in config.json and admin.json separately. An object configured in config.json with the same name as an object configured in admin.json is not the same object.

BaseUriDecorator: A decorator to override the scheme, host, and port of the existing request URI. The default BaseUriDecorator is named baseURI. For more information, refer to BaseUriDecorator.

AuditService

Records no audit events. The default AuditService is NoOpAuditService. Learn more from NoOpAuditService.

CaptureDecorator

Captures requests and response messages. The default CaptureDecorator is named capture, and uses the default settings given in CaptureDecorator.

When a capture point for the default CaptureDecorator is defined in a route, for example, when "capture: "all" is set as a top-level attribute of the JSON, log messages for requests and responses passing through the route are written to a log file in $HOME/.openig/logs.

When no capture point is defined in a route, only exceptions thrown during request or response processing are logged.

By default, request and response contexts and entities are not captured. Do one of the following to capture information:

Override the default capture decorator declaration, and set captureEntity to true.
Declare another CaptureDecorator object with an appropriate configuration and use it at your capture points.

The capture decorator logs information about the HTTP request and response messages, along with their respective headers.

ClientHandler

Communicates with third-party services. Learn more from ClientHandler.

ForgeRockClientHandler

Sends ForgeRock Common Audit transaction IDs when communicating with protected applications. The default ForgeRockClientHandler is a Chain, composed of a TransactionIdOutboundFilter and a ClientHandler.

IssuerRepository

A repository of Issuers declared in the heap. To overwrite the default issuer, configure a local IssuerRepository with the name IssuerRepository. To create a new IssuerRepository containing a subset of Issuers, configure a local IssuerRepository with a different name.

ProxyOptions

A proxy to which a ClientHandler or ReverseProxyHandler can submit requests, and an AmService can submit Websocket notifications. For more information, refer to ProxyOptions.

ReverseProxyHandler

Communicates with third-party services. For more information, refer to ReverseProxyHandler.

ScheduledExecutorService

Specifies the number of threads in a pool.

TemporaryStorage

Manages temporary buffers. For more information, refer to TemporaryStorage.

TimerDecorator

Records time spent within filters and handlers. The default TimerDecorator is named timer. For more information, refer to TimerDecorator.

TracingDecorator

Pushes traces to an OpenTelemetry service.

This capability is available in Technology preview. It isn’t yet supported, may be functionally incomplete, and is subject to change without notice.

Use this to decorate the following:

The default TracingDecorator is named tracing. PingGateway traces include Vert.x traces where applicable.

TransactionIdOutboundFilter

Inserts the ID of a transaction into the header of a request.

Sessions

When the heap is configured with a JwtSession object named Session, the object is used as the default session producer. Stateless sessions are created for all requests.

When a JwtSession is not configured for a request, session information is stored in the PingGateway cookie, called by default IG_SESSIONID.

For more information, refer to Sessions and JwtSession.

Usage

{
  "handler": Handler reference,
  "heap": [ object, ... ],
  "properties": object,
  "temporaryStorage": TemporaryStorage reference
}

Properties

"handler": Handler reference, required: The Handler to which PingGateway dispaches requests.

Provide the name of a Handler object defined in the heap or an inline Handler configuration object.

"heap": array of objects, optional

The heap object configuration, described in Heap objects.

"properties": object, optional

Configuration parameters declared as property variables for use in the configuration. See also Route properties.

Default: Null

"temporaryStorage": TemporaryStorage reference, optional

The TemporaryStorage object to buffer content during processing.

Provide the name of a TemporaryStorage object defined in the heap or an inline TemporaryStorage configuration object.

Incoming requests use the temporary storage buffer as follows:

Used only when streamingEnabled is false.
The request is loaded into the PingGateway storage defined in temporaryStorage, before it enters the chain.
If the content length of the request is more than the buffer limit, PingGateway returns an HTTP 413 Payload Too Large.

Default: Use the heap object named TemporaryStorage. Otherwise, use an internally-created TemporaryStorage object named TemporaryStorage that uses default settings for a TemporaryStorage object.

Example configuration files

Default configuration

When your configuration does not include a config.json file, the following configuration is provided by default.

{
    "heap": [
        {
            "name": "_router",
            "type": "Router",
            "config": {
                "scanInterval": "&{ig.router.scan.interval|10 seconds}",
                "defaultHandler": {
                    "type": "DispatchHandler",
                    "config": {
                        "bindings": [
                            {
                                "condition": "${request.method == 'GET' and request.uri.path == '/'}",
                                "handler": {
                                    "type": "WelcomeHandler"
                                }
                            },
                            {
                                "condition": "${request.uri.path == '/'}",
                                "handler": {
                                    "type": "StaticResponseHandler",
                                    "config": {
                                        "status": 405,
                                        "reason": "Method Not Allowed"
                                    }
                                }
                            },
                            {
                                "handler": {
                                    "type": "StaticResponseHandler",
                                    "config": {
                                        "status": 404,
                                        "reason": "Not Found"
                                    }
                                }
                            }
                        ]
                    }
                }
            }
        }
    ],
    "handler": "_router"
}

Notice the following features of the default configuration:

The handler contains a main router named _router. When PingGateway receives an incoming request, _router routes the request to the first route in the configuration whose condition is satisfied.
If the request doesn’t satisfy the condition of any route, it is routed to the defaultHandler. If the request is to access the PingGateway welcome page, PingGateway dispatches the request. Otherwise, PingGateway returns an HTTP status 404 (Resource not found), because the requested resource does not exist.

Example config.json used in the documentation

The following example of config.json is used in many of the examples in the documentation:

{
  "handler": {
    "type": "Router",
    "name": "_router",
    "baseURI": "http://app.example.com:8081",
    "capture": "all"
  },
  "heap": [
    {
      "name": "JwtSession",
      "type": "JwtSession"
    },
    {
      "name": "capture",
      "type": "CaptureDecorator",
      "config": {
        "captureEntity": true,
        "_captureContext": true
      }
    }
  ]
}

Notice the following features of the file:

The handler contains a main router named _router. When PingGateway receives an incoming request, _router routes the request to the first route in the configuration whose condition is satisfied.
The baseURI changes the request URI to point the request to the sample application.
The capture captures the body of the HTTP request and response.
The JwtSession object in the heap can be used in routes to store the session information as JSON Web Tokens (JWT) in a cookie. For more information, refer to JwtSession.

More information

org.forgerock.openig.http.GatewayHttpApplication

PingGateway 2024.9

GatewayHttpApplication (config.json )