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 configuration file, expected by default at $HOME/.openig/config/config.json.

If you provide a config.json, the IG 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, see 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.

Important

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 that it contains a main router named _router.

Default Objects

IG creates the following objects by default in config.json:

BaseUriDecorator

Overrides the scheme, host, and port of the existing request URI. The default BaseUriDecorator is named baseURI. For more information, see "BaseUriDecorator".

AuditService

Records no audit events. The default AuditService is NoOpAuditService. For more information, see "NoOpAuditService".

CaptureDecorator

Captures requests and response messages. The default CaptureDecorator is named capture. For more information, see "CaptureDecorator".

ClientHandler

Communicates with third-party services. For more information, see "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.

ReverseProxyHandler

Communicates with third-party services. For more information, see "ReverseProxyHandler".

ScheduledExecutorService

Specifies the number of threads in a pool.

SecretsService

Manages a store of secrets from files, system properties, and environment variables, by using ForgeRock Commons Secrets Service. The default SecretsService is a SystemAndEnvSecretStore with the default configuration. For more information, see Secret Stores.

TemporaryStorage

Manages temporary buffers. To change the default values, add a TemporaryStorage object named TemporaryStorage, and use non-default values. For more information, see "TemporaryStorage".

TimerDecorator

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

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 IG cookie, called by default IG_SESSIONID.

For more information, see "Sessions" and "JwtSession".

Usage

{
  "handler": Handler reference or inline Handler declaration,
  "heap": [ configuration object, ... ],
  "properties": JSON object,
  "secrets": configuration object,
  "temporaryStorage": TemporaryStorage reference
}

Properties

"handler": Handler reference, required

Dispatch all requests to this handler.

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

See also Handlers.

"heap": array of configuration objects, optional

The heap object configuration, described in "Heap Objects".

You can omit an empty array. If you only have one object in the heap, you can inline it as the handler value.

"properties": JSON object, optional

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

Default: none

"secrets": configuration object, optional

An object that configures an inline array of one or more secret stores, as defined in "Default Secrets Object".

"temporaryStorage": TemporaryStorage reference, optional

Cache content during processing based on this TemporaryStorage configuration.

Provide either 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:

  • In standalone mode, the request is loaded into the IG temporary storage buffer, before it enters the chain. If the content length of a request is more than the buffer limit, IG returns an HTTP 413 Payload Too Large immediately.

  • In web container mode, the request is loaded into the web container buffer, which is managed externally. IG does not access the web container buffer until a filter, handler, or other object tries to access the request body. At that point, IG transfers the content of the web container buffer to its own temporary storage. If the web container buffer is bigger than the IG temporary storage, a buffer exception occurs.

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

See also "TemporaryStorage".

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 IG 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 IG welcome page, IG dispatches the request. Otherwise, IG returns an HTTP status 404 (Resource not found), because the requested resource does not exist.


Example config.json Used In the Doc

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 IG 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, see "JwtSession".


Read a different version of :