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
anddestination
) 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
andcertificate
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
X-Forwarded-For
:"resolver": "${request.headers['X-Forwarded-For'][0]}"
Default: Resolve the IP address from the following items, in the following order:
-
If there is a
Forwarded
header, use the IP address of the last hop. -
Otherwise, if there is an
X-Forwarded-For
header, use the IP address of the last hop. -
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
. ThesubjectDN
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 examplehosts
andports
, 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
is1
:"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$
orCN=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
orwww.myhost1.com
-
The port is
80
. -
The method is
POST
orGET
-
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'}"
}
]
}
}