Authentication Filters
You can use the authentication filter to determine whether certain HTTP servlet requests are processed by certain providers.
The latest documentation about Liberty is available on the Open Liberty website.
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. TheuserAgent
element is compared against theUser-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 theuserAgent
element. Thehost
element is compared against theHost
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 thelessThan
orgreaterThan
values of thematchType
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>
- Contains the pattern