PingGateway 2024.9

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 Manage logs.

Usage

{
  "name": string,
  "type": "AllowOnlyFilter",
  "config": {
    "rules": [ object, ... ],
    "failureHandler": Handler reference
  }
}

Properties

"rules": array of objects, 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.

{
  "rules": [
    {
      "name": configuration expression<string>,
      "from": [ object, ... ],
      "destination": [ object, ... ],
      "when": configuration expression<boolean>
    },
    ...
  ]
}
"name": configuration expression<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, 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.

"from": [
  {
    "ip": {
      "list": [configuration expression<string>, ...],
      "resolver": runtime expression<string>
    },
    "certificate" : {
      "subjectDNs" : Pattern[]
    }
  },
  ...
]
"ip": object, optional

Criteria about the IP address of the last request sender.

"list": array of configuration expression<strings>, required:

An array of IP addresses or IP address ranges, using IPv4 or IPv6, and CIDR notation. The following example includes different formats:

"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>, 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:

"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, optional

A certificate configuration object specifying criteria about the certificate of the last request sender.

"subjectDNs": array of patterns, 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, 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.

"destination": [
  {
    "hosts": [pattern, ... ],
    "ports": [configuration expression<string>, ... ],
    "methods": [configuration expression<string>, ... ],
    "paths": [pattern, ... ]
  },
  ...
]
"hosts": array of patterns, optional

An array of case-insensitive patterns to match the request.host attribute. Patterns are matched with the Java Pattern 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>, 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>, 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, optional

An array of case-sensitive patterns to match the request.url_path attribute. Patterns are matched with the Java Pattern 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 expression<boolean>, optional

A flag to indicate that the request meets a condition. When true, the request is allowed.

The following condition is met when the first value of h1 is 1:

"when": "${request.headers['h1'][0] == '1'}"

Default: ${true}

"failureHandler": Handler 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 Handlers.

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.

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

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

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