--- title: Required configuration description: 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. component: pinggateway version: 2023.11 page_id: pinggateway:reference:RequiredConfiguration canonical_url: https://docs.pingidentity.com/pinggateway/2026/reference/RequiredConfiguration.html llms_txt: https://docs.pingidentity.com/pinggateway/llms.txt docs_for_agents: https://developer.pingidentity.com/build-with-ai/docs-for-agents.md revdate: 2023-09-19T08:48:14Z superseded_by: https://docs.pingidentity.com/pinggateway/2026/reference/RequiredConfiguration.html section_ids: AdminHttpApplication: AdminHttpApplication (admin.json) admin-default-objects: Default objects auto-created-objects: Provided objects AdminHttpApplication-usage: Usage AdminHttpApplication-properties: Properties AdminHttpApplication-example: Example configuration files AdminHttpApplication-example-default: Default configuration AdminHttpApplication-example-overriding: Overriding the default ApiProtectionFilter AdminHttpApplication-moreinfo: More information GatewayHttpApplication: GatewayHttpApplication (config.json ) config-routes-endpoint: Routes endpoint config-default-objects: Default objects sessions: Sessions GatewayHttpApplication-usage: Usage GatewayHttpApplication-properties: Properties GatewayHttpApplication-example: Example configuration files GatewayHttpApplication-default-config: Default configuration GatewayHttpApplication-doc-config: Example config.json used in the doc GatewayHttpApplication-moreinfo: More information heap-objects: Heap objects heap-objects-usage: Usage heap-objects-properties: Properties heap-objects-moreinfo: More information configuration: Configuration settings SupportedSystemProperties: Supported system properties --- # 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 file, expected at `$HOME/.openig/config/admin.json`. Objects configured in `admin.json` cannot be used by `config.json` or any IG routes. ### Default objects IG provides default objects in `admin.json`. To override a default object, configure an object with the same name in `admin.json`. Configure default objects in `admin.json` and `config.json` separately. An object configured in `admin.json` with the same name as an object configured in `config.json` is not the same object. * `AuditService` Records no audit events. The default AuditService is `NoOpAuditService`. For more information, refer to [NoOpAuditService](AuditFramework.html#NoOpAuditService). * `CaptureDecorator` Captures requests and response messages. The default CaptureDecorator is named `capture`, and uses the default settings given in [CaptureDecorator](Decorators.html#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. For more information, refer to [ClientHandler](Handlers.html#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. * `ProxyOptions` A proxy to which a [ClientHandler](ClientHandler.html) or [ReverseProxyHandler](ReverseProxyHandler.html) can submit requests, and an [AmService](AmService.html) can submit Websocket notifications. For more information, refer to [ProxyOptions](ProxyOptions.html). * `ReverseProxyHandler` Communicates with third-party services. For more information, refer to [ReverseProxyHandler](Handlers.html#ReverseProxyHandler). * `ScheduledExecutorService` Specifies the number of threads in a pool. * `SecretsService` (deprecated) Manages a store of secrets from files, system properties, and environment variables, by using Commons Secrets API. The default SecretsService is a SystemAndEnvSecretStore with the default configuration. For more information, refer to [Secrets](secrets.html). * `TemporaryStorage` Manages temporary buffers. For more information, refer to [TemporaryStorage](MiscellaneousConfigurationObjects.html#TemporaryStorage). * `TimerDecorator` Records time spent within filters and handlers. The default TimerDecorator is named `timer`. For more information, refer to [TimerDecorator](Decorators.html#TimerDecorator). * `TransactionIdOutboundFilter` Inserts the ID of a transaction into the header of a request. ### Provided objects 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 an example that uses an ApiProtectionFilter, refer to [Set up the UMA example](../gateway-guide/uma.html#uma-configuration). For information about reserved routes, refer to [Reserved routes](preface.html#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 that uses a MetricsProtectionFilter, refer to [Protect monitoring endpoints](../maintenance-guide/monitoring.html#proc-monitor-plat-protect). * `"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 an example that uses a StudioProtectionFilter, refer to [Restrict access to Studio](../studio-guide/restrict-access.html). ### Usage ```json { "heap": [ object, ... ], "connectors": [ object, ... ], "vertx": object, "gatewayUnits": configuration expression, "mode": configuration expression, "prefix": configuration expression, "properties": object, "secrets"(*): { "stores": [ SecretStore reference, ... ] }, "temporaryDirectory": configuration expression, "temporaryStorage": TemporaryStorage reference, "pidFileMode": configuration expression, "preserveOriginalQueryString": configuration expression, "session": object, "streamingEnabled": configuration expression } ``` (\*)Deprecated ### Properties * `"heap"`: *array of [objects](preface.html#definition-object), optional* The heap object configuration, described in [Heap objects](#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. * `"connectors"`: *array of [objects](preface.html#definition-object), required* Server port configuration, when IG is acting *server-side*. | | | | - | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | When an application sends requests to IG or requests services from IG, IG is server-side. IG is acting as a server of the application, and the application is acting as a client. | ```json { "connectors" : [ { "port": [ configuration expression, ... ], "tls": ServerTlsOptions reference, "vertx": object, "maxTotalHeadersSize": configuration expression }, { ... } ] } ``` * `port`: *array of configuration expression<[numbers](preface.html#definition-number)>, required* One or more ports on which IG is connected. When more than one port is defined, IG is connected to each port. * `tls`: *ServerTlsOptions [reference](preface.html#definition-reference), optional* Configure options for connections to TLS-protected endpoints, based on [ServerTlsOptions](MiscellaneousConfigurationObjects.html#ServerTlsOptions). Define the object inline or in the heap. Default: Connections to TLS-protected endpoints are not configured. * `vertx`: *[object](preface.html#definition-object), optional* Vert.x-specific configuration for this connector when IG is acting *server-side*. When IG is acting *client-side*, configure the `vertx` property of [ClientHandler](ClientHandler.html) or [ReverseProxyHandler](ReverseProxyHandler.html). Vert.x options are described in [HttpServerOptions](https://vertx.io/docs/4.5.17/apidocs/io/vertx/core/http/HttpServerOptions.html). 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`. Vert.x values are evaluated as configuration expressions. 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 Vert.x configuration options are deprecated server-side: * `maxHeaderSize` * `initialSettings:maxHeaderListSize` Use `connectors:maxTotalHeadersSize` instead of `vertx.maxHeaderSize` or `vertx.initialSettings.maxHeaderListSize`. The following example configures connectors on ports 8080 and 8443 when IG is acting server-side. When IG is acting client-side, configure the `vertx` property of ClientHandler or ReverseProxyHandler: ```json { "connectors": [{ "port": 8080, "vertx": { "maxWebSocketFrameSize": 128000, "maxWebSocketMessageSize": 256000, "compressionLevel": 4 } }, { "port": 8443, "tls": "ServerTlsOptions-1" }] } ``` * `maxTotalHeadersSize`: *[integer](preface.html#definition-integer), optional* The maximum size in bytes of the sum of all request headers. When the request headers exceed this limit, IG returns an HTTP 431 error. Default: 8 192 bytes The following example configures HTTP/2 connections on port 7070 when IG is acting server-side. The configuration allows IG to accept HTTP/2 requests with large headers. When IG is acting client-side, configure the `vertx` property of ClientHandler or ReverseProxyHandler: ```json { "connectors": [ { "port": 7070, "maxTotalHeadersSize": 16384 } ] } ``` * `vertx`: *[object](preface.html#definition-object), optional* Vert.x-specific configuration used to more finely-tune Vert.x instances. Vert.x values are evaluated as configuration expressions. Use the Vert.x options described in [VertxOptions](https://vertx.io/docs/4.5.17/apidocs/io/vertx/core/VertxOptions.html), with the following exceptions: * `metricsOptions`: Not used * `metricsEnabled`: Enable Vertx metrics. Default: `true`. For an example, refer to [Monitoring Services](../maintenance-guide/monitoring.html#monitor-vertx-prometheus). IG proxies all WebSocket subprotocols by default. To proxy specific WebSocket subprotocols only, list them as follows: ```json "vertx": { "webSocketSubProtocols": ["v1.notifications.forgerock.org", ... ] } ``` * `"gatewayUnits"`: *configuration expression<[number](preface.html#definition-number)>, optional* 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`: *configuration expression<[enumeration](preface.html#definition-enumeration)>, optional* Set the IG mode to `development` or `production`. The value is not case-sensitive. If `mode` is not set, the provided configuration token `ig.run.mode` can be resolved at startup to define the run mode. For more information, refer to [Operating modes](../configure/operating-modes.html). Default: `production` * `"prefix"`: *configuration expression<[string](preface.html#definition-string)>, optional* The base of the route for administration requests. This route and its subroutes are reserved for administration endpoints. Default: `openig` * `"properties"`: *[object](preface.html#definition-object), optional* Configuration parameters declared as property variables for use in the configuration. See also [Route properties](Properties.html). Default: Null * `"secrets"`: *SecretStore [reference](preface.html#definition-reference), optional* | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | | This property is deprecated; use [SecretsProvider](SecretsProvider.html) instead. For more information, refer to the [Deprecated](https://docs.pingidentity.com/pinggateway/release-notes/deprecated.html) section of the *Release Notes*. | One or more secret stores, as defined in [Secrets](secrets.html). * `"temporaryDirectory"`: *configuration expression<[string](preface.html#definition-string)>, optional* Directory containing temporary storage files. Set this property to store temporary files in a different directory, for example: ```json { "temporaryDirectory": "/path/to/my-temporary-directory" } ``` Default: `$HOME/.openig/tmp` (on Windows,`%appdata%\OpenIG\tmp`) * `"temporaryStorage"`: *TemporaryStorage [reference](preface.html#definition-reference), optional* The [TemporaryStorage](TemporaryStorage.html) object to buffer content during processing. Provide the name of a [TemporaryStorage](TemporaryStorage.html) 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 IG storage defined in `temporaryStorage`, before it enters the chain. * If the content length of the request is more than the buffer limit, IG returns an `HTTP 413 Payload Too Large`. 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. * `"pidFileMode"`: *configuration expression<[enumeration](preface.html#definition-enumeration)>, optional* Mode to allow or disallow startup if there is an existing PID file. Use one of the following values: * `fail`: Startup fails if there is an existing PID file. * `override`: Startup is allowed if there is an existing PID file. IG removes the existing PID file and creates a new one during startup. Default: `fail` - `"preserveOriginalQueryString"`: *configuration expression<[boolean](preface.html#definition-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, refer to [Uniform Resource Identifier (URI): Generic Syntax](https://www.rfc-editor.org/rfc/rfc3986). * `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"`: *[object](preface.html#definition-object), optional* Configures stateful sessions for IG. For information about IG sessions, refer to [Sessions](../about/about-sessions.html). ```json { "session": { "cookie": { "name": configuration expression, "httpOnly": configuration expression, "path": configuration expression, "sameSite": configuration expression, "secure": configuration expression, }, "timeout": configuration expression } } ``` * `"cookie"`: *[object](preface.html#definition-object), optional* The configuration of the cookie used to store the stateful session. Default: The session cookie is treated as a host-based cookie. * `"name"`: *configuration expression<[string](preface.html#definition-string)>, optional* The session cookie name. Default: `IG_SESSIONID` * `"httpOnly"`: *configuration expression<[boolean](preface.html#definition-boolean)>, optional* Flag to mitigate the risk of client-side scripts accessing protected session cookies. Default: `true` * `"path"`: *configuration expression<[string](preface.html#definition-string)>, optional* The path protected by the session. Set a path only if the user agent is able to re-emit session cookies on the path. For example, to re-emit a session cookie on the path `/home/cdsso`, the user agent must be able to access that path on its next hop. Default: `/`. * `"sameSite"`: *configuration expression<[enumeration](preface.html#definition-enumeration)>, optional* Options to manage the circumstance in which the session cookie is sent to the server. The following values are listed in order of strictness, with most strict first: * `STRICT`: Send the session cookie only if the request was initiated from the session cookie domain. Not case-sensitive. Use this value to reduce the risk of cross-site request forgery (CSRF) attacks. * `LAX`: Send the session cookie only with GET requests in a first-party context, where the URL in the address bar matches the session cookie domain. Not case-sensitive. Use this value to reduce the risk of cross-site request forgery (CSRF) attacks. * `NONE`: Send the session cookie whenever a request is made to the session cookie domain. With this setting, consider setting `secure` to `true` to prevent browsers from rejecting the session cookie. For more information, refer to [SameSite cookies](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie/SameSite) Default: `LAX` | | | | - | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | For CDSSO, set `"sameSite":"none"` and `"secure":"true"`. For security reasons, many browsers require the connection used by the browser to be secure (HTTPS) for `"sameSite":"none"`. Therefore, if the connection used by the browser is not secure (HTTP), the browser might not supply cookies with `"sameSite":"none"`. For more information, refer to [Authenticate with CDSSO](../gateway-guide/sso-cdsso.html#cdsso-auth). | * `"secure"`: *configuration expression<[boolean](preface.html#definition-boolean)>, optional* Flag to limit the scope of the session cookie to secure channels. Set this flag only if the user agent is able to re-emit session cookies over HTTPS on its next hop. For example, to re-emit a session cookie with the `secure` flag, the user agent must be connected to its next hop by HTTPS. Default: `false` | | | | - | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | For CDSSO, set `"sameSite":"none"` and `"secure":"true"`. For security reasons, many browsers require the connection used by the browser to be secure (HTTPS) for `"sameSite":"none"`. Therefore, if the connection used by the browser is not secure (HTTP), the browser might not supply cookies with `"sameSite":"none"`. For more information, refer to [Authenticate with CDSSO](../gateway-guide/sso-cdsso.html#cdsso-auth). | * `"timeout"`: *configuration expression<[duration](preface.html#definition-duration)>, optional* The duration after which idle sessions are automatically timed out. 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](preface.html#definition-boolean)>, optional* A flag to manage content: * `true`: IG streams the content of HTTP requests and responses. The content is available for processing bit-by-bit, as soon as it is received. * `false`: IG buffers the content of HTTP requests and responses into the storage defined in `temporaryStorage`. The content is available for processing only 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: * Write runtime expressions that consume streamed content with `#` instead of `$`. For more information, refer to [runtime expression](Expressions.html#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, refer to [Scripts](Scripts.html). | | | | - | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | When `streamingEnabled=true` and a [CaptureDecorator](CaptureDecorator.html) with `captureEntity=true` decorates a component, the decorator interrupts streaming for the captured request or response until the whole entity is captured. | 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: ```json { "prefix": "openig", "connectors": [ { "port" : 8080 } ] } ``` #### 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](../gateway-guide/uma.html#uma-configuration). ```json { "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" ] } ] } } ] } ``` ### More information [org.forgerock.openig.http.AdminHttpApplication](../_attachments/apidocs/org/forgerock/openig/http/AdminHttpApplication.html) ## 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](#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 IG route. They cannot be used by `admin.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, 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 IG 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](Decorators.html#BaseUriDecorator). - `AuditService` Records no audit events. The default AuditService is `NoOpAuditService`. For more information, refer to [NoOpAuditService](AuditFramework.html#NoOpAuditService). - `CaptureDecorator` Captures requests and response messages. The default CaptureDecorator is named `capture`, and uses the default settings given in [CaptureDecorator](Decorators.html#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. For more information, refer to [ClientHandler](Handlers.html#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. - `ProxyOptions` A proxy to which a [ClientHandler](ClientHandler.html) or [ReverseProxyHandler](ReverseProxyHandler.html) can submit requests, and an [AmService](AmService.html) can submit Websocket notifications. For more information, refer to [ProxyOptions](ProxyOptions.html). - `ReverseProxyHandler` Communicates with third-party services. For more information, refer to [ReverseProxyHandler](Handlers.html#ReverseProxyHandler). - `ScheduledExecutorService` Specifies the number of threads in a pool. - `SecretsService` (deprecated) Manages a store of secrets from files, system properties, and environment variables, by using Commons Secrets API. The default SecretsService is a SystemAndEnvSecretStore with the default configuration. For more information, refer to [Secrets](secrets.html). - `TemporaryStorage` Manages temporary buffers. For more information, refer to [TemporaryStorage](MiscellaneousConfigurationObjects.html#TemporaryStorage). - `TimerDecorator` Records time spent within filters and handlers. The default TimerDecorator is named `timer`. For more information, refer to [TimerDecorator](Decorators.html#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, refer to [Sessions](../about/about-sessions.html) and [JwtSession](MiscellaneousConfigurationObjects.html#JwtSession). ### Usage ```json { "handler": Handler reference, "heap": [ object, ... ], "properties": object, "secrets"(*): { "stores": [ SecretStore reference, ... ] }, "temporaryStorage": TemporaryStorage reference } ``` (\*)Deprecated ### Properties * `"handler"`: *Handler [reference](preface.html#definition-reference), required* The [Handler](Handlers.html) to which IG dispaches requests. Provide the name of a Handler object defined in the heap or an inline Handler configuration object. - `"heap"`: *array of [objects](preface.html#definition-object), optional* The heap object configuration, described in [Heap objects](#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"`: *[object](preface.html#definition-object), optional* Configuration parameters declared as property variables for use in the configuration. See also [Route properties](Properties.html). Default: Null - `"secrets"`: *SecretStore [reference](preface.html#definition-reference), optional* | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | | This property is deprecated; use [SecretsProvider](SecretsProvider.html) instead. For more information, refer to the [Deprecated](https://docs.pingidentity.com/pinggateway/release-notes/deprecated.html) section of the *Release Notes*. | One or more secret stores, as defined in [Secrets](secrets.html). - `"temporaryStorage"`: *TemporaryStorage [reference](preface.html#definition-reference), optional* The [TemporaryStorage](TemporaryStorage.html) object to buffer content during processing. Provide the name of a [TemporaryStorage](TemporaryStorage.html) 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 IG storage defined in `temporaryStorage`, before it enters the chain. * If the content length of the request is more than the buffer limit, IG returns an `HTTP 413 Payload Too Large`. 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. ### Example configuration files #### Default configuration When your configuration does not include a `config.json` file, the following configuration is provided by default. ```json { "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: ```json { "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, refer to [JwtSession](MiscellaneousConfigurationObjects.html#JwtSession). ### More information [org.forgerock.openig.http.GatewayHttpApplication](../_attachments/apidocs/org/forgerock/openig/http/GatewayHttpApplication.html) ## 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 ```json [ { "name": string, "type": string, "config": { object-specific configuration } }, ... ] ``` ### Properties * `"name"`: *[string](preface.html#definition-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](preface.html#definition-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](preface.html#definition-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. ### More information [org.forgerock.openig.heap.Heap](../_attachments/apidocs/org/forgerock/openig/heap/Heap.html) ## 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. For information about expressions, refer to [Expressions](Expressions.html#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 For information about how to use a different location, refer to [Configuration location](../configure/configure.html#configuration-location). * `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` * `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