Web Agents 2024.3

Not-enforced rules

Some resources, such as the "public" directory of a web application, contain data that is not sensitive. It can be accessed by any, authenticated or unauthenticated, clients. The agent uses lists of not-enforced rules to identify these resources in the web application.

The agent matches incoming requests to the lists of not-enforced rules. When a request matches a not-enforced rule, the agent bypasses the call to AM:

  • If an unauthenticated user sent the request, the agent does not redirect the user to log in.

  • If an authenticated user sent the request, the agent does not request a policy evaluation from AM.

Use not-enforced rules to reduce the number of unnecessary calls to AM, and therefore improve the performance and speed of your application.

The following image shows the data flow when Web Agents Documentation evaluates not-enforced rules for a request:

not-enforced-flow

1-2. A client requests a resource and the agent checks whether the request matches a rule in a not-enforced list.

3-5. If the request matches a rule, the agent passes the request without requiring authentication or policy decisions. Otherwise, the agent checks whether rules are inverted.

6-10. If the request matches an inverted rule, the agent passes the request without requiring authentication or policy decisions. Otherwise, the agent enforces authentication and policy decisions.

Conventions for not-enforced rules

Consider the following points about not-enforced rules:

  • Web servers normalize request URLs as described in RFC 3986: Normalization and comparison before passing them to the agent. The agent compares the normalized URL to the not-enforced rule.

  • Trailing forward-slashes / can represent a directory. Therefore, /images/ does not match /images, but does match /images/index.html

Invert not-enforced URL rules

Invert all rules in a not-enforced URL list by setting Invert Not-Enforced URLs to true.

Consider the following points when you invert all rules:

  • If Not-Enforced URL List is empty, all URLs are enforced.

  • At least one URL must be enforced. To allow access to any URL without authentication, consider disabling the agent.

Wildcards

For more information about using wildcards, refer to Wildcards.

Multi-level wildcard (*)

The following list summarizes the behavior of the multi-level wildcard (*):

  • Matches zero or more occurrences of any character except for the question mark (?).

  • Spans multiple levels in a URL.

  • Cannot be escaped. Therefore, the backslash (\) or other characters cannot be used to escape the asterisk, as such \*.

  • Cannot be used in the same rule as the one-level wildcard (-*-) or regular expression.

  • Explicit patterns are required to match URL parameters. For example:

    • URL patterns ending with /foo* do not match URLs with parameters

    • URL patterns ending with /foo*?* match any parameter

Multi-level wildcard for not-enforced IP rules
Rules in Not-Enforced IP List Matches request IP Does not match request IP

192.168.1.*

192.168.1.0

192.168.1.0/24

192.168.0.1
Multi-level wildcard for not-enforced URI rules
Rules in Not-Enforced URL List Matches request URL Does not match request URL

http://A-examp.com:8080/*

http://A-examp.com:8080/

http://A-examp.com:8080/index.html

http://A-examp.com:8080/x.gif

http://B-examp.com:8080/

http://A-examp.com:8090/index.html

http://A-examp.com:8080/a?b=1

http://A-examp.com:8080/*.html

http://A-examp.com:8080/index.html

http://A-examp.com:8080/pub/ab.html

http://A-examp.com:8080/pri/xy.html

http://A-examp.com/index.html

http://A-examp.com:8080/x.gif

http://B-examp.com/index.html

http://A-examp.com:8080/*/ab

http://A-examp.com:8080/pri/xy/ab/xy/ab

http://A-examp.com:8080/xy/ab

http://A-examp.com/ab

http://A-examp.com/ab.html

http://B-examp.com:8080/ab

http://A-examp.com:8080/ab/*/de

http://A-examp.com:8080/ab/123/de

http://A-examp.com:8080/ab/ab/de

http://A-examp.com:8080/ab/de/ab/de

http://A-examp.com:8080/ab/de

http://A-examp.com:8090/ab/de

http://B-examp.com:8080/ab/de/ab/de

One-level wildcard (-*-)

The following list summarizes the behavior of the one-level wildcard (-*-):

  • Matches zero or more occurrences of any character except for the forward-slash (/) and the question mark (?).

  • Does not span across multiple levels in a URL.

  • Cannot be escaped. Therefore, the backslash (\) or other characters cannot be used to escape the hyphen-asterisk-hyphen, like this \-*-.

  • Cannot be used in the same rule as the multi-level wildcard (*) or regular expression.

One-level wildcard for not-enforced URI rules
Rules in Not-Enforced URL List Matches request URL Does not match request URL

http://A-examp.com:8080/b/-*-

http://A-examp.com:8080/b/

http://A-examp.com:8080/b/cd

http://A-examp.com:8080/b

http://A-examp.com:8080/b/cd/ (This URL should match the rule, but does not because of the known issue AMAGENTS-4672.)

http://A-examp.com:8080/b/c?d=e

http://A-examp.com:8080/b/cd/e

http://A-examp.com:8090/b/

http://A-examp.com:8080/b/-*-/f

http://A-examp.com:8080/b/c/f

http://A-examp.com:8080/b/cde/f

http://A-examp.com:8080/b/c/e/f

http://A-examp.com:8080/f/

http://A-examp.com:8080/b/c-*-/f

http://A-examp.com:8080/b/cde/f

http://A-examp.com:8080/b/cd/f

http://A-examp.com:8080/b/c/f

http://A-examp.com:8080/b/c/e/f

http://A-examp.com:8080/b/c/

http://A-examp.com:8080/b/c/fg

Multiple wildcards

When multiple wildcards are included in the same rule of a Not-Enforced URL List, the agent matches the parameters in any order that they appear in a resource URI.

For example, the following rule applies to any resource URI that contains a member_level and location query parameter, in any order:

com.sun.identity.agents.config.notenforced.url[1]=http://www.example.com:8080/customers/*?*member_level=*&location=*

In following example, the requests would be not-enforced:

https://www.example.com/customers/default.jsp?member_level=silver&location=fr
https://www.example.com/customers/default.jsp?location=es&member_level=silver
https://www.example.com/customers/default.jsp?location=uk&vip=true&member_level=gold

Regular expressions

Regular expressions are evaluated differently by different engines. When you use regular expressions in not-enforced lists, make sure that the expressions are evaluated in the way you expect. Double check that the correct URLs are enforced and not enforced.

Set Regular Expressions for Not-Enforced URLs to true, and consider the following points for using regular expressions in not-enforced rules:

  • Wildcards cannot be used. The asterisk * is not treated as a wildcard, but is treated as part of the expression, representing repetition of the last character 0-n times.

  • The following formats cannot be used:

    • Netmask CIDR notation

    • IP address ranges

    However, regular expressions can match a range of IP addresses, such as:

    com.sun.identity.agents.config.notenforced.ip[1]=192\.168\.10\.(10|\d)

  • If an invalid regular expression is specified in a rule, the rule is dropped, and an error message is logged.

HTTP Methods

Rules that apply an HTTP method filter are configured as custom properties in AM.

Add one or more HTTP method keywords followed by an index value. The not-enforced rule is applied when the incoming request uses the HTTP method. Keywords include but are not restricted to GET, HEAD, POST, PUT, PATCH, DELETE, and OPTIONS.

If the same method is used in multiple rules, increment the index to make the rule unique:

com.sun.identity.agents.config.notenforced.url[PATCH,1]=http://www.example.com:8080/scripts/*
com.sun.identity.agents.config.notenforced.url[PATCH,2]=http://www.other.com:8080/scripts/*

By default, no HTTP method is specified for a rule, and all methods are not-enforced for that rule. When one or more HTTP methods are specified, only those methods are not-enforced; methods that are not specified are enforced.

The following example does not enforce OPTIONS requests to the scripts directory, but does enforce other HTTP methods:

com.sun.identity.agents.config.notenforced.url[OPTIONS,1]=http://www.example.com:8080/scripts/*

To specify a list of methods, add multiple rules:

com.sun.identity.agents.config.notenforced.url[OPTIONS,1]=http://www.example.com:8080/scripts/*
com.sun.identity.agents.config.notenforced.url[PATCH,2]=http://www.other.com:8080/scripts/*
com.sun.identity.agents.config.notenforced.url[TRACE,3]=http://www.example.com:8080/scripts/*

Unrecognized methods can invalidate a rule.

Compound rules

Configure compound rules in Not-Enforced URL from IP Processing List.

In the following example, the agent does not enforce HTTP requests from the IP addresses 192.6.8.0/24 to any file in /public, or any files or directories that start with the string login in the directory /free_access URI:

org.forgerock.agents.config.notenforced.ipurl[1]=192.6.8.0/24|http://www.example.com:8080/public/* */free_access/login*

Encoding non-ASCII characters in rules

Percent-encode resources that use non-ASCII characters.

For example, to match resources to the URI http://www.example.com/forstå, specify the following percent-encoded rule:

/forst%C3%A5/*