Required Configuration

AdminHttpApplication (admin.json)

The AdminHttpApplication serves requests on the administrative route, such as the creation of routes and the collection of monitoring information. The administrative route and its subroutes are reserved for administration endpoints.

The configuration is loaded from a JSON-encoded configuration file, expected by default at $HOME/.openig/config/admin.json.

Default Objects

To override a default object, configure an object with the same name in admin.json.

IG provides the following default objects in admin.json:

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 Secrets.

TemporaryStorage

Manages temporary buffers. 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.

Provided Objects

To override a default object, configure an object with the same name in admin.json.

IG creates the following objects when a filter with the name of the object is declared in admin.json:

"ApiProtectionFilter"

A filter to protect administrative APIs on reserved routes. By default, only the loopback address can access reserved routes.

For information about reserved routes, see Reserved Routes.

"MetricsProtectionFilter"

A filter to protect the monitoring endpoints.

By default, the Prometheus Scrape Endpoint and Common REST Monitoring Endpoint are open and accessible; no special credentials or privileges are required to access the monitoring endpoints.

For an example of how to manage access, see Protecting the Monitoring Endpoints.

"StudioProtectionFilter"

A filter to protect the Studio endpoint when IG is running in development mode.

When IG is running in development mode, by default the Studio endpoint is open and accessible.

For information about accessing Studio, see the Studio Guide.

For information about restricting access to Studio in development mode, see Restricting Access to Studio.

Usage

{
   "heap": [ configuration object, ... ],
   "connectors": configuration object,
   "vertx": object,
   "gatewayUnits": configuration expression<number>,
   "mode": enumeration,
   "prefix": configuration expression<string>,
   "properties": JSON object,
   "secrets": configuration object,
   "temporaryDirectory": configuration expression<string>,
   "temporaryStorage": TemporaryStorage reference,
   "preserveOriginalQueryString": configuration expression<boolean>,
   "session": configuration object,
   "streamingEnabled": configuration expression<boolean>
}

Properties

"connectors": array of configuration objects, required
Supported only for IG in standalone mode.

Server port configuration, when IG is server-side.

When an application sends requests to IG, or requests services from IG, IG is acting as a server of the application (server-side), and the application is acting as a client.

{
  "connectors" : [
    {
      "port": configuration expression<number>, ...
      "tls": ServerTlsOptions reference,
      "vertx": object
    },
    {
      ...
    }
  ]
}
port: configuration expressions<number>, required

Port on which IG is connected. When more than one port is defined, IG is connected to each port.

tls: ServerTlsOptions reference, optional

Configure options for connections to TLS-protected endpoints, based on ServerTlsOptions. Define the object inline or in the heap.

Default: Connections to TLS-protected endpoints are not configured.

vertx: object, optional

Vert.x-specific configuration for this connector, where IG does not provide its own first-class configuration. Vert.x options are described in HttpServerOptions.

For properties where IG provides its own first-class configuration, Vert.x configuration options are disallowed, and the IG configuration option takes precedence over Vert.x options configured in vertx. The following Vert.x configuration options are disallowed server-side:

  • port

  • useAlpn

  • ssl

  • enabledCipherSuites

  • enabledSecureTransportProtocols

  • jdkSslEngineOptions

  • keyStoreOptions

  • openSslEngineOptions

  • pemKeyCertOptions

  • pemTrustOptions

  • pfxKeyCertOptions

  • pfxTrustOptions

  • trustStoreOptions

  • clientAuth

    The following example configures Vert.x-specific options for the connection on 8080, and TLS options for the connection on 8443:

    {
      "connectors": [{
        "port": 8080,
        "vertx": {
          "maxWebSocketFrameSize": 128000,
          "maxWebSocketMessageSize": 256000,
          "compressionLevel": 4
        }
      },
      {
        "port": 8443,
        "tls": "ServerTlsOptions-1"
      }]
    }
vertx: object, optional

Supported only for IG in standalone mode. Vert.x-specific configuration used to more finely-tune Vert.x instances. Vert.x options are described in VertxOptions.

"gatewayUnits": configuration expression<number>, optional

Supported only for IG in standalone mode. The number of parallel instances of IG to bind to an event loop. All instances listen on the same ports.

Default: The number of cores available to the JVM.

mode: operating mode, optional

Set the IG mode to development or production. The value is not case-sensitive.

  • Development mode (mutable mode)

    In development mode, by default all endpoints are open and accessible.

    You can create, edit, and deploy routes through IG Studio, and manage routes through Common REST, without authentication or authorization.

    Use development mode to evaluate or demo IG, or to develop configurations on a single instance. This mode is not suitable for production.

    For information about how to switch to development mode, see Switching from Production Mode to Development Mode.

    For information about restricting access to Studio in development mode, see Restricting Access to Studio.

  • Production mode (immutable mode)

    In production mode, the /routes endpoint is not exposed or accessible.

    Studio is effectively disabled, and you cannot manage, list, or even read routes through Common REST.

    By default, other endpoints, such as /share and api/info are exposed to the loopback address only. To change the default protection for specific endpoints, configure an ApiProtectionFilter in admin.json and add it to the IG configuration.

    For information about how to switch to production mode, see Switching From Development Mode to Production Mode.

    If mode is not set, the provided configuration token ig.run.mode can be resolved at startup to define the run mode.

    Default: production

"heap": array of configuration objects, optional

The heap object configuration, described in Heap Objects. You can omit an empty array.

"prefix": configuration expression<string>, optional

The base of the route for administration requests. This route and its subroutes are reserved for administration endpoints.

Default: openig

"properties": JSON object, optional

Configuration parameters declared as property variables for use in the configuration. See also Route 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.

"temporaryDirectory": configuration expression<string>, optional

Directory containing temporary storage files.

Set this property to store temporary files in a different directory, for example:

{
   "temporaryDirectory": "/path/to/my-temporary-directory"
}

Default: $HOME/.openig/tmp (on Windows,appdata\OpenIG\OpenIG\tmp)

"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.

"preserveOriginalQueryString": configuration expression<boolean>, optional

Process query strings in URLs, by applying or not applying a decode/encode process to the whole query string.

The following characters are disallowed in query string URL components: ", {, }, <, >, (space), and |. For more information about which query strings characters require encoding, see Uniform Resource Identifier (URI): Generic Syntax.

  • true: Preserve query strings as they are presented.

    Select this option if the query string must not change during processing, for example, in signature verification.

    If a query string contains a disallowed character, the request produces a 400 Bad Request.

  • false: Tolerate disallowed characters in query string URL components, by applying a decode/encode process to the whole query string.

    Select this option when a user agent or client produces query searches with disallowed characters. IG transparently encodes the disallowed characters before forwarding requests to the protected application.

    Characters in query strings are transformed as follows:

    • Allowed characters are not changed. For example, sep=a is not changed.

    • Percent-encoded values are re-encoded when the decoded value is an allowed character. For example, sep=%27 is changed to sep=', because ' is an allowed character.

    • Percent-encoded values are not changed when the decoded value is a disallowed character. For example, sep=%22 is not changed, because " is a disallowed character.

    • Disallowed characters are encoded. For example, sep=", is changed to sep=%22, because " is a disallowed character.

      Default: false

"session": configuration object, optional
Supported only for IG in standalone mode.

Configures stateful sessions for IG in standalone mode. For information about IG sessions, see Sessions.

{
  "session": {
    "cookie": {
      "name": configuration expression<string>,
      "httpOnly": configuration expression<boolean>,
      "secure": configuration expression<boolean>,
      "path": configuration expression<string>
    },
    "timeout": configuration expression<duration>
  }
}
"cookie": object, optional

The configuration of the cookie used to store the stateful session.

Default: The cookie is treated as a host-based cookie.

"name": configuration expression<string>, optional

The session cookie name.

Default: IG_SESSIONID

"httpOnly": configuration expression<boolean>, optional

Flag to mitigate the risk of client-side scripts accessing protected cookies.

Default: true

"secure": configuration expression<boolean>, optional

Flag to limit the scope of the cookie to secure channels.

Set this flag only if the user-agent is able to re-emit cookies over HTTPS on its next hop. For example, to re-emit a cookie with the secure flag, the user-agent must be connected to its next hop by HTTPS.

Default: false

"path": configuration expression<string>, optional

The path protected by the session.

Set a path only if the user-agent is able to re-emit cookies on the path. For example, to re-emit a cookie on the path /home/cdsso, the user-agent must be able to access that path on its next hop.

Default: /.

"timeout": configuration expression<duration>, optional

The duration for which the session cookie is valid.

The value must be above zero, and no greater than 3650 days (approximately 10 years). IG truncates the duration of longer values to 3650 days.

Default: 30 minutes

"streamingEnabled": configuration expression<boolean>, optional
Supported only for IG in standalone mode.

When true, the content of HTTP requests and responses is streamed; it is available for processing bit-by-bit, as soon as it is received.

When false, the content is buffered; it is available for processing after it has all been received.

When this property is true, consider the following requirements to prevent IG from blocking an executing thread to wait for streamed content:

  • Runtime expressions that consume streamed content must be written with # instead of $.

    For more information, see runtime expression.

  • In scripts and Java extensions, never use a Promise blocking method, such as get(), getOrThrow(), or getOrThrowUninterruptibly(), to obtain the response.

    For more information, see Scripts.

Default: false

Example Configuration Files

Default Configuration

When your configuration does not include an admin.json file, the following admin.json is provided by default:

  • Standalone mode

  • Web container mode

{
  "prefix": "openig",
  "connectors": [
    { "port" : 8080 }
  ]
}
{
  "prefix" : "openig"
}
Overriding the Default ApiProtectionFilter

The following example shows an admin.json file configured to override the default ApiProtectionFilter that protects the reserved administrative route. This example is used in Set Up the UMA Example.

  • Standalone mode

  • Web container mode

{
  "prefix": "openig",
  "connectors": [
    { "port" : 8080 }
  ],
  "heap": [
    {
      "name": "ClientHandler",
      "type": "ClientHandler"
    },
    {
      "name": "ApiProtectionFilter",
      "type": "CorsFilter",
      "config": {
        "policies": [
          {
            "acceptedOrigins": [ "http://app.example.com:8081" ],
            "acceptedMethods": [ "GET", "POST", "DELETE" ],
            "acceptedHeaders": [ "Content-Type" ]
          }
        ]
      }
    }
  ]
}
{
  "prefix": "openig",
  "heap": [
    {
      "name": "ClientHandler",
      "type": "ClientHandler"
    },
    {
      "name": "ApiProtectionFilter",
      "type": "CorsFilter",
      "config": {
        "policies": [
          {
            "acceptedOrigins": [ "http://app.example.com:8081" ],
            "acceptedMethods": [ "GET", "POST", "DELETE" ],
            "acceptedHeaders": [ "Content-Type" ]
          }
        ]
      }
    }
  ]
}

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.

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

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

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

BaseUriDecorator

A decorator to override 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 Secrets.

TemporaryStorage

Manages temporary buffers. 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 Route 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.

Heap Objects

A heaplet creates and initializes an object that is stored in a heap. A heaplet can retrieve objects it depends on from the heap.

A heap is a collection of associated objects created and initialized by heaplet objects. All configurable objects in IG are heap objects.

The heap configuration is included as an object in admin.json and config.json.

Usage

[
    {
        "name": string,
        "type": string,
        "config": {
            object-specific configuration
        }
    },
    ...
]

Properties

"name": string, required except for inline objects

The unique name to give the heap object in the heap. This name is used to resolve the heap object, for example, when another heap object names a heap object dependency.

"type": string, required

The class name of the object to be created. To determine the type name, see the object’s documentation in this reference.

"config": object, required

The configuration that is specific to the heap object being created.

If all the fields are optional and the configuration uses only default settings, you can omit the config field instead of including an empty config object as the field value.

Configuration Settings

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

Expressions can retrieve the values for configuration settings from system properties or environment variables. When IG starts up or when a route is reloaded, the expressions are evaluated. If you change the value of a system property or environment variable and then restart IG or reload the route, the configuration settings are updated with the new values.

If a configuration setting is required and the expression returns null, an error occurs when IG starts up or when the route is reloaded. If the configuration setting is optional, there is no error.

In the following example, "timer" is defined by an expression that recovers the environment variable "ENABLE_TIMER" and transforms it into a boolean. Similarly, "numberOfRequests" is defined by an expression that recovers the system property "requestsPerSecond" and transforms it into an integer:

{
  "name": "throttle-simple-expressions1",
  "timer": "${bool(env['ENABLE_TIMER'])}",
  "baseURI": "http://app.example.com:8081",
  "condition": "${matches(request.uri.path, '^/home/throttle-simple-expressions1')}",
  "handler": {
    "type": "Chain",
    "config": {
      "filters": [
        {
          "type": "ThrottlingFilter",
          "name": "ThrottlingFilter-1",
          "config": {
            "requestGroupingPolicy": "",
            "rate": {
              "numberOfRequests": "${integer(system['requestsPerSecond'])}",
              "duration": "10 s"
            }
          }
        }
      ],
      "handler": "ReverseProxyHandler"
    }
  }
}

If "requestsPerSecond"=6 and "ENABLE_TIMER"=true, after the expressions are evaluated IG views the example route as follows:

{
  "name": "throttle-simple-expressions2",
  "timer": true,
  "baseURI": "http://app.example.com:8081",
  "condition": "${matches(request.uri.path, '^/home/throttle-simple-expressions2')}",
  "handler": {
    "type": "Chain",
    "config": {
      "filters": [
        {
          "type": "ThrottlingFilter",
          "name": "ThrottlingFilter-1",
          "config": {
            "requestGroupingPolicy": "",
            "rate": {
              "numberOfRequests": 6,
              "duration": "10 s"
            }
          }
        }
      ],
      "handler": "ReverseProxyHandler"
    }
  }
}

For information about expressions, see Expressions.

Supported System Properties

The following properties are supported in IG. Their names have a special meaning in IG, and they should be used only for their stated purpose:

ig.instance.dir, IG_INSTANCE_DIR

The full path to the directory containing configuration and data for the IG instance.

Default: Linux, $HOME/.openig; Windows, appdata\OpenIG

org.forgerock.json.jose.jwe.compression.max.decompressed.size.bytes

The maximum size in bytes to which a compressed JWT can be decompressed.

Default: 32 KBytes

org.forgerock.secrets.preferDeterministicEcdsa

When this property is true, and the following conditions are met, JWTs are signed with a deterministic Elliptic Curve Digital Signature Algorithm (ECDSA):

  • ECDSA is used for signing

  • Bouncy Castle is installed

Default: true

org.forgerock.http.TrustTransactionHeader

When this property is true, all incoming X-ForgeRock-TransactionId headers are trusted. Monitoring or reporting systems that consume the logs can allow requests to be correlated as they traverse multiple servers.

Default: false

org.forgerock.http.util.ignoreFormParamDecodingError

When this property is true, form encoding errors caused by invalid characters are ignored, and encoded values are used instead.

Default: false