admin.json)
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: 2026
page_id: pinggateway:reference:AdminHttpApplication
canonical_url: https://docs.pingidentity.com/pinggateway/2026/reference/AdminHttpApplication.html
revdate: 2026-02-23T12:00:00Z
section_ids:
admin-default-objects: Default objects
auto-created-objects: Provided objects (deprecated)
AdminHttpApplication-usage: Usage
AdminHttpApplication-properties-list: Properties
AdminHttpApplication-heap: heap
AdminHttpApplication-adminConnector: adminConnector
AdminHttpApplication-auditService: auditService
AdminHttpApplication-connectors: connectors
AdminHttpApplication-vertx: vertx
AdminHttpApplication-gatewayUnits: gatewayUnits
AdminHttpApplication-adminMaxBodyLength: adminMaxBodyLength
AdminHttpApplication-maxBodyLength: maxBodyLength
AdminHttpApplication-mode: mode
AdminHttpApplication-prefix: prefix (deprecated)
AdminHttpApplication-properties: properties
AdminHttpApplication-temporaryDirectory: temporaryDirectory
AdminHttpApplication-temporaryStorage: temporaryStorage
AdminHttpApplication-pidFileMode: pidFileMode
AdminHttpApplication-preserveOriginalQueryString: preserveOriginalQueryString
AdminHttpApplication-session: session
AdminHttpApplication-streamingEnabled: streamingEnabled
AdminHttpApplication-serveDeprecatedPrometheusEndpoint: serveDeprecatedPrometheusEndpoint
AdminHttpApplication-openTelemetry: openTelemetry
AdminHttpApplication-apiProtectionFilter: apiProtectionFilter
AdminHttpApplication-metricsProtectionFilter: metricsProtectionFilter
AdminHttpApplication-studioProtectionFilter: studioProtectionFilter
AdminHttpApplication-example: Default configuration
AdminHttpApplication-moreinfo: More information
---
# 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 PingGateway routes.
## Default objects
PingGateway 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` isn't the same object.
* `AuditService`
Records no audit events. The default AuditService is `NoOpAuditService`. Learn more from [NoOpAuditService](NoOpAuditService.html).
* `CaptureDecorator`
Captures requests and response messages. The default CaptureDecorator is named `capture`, and uses the default settings given in [CaptureDecorator](CaptureDecorator.html).
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 aren't 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](ClientHandler.html).
* `ForgeRockClientHandler`
Sends transaction IDs when communicating with protected applications. The default [ForgeRockClientHandler](ForgeRockClientHandler.html) is a [Chain](Chain.html), composed of a [TransactionIdOutboundFilter](TransactionIdOutboundFilter.html) and a [ClientHandler](ClientHandler.html).
* `IssuerRepository` (deprecated)
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.
| | |
| - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| | The [IssuerRepository (deprecated)](IssuerRepository.html) is deprecated. For issuers known in advance, add their settings to the [ClientRegistration](ClientRegistration.html). For discovery, configure an [AuthorizationCodeOAuth2ClientFilter](AuthorizationCodeOAuth2ClientFilter.html) `"discoveryHandler"`. |
* `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](ReverseProxyHandler.html).
* `ScheduledExecutorService`
Specifies the number of threads in a pool.
* `TemporaryStorage`
Manages temporary buffers. For more information, refer to [TemporaryStorage](TemporaryStorage.html).
* `TimerDecorator`
Records time spent within filters and handlers. The default TimerDecorator is named `timer`. For more information, refer to [TimerDecorator](TimerDecorator.html).
* `TracingDecorator`
Pushes traces to an [OpenTelemetry](https://opentelemetry.io/) service.
| | |
| - | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| | This feature has [Evolving](https://docs.pingidentity.com/pinggateway/release-notes/stability.html#interface-stability) interface stability. It is subject to change without notice, even in a minor or maintenance release. |
Use this to decorate the following:
* [PingGateway access token resolvers](AccessTokenResolvers.html)
* [AmService](AmService.html)
* [AuditService](AuditService.html)
* [PingGateway filters](Filters.html)
* [PingGateway handlers](Handlers.html)
The default [TracingDecorator](TracingDecorator.html) is named `tracing`. PingGateway traces include Vert.x traces where applicable.
* `TransactionIdOutboundFilter`
Inserts the ID of a transaction into the header of a request.
## Provided objects (deprecated)
PingGateway creates the following objects when a filter with the name of the object is declared in `admin.json`.
| | |
| - | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| | Overriding these objects by declaring objects with the same names in the heap is deprecated; define them [in the configuration](#AdminHttpApplication-usage) instead. |
* `"ApiProtectionFilter"`
A filter to protect administrative APIs on reserved routes. By default, only the loopback address can access reserved routes.
* `"MetricsProtectionFilter"`
A filter to protect the monitoring endpoints. By default, the Prometheus Scrape Endpoint and Common REST Monitoring Endpoint (deprecated) are open and accessible; no special credentials or privileges are required to access the monitoring endpoints.
* `"StudioProtectionFilter"`
A filter to protect the Studio endpoint when PingGateway is running in development mode. When PingGateway is running in development mode, by default, the Studio endpoint is open and accessible.
## Usage
| | |
| - | -------------------------------------------------------------------------------- |
| | Restart PingGateway after making configuration changes to load the new settings. |
```none
{
"heap": [ object, … ],
"adminConnector": {
"port": configuration expressionAdministrative access denied
" } } } } } ``` Default: `0.0.0.0` (listen on all network interfaces) * `gracePeriod`: *configuration expression<[duration](preface.html#definition-duration)>, optional* When shutting down, PingGateway refuses new requests and waits for this period before forcing administrative connections to close. By default, the `stop.sh` and `stop.bat` scripts let the PingGateway process terminate gracefully. If you set a time limit for [forcible shutdown](../installation-guide/start-stop.html#forcible-shutdown), make sure it's longer than the `gracePeriod` defined here. Set `"gracePeriod": "disabled"` to force connections to close immediately. Default: 1 second - `tls`: *ServerTlsOptions [reference](preface.html#definition-reference), optional* Configure [ServerTlsOptions](ServerTlsOptions.html) for connections to TLS-protected endpoints. Define the object inline or in the heap. Default: Connections to TLS-protected endpoints aren't configured. * `vertx`: *[object](preface.html#definition-object), optional* Vert.x-specific configuration for administrative connections. Learn more about Vert.x options in [HttpServerOptions](https://vertx.io/docs/5.0.10/apidocs/io/vertx/core/http/HttpServerOptions.html). For properties where PingGateway provides its own first-class configuration, the PingGateway 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: * `host` The following example sets a timeout for the DNS cache, so PingGateway can respond more quickly to DNS changes. Using [AddressResolverOptions](https://vertx.io/docs/5.0.10/apidocs/io/vertx/core/dns/AddressResolverOptions.html), it sets a maxiumum time-to-live (TTL) of 10 seconds for DNS responses: ```json { "vertx": { "addressResolverOptions": { "cacheMaxTimeToLive": 10 } } } ``` When PingGateway establishes a new connection, it uses the DNS cache to resolve the hostname. After the maximum TTL, PingGateway performs a new DNS lookup to get the most up-to-date IP address for the hostname. - `maxTotalHeadersSize`: *[integer](preface.html#definition-integer), optional* The maximum size in bytes for the sum of all request headers. When the request headers exceed this limit, PingGateway returns an HTTP 431 error. Default: 8 192 bytes ### auditService `"auditService"`: *AuditService [reference](preface.html#definition-reference), optional* The [AuditService](AuditService.html) defined in `admin.json` to record audit events for administrative endpoints. This audit service differs from any audit service defined in `config.json` or in any route. This audit service doesn't share settings with other audit services. Its settings don't impact or replace those in other audit services. When this audit service writes log files, make sure the `"logDirectory"` setting differs from other audit services to ensure unique log file paths. This audit service must enable the `access` topic as shown in the [AuditService example](AuditService.html#AuditService-example). Default: the `AuditService` defined in the heap ### connectors `"connectors"`: *array of [objects](preface.html#definition-object), required* Server port configuration, when PingGateway is acting *server-side*. | | | | - | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | When an application sends requests to or requests services from PingGateway, PingGateway is server-side. PingGateway serves the application acting as a client. | * `port`: *array of configuration expression<[numbers](preface.html#definition-number)>, required* One or more ports where PingGateway listens for client application connections. When more than one port is defined, PingGateway listens on each port. Don't reuse these ports when setting the [port for the `"adminConnector"`](#AdminHttpApplication-adminConnector-port). - `host`: *configuration expression<[string](preface.html#definition-string)>, optional* The hostname where PingGateway listens for administrative connections. Default: `0.0.0.0` (listen on all network interfaces) * `gracePeriod`: *configuration expression<[duration](preface.html#definition-duration)>, optional* When shutting down, PingGateway refuses new requests and waits for this period before forcing connections to close. By default, the `stop.sh` and `stop.bat` scripts let the PingGateway process terminate gracefully. If you set a time limit for [forcible shutdown](../installation-guide/start-stop.html#forcible-shutdown), make sure it's longer than the `gracePeriod` defined here. Set `"gracePeriod": "disabled"` to force connections to close immediately. Default: 1 second - `tls`: *ServerTlsOptions [reference](preface.html#definition-reference), optional* Configure options for connections to TLS-protected endpoints based on [ServerTlsOptions](ServerTlsOptions.html). Define the object inline or in the heap. Default: Connections to TLS-protected endpoints aren't configured. * `vertx`: *[object](preface.html#definition-object), optional* Vert.x-specific configuration for this connector when PingGateway is acting *server-side*. When PingGateway is acting *client-side*, configure the `vertx` property of a [ClientHandler](ClientHandler.html) or [ReverseProxyHandler](ReverseProxyHandler.html). Learn more about Vert.x options in [HttpServerOptions](https://vertx.io/docs/5.0.10/apidocs/io/vertx/core/http/HttpServerOptions.html). For properties where PingGateway provides its own first-class configuration, Vert.x configuration options are disallowed, and the PingGateway 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: * `host` The following example configures connectors on ports 8080 and 8443 when PingGateway is acting server-side: ```json { "connectors": [{ "port": 8080, "vertx": { "maxWebSocketFrameSize": 128000, "maxWebSocketMessageSize": 256000, "compressionLevel": 4 } }, { "port": 8443, "tls": "ServerTlsOptions-1" }] } ``` The following example sets a timeout for the DNS cache, so PingGateway can respond more quickly to DNS changes. Using [AddressResolverOptions](https://vertx.io/docs/5.0.10/apidocs/io/vertx/core/dns/AddressResolverOptions.html), it sets a maxiumum time-to-live (TTL) of 10 seconds for DNS responses: ```json { "vertx": { "addressResolverOptions": { "cacheMaxTimeToLive": 10 } } } ``` When PingGateway establishes a new connection, it uses the DNS cache to resolve the hostname. After the maximum TTL, PingGateway performs a new DNS lookup to get the most up-to-date IP address for the hostname. - `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, PingGateway returns an HTTP 431 error. The following example configures HTTP/2 connections on port 7070 whenPingGateway is acting server-side. The configuration allows PingGateway to accept HTTP/2 requests with large headers: ```json { "connectors": [ { "port": 7070, "maxTotalHeadersSize": 16384 } ] } ``` Default: 8 192 bytes ### vertx `vertx`: *[object](preface.html#definition-object), optional* This is the 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/5.0.10/apidocs/io/vertx/core/VertxOptions.html) with the following exceptions: * `metricsOptions`: Not used * `metricsEnabled`: Enable Vertx metrics. Default: `true`. Learn more in [Monitor Vert.x metrics](../maintenance-guide/monitoring.html#monitor-vertx). PingGateway proxies all WebSocket subprotocols by default. To proxy specific WebSocket subprotocols only, list them as follows: ```none "vertx": { "webSocketSubProtocols": ["v1.notifications.forgerock.org", ... ] } ``` ### gatewayUnits `"gatewayUnits"`: *configuration expression<[number](preface.html#definition-number)>, optional* The number of parallel instances of PingGateway to bind to an event loop. All instances listen on the same ports. Default: The number of cores available to the JVM. ### adminMaxBodyLength `"adminMaxBodyLength"`: *configuration expression<[number](preface.html#definition-number)>, optional* Maximum body size in bytes for HTTP requests to the administration port. This takes effect only when ["streamingEnabled"](#AdminHttpApplication-streamingEnabled) is `false`. Default: `-1` (unlimited) ### maxBodyLength `"maxBodyLength"`: *configuration expression<[number](preface.html#definition-number)>, optional* Maximum body size in bytes for HTTP requests from client applications. This takes effect only when ["streamingEnabled"](#AdminHttpApplication-streamingEnabled) is `false`. Default: `-1` (unlimited) ### mode `mode`: *configuration expression<[enumeration](preface.html#definition-enumeration)>, optional* Set the PingGateway mode to `development` or `production`. The value is not case-sensitive. If `mode` is not set, PingGateway resolves the provided configuration token `ig.run.mode` at startup to define the run mode. Learn more in [PingGateway operating modes](../configure/operating-modes.html). Default: `production` ### prefix (deprecated) `"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. | | | | - | ------------------------------------------------------------------ | | | This property is deprecated. Define an `"adminConnector"` instead. | Default: `openig` ### properties `"properties"`: *[object](preface.html#definition-object), optional* Configuration parameters declared as property variables for use in the configuration. Learn more in [PingGateway route properties](Properties.html). Default: No properties are defined. ### temporaryDirectory `"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"`: *TemporaryStorage [reference](preface.html#definition-reference), optional* The [TemporaryStorage](TemporaryStorage.html) 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: * Only used 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` with default settings for a TemporaryStorage object. ### pidFileMode `"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. PingGateway removes the existing PID file and creates a new one during startup. Default: `fail` ### preserveOriginalQueryString `"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 `|`. Learn more about which query string characters require encoding in [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 returns HTTP 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. PingGateway transparently encodes the disallowed characters before forwarding requests to the protected application. Characters in query strings are transformed as follows: * Allowed characters aren't 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 aren't 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 `"session"`: *AsyncSessionManager [reference](preface.html#definition-reference), optional* An [InMemorySessionManager](InMemorySessionManager.html) or [JwtSessionManager](JwtSessionManager.html). Learn more in [PingGateway sessions](../about/about-sessions.html). Default: [InMemorySessionManager](InMemorySessionManager.html) with `IG_ADMIN_SESSIONID` as the session cookie name ### streamingEnabled `"streamingEnabled"`: *configuration expression<[boolean](preface.html#definition-boolean)>, optional* A flag to manage content: * `true`: PingGateway streams the content of HTTP requests and responses. The content is available for processing bit-by-bit, as soon as it is received. * `false`: PingGateway 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 PingGateway from blocking an executing thread to wait for streamed content: * Write runtime expressions that consume streamed content with `#` instead of `$`. Learn more in the section on [runtime expressions](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. Learn more in [PingGateway scripts](Scripts.html). | | | | - | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | When `"streamingEnabled": true`:* A [CaptureDecorator](CaptureDecorator.html) with `"captureEntity": true` decorating a component interrupts streaming for the captured request or response until the whole entity is captured. * For a client sharing connections to PingGateway, for example, because the client uses HTTP pipelining, any error consuming a chunked response causes PingGateway to reset (close) the client connection. This affects all requests associated with the connection. * When PingGateway acts as a reverse proxy for client applications receiving few or infrequent [server-side events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events), set a high `soTimeout` value in the [ReverseProxyHandler](ReverseProxyHandler.html) configuration and implement mechanisms to keep the connection alive or reestablish it as needed. | Default: `false` ### serveDeprecatedPrometheusEndpoint "serveDeprecatedPrometheusEndpoint": *configuration expression<[boolean](preface.html#definition-boolean)>, optional* A flag to enable or disable the deprecated Prometheus metrics endpoint at `/metrics/prometheus`: * `false`: Disable the deprecated Prometheus Scrape Endpoint * `true`: Enable the deprecated Prometheus Scrape Endpoint Default: `false` ### openTelemetry `"openTelemetry"`: *[object](preface.html#definition-object), optional* Configure how to push traces to an [OpenTelemetry](https://opentelemetry.io/) service. When you use it with other applications with OpenTelemetry support, the service helps you analyze the flows through PingGateway and the other applications to understand performance and system behavior. | | | | - | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | This feature has [Evolving](https://docs.pingidentity.com/pinggateway/release-notes/stability.html#interface-stability) interface stability. It is subject to change without notice, even in a minor or maintenance release. | * `"tracing"`: *[object](preface.html#definition-object), required* PingGateway can push traces to an OpenTelemetry Protocol (OTLP) endpoint over HTTP where you collect and analyze system trace data. By default, this optional feature is disabled. To push traces to an OpenTelemetry service, you must at least enable it and set the decoration `"tracing": true` on routes or objects of interest to enable additional traces. The trace data and span content have [Evolving](https://docs.pingidentity.com/pinggateway/release-notes/stability.html#interface-stability) interface stability. It is subject to change without notice, even in a minor or maintenance release. The following configuration enables PingGateway to push traces to the default endpoint, `http://localhost:4318/v1/traces`: ```json { "openTelemetry": { "tracing": { "enabled": true } } } ``` * `"enabled"`: *configuration expression<[boolean](preface.html#definition-boolean)>, optional* Set to `true` to enable OpenTelemetry tracing. Default: `false` - `"resourceAttributes"`: *object, optional* A map of additional resource attributes for processing traces. Learn more in the OpenTelemetry documentation about [Semantic Attributes with SDK-provided Default Value](https://opentelemetry.io/docs/specs/semconv/resource/#semantic-attributes-with-sdk-provided-default-value). For example, if there are multiple PingGateway instances in a deployment, set the `"service.instance.id"` resource attribute differently for each one to distinguish between them: ```json { "resourceAttributes": { "service.instance.id": "gateway1" } } ``` * `"exporter"`: *object, optional* Configuration for the exporter, which pushes traces to the OpenTelemetry service. * `"type"`: *configuration expression<[string](preface.html#definition-string)>, optional* Set to `otlp` for OpenTelemetry Protocol (OTLP) support, which is the only supported protocol at this time. Default: `otlp` - `"config"`: *object, optional* Endpoint and timeout configuration: * `"endpoint"`: *configuration expression<[string](preface.html#definition-string)>, optional* The endpoint to publish traces to. For HTTPS, PingGateway trusts the default JVM CAs. To override this, set the `-Djavax.net.ssl.trustStore` and associated JVM settings when starting PingGateway. Learn more about the optional settings in the [Java Secure Socket Extension (JSSE) Reference Guide](https://docs.oracle.com/en/java/javase/25/security/java-secure-socket-extension-jsse-reference-guide.html). PingGateway doesn't support TLS configuration for the tracing endpoint at this time. Default: `http://localhost:4318/v1/traces` - `"connectionTimeout"`: *configuration expression<[duration](preface.html#definition-duration)>, optional* Time out a connection to the endpoint after this duration. Default: 10 seconds. * `"headers"`: *object, optional* Map of additional headers to include in the export span request. The following example sets the authorization header, `Authorization: Bearer ${bearer.token}`: ```none "headers": { "Authorization": "Bearer ${bearer.token}" } ``` - `"proxyOptions"`: *ProxyOptions [reference](preface.html#definition-reference), optional* A [proxy](ProxyOptions.html) to send traces to. Default: Use the system proxy settings. * `"retries"`: *object, optional* This defines a retry policy for the export span requests. Default: Enabled * `"enabled"`: *configuration expression<[boolean](preface.html#definition-boolean)>, optional* Retry failed requests. Default: `true` - `"maxAttempts"`: *configuration expression<[number](preface.html#definition-number)>, optional* Maximum number of retries. Default: 5 * `"initialBackoff"`: *configuration expression<[duration](preface.html#definition-duration)>, optional* How long to wait before the first retry. Default: 1 second - `"maxBackoff"`: *configuration expression<[duration](preface.html#definition-duration)>, optional* Maximum wait time between retries. Default: 5 seconds * `"backoffMultiplier"`: *configuration expression<[number](preface.html#definition-number)>, optional* Multiplier for the backoff wait time before retries. Default: 1.5 - `"timeout"`: *configuration expression<[duration](preface.html#definition-duration)>, optional* Time out a request to publish data to the endpoint after this duration. Default: 10 seconds. * `"tls"`: *ClientTlsOptions [reference](preface.html#definition-reference), optional* Configure [ClientTlsOptions](ClientTlsOptions.html) for connections to a TLS-protected OpenTelemetry service. Define the object inline or in the heap. Default: Rely on the JVM settings to trust server certificates. * `"batch"`: *object, optional* Enable and configure batch processing for trace data. * `"enabled"`: *configuration expression<[boolean](preface.html#definition-boolean)>, optional* Leave batch processing enabled in deployment. Default: `true` - `"compressionMethod"`: *configuration expression<[enumeration](preface.html#definition-enumeration)>, optional* Method used to compress trace data; either `gzip` or `none`. Default: `gzip` * `"scheduleDelay"`: *configuration expression<[duration](preface.html#definition-duration)>, optional* Maximum interval between sending batches of trace data. Default: 50 seconds - `"maxQueueSize"`: *configuration expression<[number](preface.html#definition-number)>, optional* Maximum number of spans to queue before dropping them. Default: 1024 * `"maxExportBatchSize"`: *configuration expression<[number](preface.html#definition-number)>, optional* Maximum number of spans in a batch. Default: 256 - `"exporterTimeout"`: *configuration expression<[duration](preface.html#definition-duration)>, optional* Time out a data exporter after this duration. Default: 30 seconds * `"exportUnsampledSpans"`: *configuration expression<[boolean](preface.html#definition-boolean)>, optional* Whether to report on unsampled spans. Default: `false` - `"sampler"`: *object, optional* Configuration for sampling spans. * `"type"`: *configuration expression<[string](preface.html#definition-string)>, optional* The sampler strategy to use is one of the following: * `"alwaysOn"`: Send every span for processing. * `"alwaysOff"`: Never send any span for processing. * `"traceIdRatio"`: Sample the specified ratio of spans, deterministically based on the trace IDs of the spans. * `"parentBasedAlwaysOn"`: Always send the span for processing if the parent span was sampled. (Default) * `"parentBasedAlwaysOff"`: Never send the span for processing if the parent span was sampled. * `"parentBasedTraceIdRatio"`: Send the specified ratio of spans for processing if the parent span was sampled. - `"ratio"`: *configuration expression<[number](preface.html#definition-number)>, optional* For ratio-based types, a percentage of spans to process. Default: 50 (percent) * `"spanLimits"`: *object, optional* Configuration for limits enforced when recording spans. * `"maxNumberOfAttributesPerEvent"`: *configuration expression<[number](preface.html#definition-number)>, optional* The maximum number of metadata items (attributes) attached to a span per event. An event is an annotation to span at a particular, meaningful point in time during the span's duration. Default: 256 - `"maxAttributeValueLength"`: *configuration expression<[number](preface.html#definition-number)>, optional* The maximum number of characters in a string attribute value. Default: 256 * `"maxNumberOfAttributes"`: *configuration expression<[number](preface.html#definition-number)>, optional* The maximum number of attributes per span. Default: 256 - `"maxNumberOfLinks"`: *configuration expression<[number](preface.html#definition-number)>, optional* The maximum number of links per span. Links associate the current span with one or more other spans. Default: 256 * `"maxNumberOfEvents"`: *configuration expression<[number](preface.html#definition-number)>, optional* The maximum number of events per span. Default: 256 - `"maxNumberOfAttributesPerLink"`: *configuration expression<[number](preface.html#definition-number)>, optional* The maximum number of attributes per link. Default: 256 - `"logging"`: *[object](preface.html#definition-object), required* PingGateway can log messages to an OpenTelemetry Protocol (OTLP) endpoint over HTTP where you collect and analyze system trace data. By default, this optional feature is disabled. To log to an OpenTelemetry service, you must at least enable logging. The following configuration enables PingGateway to log messages to `http://localhost:4318/v1/logs`: ```json { "openTelemetry": { "logging": { "enabled": true } } } ``` * `"enabled"`: *configuration expression<[boolean](preface.html#definition-boolean)>, optional* Set to `true` to enable OpenTelemetry logging. Default: `false` - `"resourceAttributes"`: *object, optional* A map of additional resource attributes for processing logs. Learn more in the OpenTelemetry documentation about [Semantic Attributes with SDK-provided Default Value](https://opentelemetry.io/docs/specs/semconv/resource/#semantic-attributes-with-sdk-provided-default-value). For example, if you have multiple PingGateway servers in a deployment, set the `"service.instance.id"` resource attribute differently for each one to distinguish between them: ```json { "resourceAttributes": { "service.instance.id": "gateway1" } } ``` * `"exporter"`: *object, optional* Configuration for the exporter, which logs to the OpenTelemetry service. * `"type"`: *configuration expression<[string](preface.html#definition-string)>, optional* Set to `otlp` for OpenTelemetry Protocol (OTLP) support, the only supported protocol at this time. Default: `otlp` - `"config"`: *object, optional* Endpoint and timeout configuration: * `"endpoint"`: *configuration expression<[string](preface.html#definition-string)>, optional* The endpoint to publish log messages to. For HTTPS, PingGateway trusts the default JVM CAs. To override this, set the `-Djavax.net.ssl.trustStore` and associated JVM settings when starting PingGateway. Learn more about the optional settings in the [Java Secure Socket Extension (JSSE) Reference Guide](https://docs.oracle.com/en/java/javase/25/security/java-secure-socket-extension-jsse-reference-guide.html). PingGateway doesn't support TLS configuration for the tracing endpoint at this time. Default: `http://localhost:4318/v1/logs` - `"compressionMethod"`: *configuration expression<[enumeration](preface.html#definition-enumeration)>, optional* Method used to compress log data; either `gzip` or `none`. Default: `gzip` * `"connectionTimeout"`: *configuration expression<[duration](preface.html#definition-duration)>, optional* Time out a connection to the endpoint after this duration. Default: 10 seconds. - `"headers"`: *object, optional* Map of additional headers to include in the export log request. The following example sets the authorization header, `Authorization: Bearer ${bearer.token}`: ```none "headers": { "Authorization": "Bearer ${bearer.token}" } ``` * `"proxyOptions"`: *ProxyOptions [reference](preface.html#definition-reference), optional* A [proxy](ProxyOptions.html) to send log messages to. Default: Use the system proxy settings. - `"retries"`: *object, optional* This defines a retry policy for the export log requests. Default: Enabled * `"enabled"`: *configuration expression<[boolean](preface.html#definition-boolean)>, optional* Retry failed requests. Default: `true` - `"maxAttempts"`: *configuration expression<[number](preface.html#definition-number)>, optional* Maximum number of retries. Default: 5 * `"initialBackoff"`: *configuration expression<[duration](preface.html#definition-duration)>, optional* How long to wait before the first retry. Default: 1 second - `"maxBackoff"`: *configuration expression<[duration](preface.html#definition-duration)>, optional* Maximum wait time between retries. Default: 5 seconds * `"backoffMultiplier"`: *configuration expression<[number](preface.html#definition-number)>, optional* Multiplier for the backoff wait time before retries. Default: 1.5 * `"timeout"`: *configuration expression<[duration](preface.html#definition-duration)>, optional* Time out a request to publish log messages to the endpoint after this duration. Default: 10 seconds. - `"tls"`: *ClientTlsOptions [reference](preface.html#definition-reference), optional* Configure [ClientTlsOptions](ClientTlsOptions.html) for connections to a TLS-protected OpenTelemetry service. Define the object inline or in the heap. Default: Rely on the JVM settings to trust server certificates. * `"batch"`: *object, optional* Enable and configure batch processing for log messages. * `"enabled"`: *configuration expression<[boolean](preface.html#definition-boolean)>, optional* Leave batch processing enabled in deployment. Default: `true` - `"scheduleDelay"`: *configuration expression<[duration](preface.html#definition-duration)>, optional* Maximum interval between sending batches of log messages. Default: 50 seconds * `"maxQueueSize"`: *configuration expression<[number](preface.html#definition-number)>, optional* Maximum number of messages to queue before dropping them. Default: 1024 - `"maxExportBatchSize"`: *configuration expression<[number](preface.html#definition-number)>, optional* Maximum number of messages in a batch. Default: 256 * `"exporterTimeout"`: *configuration expression<[duration](preface.html#definition-duration)>, optional* Time out a data exporter after this duration. Default: 30 seconds ### apiProtectionFilter `"apiProtectionFilter"`: *[object](preface.html#definition-object), optional* A filter to protect administrative APIs on reserved routes. Learn more in the section on [setting up UMA](../gateway-guide/uma.html#uma-configuration) and in [Reserved routes](preface.html#reserved-routes). Default: only the loopback address can access reserved routes ### metricsProtectionFilter `"metricsProtectionFilter"`: *[object](preface.html#definition-object), optional* A filter to protect the monitoring endpoints. Default: the Prometheus Scrape Endpoint and Common REST Monitoring Endpoint (deprecated) are open and accessible; no special credentials or privileges are required to access the monitoring endpoints. Find an example in [Protect monitoring endpoints](../maintenance-guide/monitoring.html#proc-monitor-plat-protect). ### studioProtectionFilter `"studioProtectionFilter"`: *[object](preface.html#definition-object), optional* A filter to protect the Studio endpoint when PingGateway is running in development mode. Learn more in [Restrict access to Studio](../studio-guide/restrict-access.html). Default: the Studio endpoint is open and accessible when running PingGateway in development mode ## Default configuration When your configuration doesn't include an `admin.json` file, PingGateway provides the following `admin.json` by default: ```json { "connectors": [ { "port" : 8080 } ] } ``` Source: [admin-sa.json](../_attachments/config/admin-sa.json) By default, PingGateway implicitly defines 8085 as the `adminConnector` port, which is equivalent to `"adminConnector": { "port": 8085 }`. Also, by default, PingGateway no longer uses the (deprecated) prefix in paths to administrative endpoints. Learn more in [adminConnector](#AdminHttpApplication-adminConnector). ## More information [org.forgerock.openig.http.AdminHttpApplication](../_attachments/apidocs/org/forgerock/openig/http/AdminHttpApplication.html)