--- title: AllowOnlyFilter description: Authorizes a request to continue processing if it satisfies at least one of the configured rules. Otherwise, passes the request to the FailureHandler or returns an HTTP 401 Unauthorized, with an empty response body. component: pinggateway version: 2026 page_id: pinggateway:reference:AllowOnlyFilter canonical_url: https://docs.pingidentity.com/pinggateway/2026/reference/AllowOnlyFilter.html revdate: 2025-08-26T18:26:39Z section_ids: AllowOnlyFilter-usage: Usage AllowOnlyFilter-properties: Properties AllowOnlyFilter-example: Examples certificate_and_ip_address_conditions: Certificate and IP address conditions destination_conditions: Destination conditions multiple_rules: Multiple rules AllowOnlyFilter-moreinfo: More information --- # AllowOnlyFilter Authorizes a request to continue processing if it satisfies at least one of the configured rules. Otherwise, passes the request to the FailureHandler or returns an HTTP 401 Unauthorized, with an empty response body. This filter manages requests from the *last request sender*, otherwise called the *request from the last hop*, or the *request from a direct client*. For debugging, configure the AllowOnlyFilter `name`, and add the following logger to `logback.xml`, replacing filter\_name with the name: ``` org.forgerock.openig.filter.allow.AllowOnlyFilter.filter_name ``` For more information, see [Managing PingGateway logs](../maintenance-guide/logging.html). ## Usage ```json { "name": string, "type": "AllowOnlyFilter", "config": { "rules": [ object, ... ], "failureHandler": Handler reference } } ``` ## Properties * `"rules"`: *array of [objects](preface.html#definition-object), required* An array of one or more `rules` configuration objects to specify criteria for the request. When more than one `rules` configuration object is included in the array, the request must match at least one of the configuration objects. When more than one property is specified in the `rules` configuration (for example, `from` and `destination`) the request must match criteria for each property. ```json { "rules": [ { "name": configuration expression, "from": [ object, ... ], "destination": [ object, ... ], "when": runtime condition }, ... ] } ``` * `"name"`: *configuration expression<[string](preface.html#definition-string)>, optional* A name for the `rules` configuration. When logging is configured for the AllowOnlyFilter, the rule name appears in the logs. * `"from"`: *array of [objects](preface.html#definition-object), required* An array of one or more `from` configuration objects to specify criteria about the last request sender (the direct client). When more than one `from` configuration object is included in the array, the last request sender must match at least one of the configuration objects. When both `ip` and `certificate` properties are included in the configuration, the last request sender must match criteria for both properties. ```json "from": [ { "ip": { "list": [configuration expression, ...], "resolver": runtime expression }, "certificate" : { "subjectDNs" : Pattern[] } }, ... ] ``` * `"ip"`: *[object](preface.html#definition-object), optional* Criteria about the IP address of the last request sender. * `"list"`: *array of configuration expression<[strings](preface.html#definition-string)>, required*: An array of IP addresses or IP address ranges, using IPv4 or IPv6, and CIDR notation. The following example includes different formats: ```json "list": ["127.0.0.1", "::1", "192.168.0.0/16", "1234::/16"] ``` The IP address of the last request sender must match at least one of the specified IP addresses or IP address ranges. * `"resolver"`: *runtime expression<[string](preface.html#definition-string)>, optional*: An expression that returns an IP address as a string. The following example returns an IP address from the first item in the first [`X-Forwarded-For` header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Forwarded-For): ```none "resolver": "${split(request.headers['X-Forwarded-For'][0], ',')[0]}" ``` Default: Resolve the IP address from the following items, in the following order: 1. If there is a `Forwarded` header, use the IP address of the last hop. 2. Otherwise, if there is an `X-Forwarded-For` header, use the IP address of the last hop. 3. Otherwise, use the IP address of the connection. * `"certificate"`: *[object](preface.html#definition-object), optional* A `certificate` configuration object specifying criteria about the certificate of the last request sender. * `"subjectDNs"`: *array of [patterns](preface.html#definition-pattern), required*: An array of patterns to represent the expected distinguished name of the certificate subject, the `subjectDN`. The `subjectDN` of the last request sender must match at least one of the patterns. * `"destination"`: *array of [objects](preface.html#definition-object), optional* An array of `destination` configuration objects to specify criteria about the request destination. When more than one `destination` configuration object is included in the array, the request destination must match at least one of the configuration objects. When more than one property is specified in the `destination` configuration, for example `hosts` and `ports`, the request destination must match criteria for each property. ```json "destination": [ { "hosts": [pattern, ... ], "ports": [configuration expression, ... ], "methods": [configuration expression, ... ], "paths": [pattern, ... ] }, ... ] ``` * `"hosts"`: *array of [patterns](preface.html#definition-pattern), optional* An array of *case-insensitive* patterns to match the `request.host` attribute. Patterns are matched with the Java [Pattern](https://docs.oracle.com/en/java/javase/25/docs/api/java.base/java/util/regex/Pattern.html) class. When this property is configured, the request destination must match at least one host pattern in the array. Default: Any host is allowed. * `"ports"`: *array of configuration expression<[strings](preface.html#definition-string)>, optional* An array of strings to match the `request.port` attribute. Specify values in the array as follows: * Array of single ports, for example `["80", "90"]`. * Array of port ranges, for example `["100:200"]`. * Array of single ports and port ranges, for example `["80", "90", "100:200"]`. When this property is configured, the destination port must match at least one entry in the array. Default: Any port is allowed. * `"methods"`: *array of configuration expression<[strings](preface.html#definition-string)>, optional* An array of HTTP methods to match the `request.method` attribute. When this property is configured, the request method must match at least one method in the array. Default: Any method is allowed. * `"paths"`: *array of [patterns](preface.html#definition-pattern), optional* An array of *case-sensitive* patterns to match the `request.url_path` attribute. Patterns are matched with the Java [Pattern](https://docs.oracle.com/en/java/javase/25/docs/api/java.base/java/util/regex/Pattern.html) class. When this property is configured, the destination path must match at least one path in the array. Default: Any path is allowed. * `"when"`: *runtime condition<[boolean](preface.html#definition-boolean)>, optional* A [condition](Conditions.html) whose expression indicates the request meets a condition. When the condition's expression evaluates to `true`, PingGateway allows the request. The following condition is met when the first value of `h1` is `1`: ```json "when": "${request.headers['h1'][0] == '1'}" ``` Default: `true` * `"failureHandler"`: *Handler [reference](preface.html#definition-reference), optional* Handler to treat the request if none of the declared rules are satisfied. Provide either the name of a Handler object defined in the heap or an inline Handler configuration object. Default: HTTP 401 Unauthorized, with an empty response body. See also [PingGateway handlers](Handlers.html). ## Examples ### Certificate and IP address conditions In the following example, a request is authorized if the last request sender satisfies *either* of the following conditions: * Certificate subject DN matches `.*CN=test$` *or* `CN=me`, *and* the IP address is in the range 1.2.3.0/24. * IP address is 123.43.56.8. ```json "from": [ { "certificate": { "subjectDNs": [".*CN=test$", "CN=me"] }, "ip": { "list": ["1.2.3.0/24"] } }, { "ip": { "list": ["123.43.56.8"] } }, ] ``` ### Destination conditions In the following example, a request is authorized if the request destination satisfies *all* of the following conditions: * The host is `myhost1.com` *or* `www.myhost1.com` * The port is `80`. * The method is `POST` *or* `GET` * The path matches `/user/*`. ```json "destination": [ { "hosts": ["myhost1.com", "www.myhost1.com"], "ports": ["80"], "methods": ["POST", "GET"], "paths": ["/user/*"] } ] ``` ### Multiple rules The following example authorizes a request to continue processing if the requests meets the conditions set by *either* `rule1` or `rule2`: ```json { "type": "AllowOnlyFilter", "config": { "rules": [ { "name": "rule1", "from": [ { "certificate": { "subjectDNs": [".*CN=test$", "CN=me"] }, "ip": { "list": ["1.2.3.0/24"] } } ], "destination": [ { "hosts": ["myhost1.com", "www.myhost1.com"], "ports": ["80"], "methods": ["POST", "GET"], "paths": ["/user/*"] } ], "when": "${request.headers['h1'][0] == '1'}" }, { "name":"rule2", "when": "${request.headers['h1'][0] == '2'}" } ] } } ``` ## More information [org.forgerock.openig.filter.allow.AllowOnlyFilter](../_attachments/apidocs/org/forgerock/openig/filter/allow/AllowOnlyFilter.html)