Authentication Filters

You can use the authentication filter to determine whether certain HTTP servlet requests are processed by certain providers.

The Liberty server authentication filter uses the filter criteria that are specified in the authFilter element in the server.xml file to determine whether certain HTTP servlet requests are processed by certain providers, such as OpenID, OpenID Connect, or SPNEGO, for authentication.

If all conditions in the authFilter element are met, the HTTP servlet request is processed by the particular provider that references that authFilter element. If any of the conditions within the authFilter element are not met, the HTTP servlet request is not processed by the provider.

Supported elements

The authFilter element supports the following elements: userAgent, host, webApp, remoteAddress, and requestUrl.

  • The userAgent element is compared against a corresponding header value that is extracted from the incoming HTTP servlet request. The userAgent element is compared against the User-Agent HTTP request header, which identifies the client software that is used by the originating request. For web client browsers, this value reflects the browser type that is used to initiate the request (Internet Explorer, Firefox, Safari, etc.).
  • The host element is used similarly to the userAgent element. The host element is compared against the Host HTTP request header, which identifies the target host name of the request.
  • The webApp element is used to specify the application, or list of applications, hosted on the Liberty server that is protected by this authentication filter.
  • The remoteAddress element is compared against the remote TCP/IP address of the client application that sent the HTTP request. You can configure wildcards for specifying subnets and ranges by using the lessThan or greaterThan values of the matchType attribute, as shown among the examples that follow later in this topic.
  • The requestUrl element is compared against the URL that is used by the client application to make the request. Single URL patterns are configured or piped lists of values are configured, as shown among the examples that follow later in this topic.

Authentication Filter examples

Request URL contains a pattern
The following example shows a typical configuration for an authentication filter. Here, any incoming request with a request URL containing "/SimpleServlet" is processed by the service that is configured to use this filter.

<authFilter id="myAuthFilter">
         <requestUrl id="myRequestUrl" urlPattern="/SimpleServlet" matchType="contains"/>
</authFilter>
Request URL contains one of a set of patterns
In the following example, a piped list of request URL patterns is specified. To process an incoming request with the service configured to use this filter, the incoming request URL must contain any one of "/SimpleServlet", "/EmployeeRoleServlet", or "/AllRoleServlet".

<authFilter id="myAuthFilter">
         <requestUrl id="myURL" urlPattern="/SimpleServlet|/EmployeeRoleServlet|/AllRoleServlet" matchType="contains" />
</authFilter>
Web application name contains a pattern
In the following example, a web application name is specified in the authentication filter. Incoming requests must target the "myApp" application to be processed by the service that is configured to use this filter.

<authFilter id="myAuthFilter">
         <webApp id="myWebApp" name="myApp" matchType="contains"/>
</authFilter>
Web application name contains one of a set of patterns
In the following example, a piped list of web applications is specified. To process an incoming request with the service configured to use this filter, the incoming request must target any one of the "myApp1", "myApp2", or "myApp3" applications.

<authFilter id="myAuthFilter">
         <webApp id="myWebApp" name="myApp1|myApp2|myApp3" matchType="contains"/>
</authFilter>
Request originates from a certain IP address
The following example shows how to use wildcards in the remoteAddress element. With this configuration, the service that is configured to use this filter processes the incoming request if the request comes from an IP address anywhere in the 127.0.0.* range.

<authFilter id="myAuthFilter">
         <remoteAddress id="myRemoteAddress" ip="127.0.0.*" matchType="equals"/>
</authFilter>
Excluding patterns
The following example shows how to use a piped list of values for the requestUrl element. Matching any of the patterns in the list is sufficient to satisfy the requirements of that particular element. In this example, the request URL must contain either "/SimpleServlet", "/EmployeeRoleServlet", or "/AllRoleServlet". In addition, the request URL must not contain "/ManagerRoleServlet" and the request must come from an Internet Explorer user agent.

<authFilter id="myAuthFilter">
         <requestUrl id="myURL1" urlPattern="/SimpleServlet|/EmployeeRoleServlet|/AllRoleServlet" matchType="contains" />
         <requestUrl id="myURL2" urlPattern="/ManagerRoleServlet" matchType="notContain" />
         <userAgent id="myAgent" agent="IE" matchType="contains" />
</authFilter>
Example using all sub-elements
To process an incoming request with the service configured to use this filter, the request must meet the following conditions:
  • Contains the pattern "/SimpleServlet" in the request URL
  • Targets a domain that contains "host.example.com"
  • Comes from the IP address 127.0.0.1
  • Comes from a Firefox browser
  • The name of the target application is myApp

<authFilter id="myAuthFilter">
         <requestUrl id="myRequestUrl" urlPattern="/SimpleServlet" matchType="contains"/>
         <host id="myHost" name="host.example.com" matchType="contains"/>
         <remoteAddress id="myAddress" ip="127.0.0.1" matchType="equals" />
         <userAgent id="myUserAgent" agent="Firefox" matchType="equals"/>
         <webApp id="myWebApp" name="myApp" matchType="contains"/>
</authFilter>