A Servlet Authentication Filter is a provider type that performs pre- and post-processing for authentication functions, including identity assertion. A Servlet Authentication Filter is a special type of security provider that primarily acts as a “helper” to an Authentication provider.
The ServletAuthenticationFilter
interface defines the security service provider interface (SSPI) for authentication filters that can be plugged in to WebLogic Server. You implement the ServletAuthenticationFilter
interface as part of an Authentication provider, and typically as part of the Identity Assertion form of Authentication provider, to signal that the Authentication provider has authentication filters that it wants the servlet container to invoke during the authentication process.
The following sections describe Servlet Authentication Filter interface concepts and functionality, and provide step-by-step instructions for developing a Servlet Authentication Filter:
Filters, as defined by the Java Servlet API 2.3 specification, are preprocessors of the request before it reaches the servlet, and/or postprocessors of the response leaving the servlet. Filters provide the ability to encapsulate recurring tasks in reusable units and can be used to transform the response from a servlet or JSP page.
Servlet Authentication filters are an extension to of the filter object that allows filters to replace or extend container-based authentication.
The WebLogic Security Framework allows you to provide a custom Authentication provider. However, due to the nature of the Java Servlet API 2.3 specification, the interaction between the Authentication provider and the client or other servers is architecturally limited during the authentication process. This restricts authentication mechanisms to those that are compatible with the authentication mechanisms the Servlet container offers: basic, form, and certificate.
Filters have fewer architecturally-dependence limitations; that is, they are not dependent on the authentication mechanisms offered by the Servlet container. By allowing filters to be invoked prior to the container beginning the authentication process, a security realm can implement a wider scope of authentication mechanisms. For example, a Servlet Authentication Filter could redirect the user to a SAML provider site for authentication.
JAAS LoginModules (within a WebLogic Authentication provider) can be used for customization of the login process. Customizing the location of the user database, the types of proof material required to execute a login, or the population of the Subject with groups is implemented via a LoginModule.
Conversely, redirecting to a remote site to execute the login, extracting login information out of the query string, and negotiating a login mechanism with a browser are implemented via a Servlet Authentication Filter.
You should consider the following design considerations when writing Servlet Authentication Filters:
The Servlet Authentication Filter interface allows an Authentication provider to implement zero or more Servlet Authentication Filter classes. The filters are invoked as follows:
The servlet container gets the configured chain of Servlet Authentication Filters from the WebLogic Security Framework.
The Security Framework returns the Servlet Authentication Filters in the order of the authentication providers. If one provider has multiple Servlet Authentication Filters, the Security Framework uses the ordered list of javax.servlet.Filters returned by the ServletAuthenticationFilter getAuthenticationFilters
method.
Duplicate filters are allowed because they might need to execute multiple times to correctly manipulate the request.
init
method to indicate to a filter that it is being placed into service.doFilter
method on the first filter each time a request/response pair is passed through the chain due to a client request for a resource at the end of the chain.The FilterChain object passed in to this method allows the Filter to pass on the request and response to the next entity in the chain. Filters use the FilterChain object to invoke the next filter in the chain, or if the calling filter is the last filter in the chain, to invoke the resource at the end of the chain.
doFilter
method then, when the final one calls the doFilter
method, the servlet container then performs authentication as it would if the filters were not present.
However, if any of the Servlet Authentication Filters do not call the doFilter
method, the remaining filters, the servlet, and the servlet container’s authentication procedure are not called. This allows a filter to replace the servlet’s authentication process. This typically involves authentication failure or redirecting to another URL for authentication.
Although you implement the Servlet Authentication Filter interface as part of an Authentication provider, Authentication providers do not actually call Servlet Authentication Filters directly. The implementation of Servlet Authentication Filters depends upon particular features of the WebLogic Security Framework that know how to locate and invoke the filters.
If you develop a custom Servlet Authentication Filter, make sure that your custom Authentication providers do not call the WLS-specific classes (for example, weblogic.servlet.*) and the Java EE-specific classes (for example, javax.servlet.*). Following this rule ensures maximum portability with WebLogic Enterprise Security.
Figure 13-1 illustrates this requirement.
WebLogic Server includes a Servlet Authentication Filter that handles the header manipulation required by the Simple and Protected Negotiate (SPNEGO). This Servlet Authentication Filter, called the “Negotiate Servlet Authentication Filter,” is configured to support the WWW-Authenticate and Authorization HTTP headers.
The Negotiate Servlet Authentication Filter generates the appropriate WWW-Authenticate header on unauthorized responses for the negotiate protocol and handles the Authorization headers on subsequent requests. The filter is available through the Negotiate Identity Assertion Provider.
By default, the Negotiate Identity Assertion provider is available, but not configured, in the WebLogic default security realm. The Negotiate Identity Assertion provider can be used instead of, or in addition to, the WebLogic Identity Assertion provider.
You can develop a custom Servlet Authentication Filter by following these steps:
Before you start creating runtime classes, you should first:
When you understand this information and have made your design decisions, create the runtime classes for your Servlet Authentication Filter by following these steps:
For an example of how to create a runtime class for a custom Servlet Authentication Filter provider, see Generate an MBean Type Using the WebLogic MBeanMaker
You implement the ServletAuthenticationFilter
interface as part of an Authentication provider to signal that the Authentication provider has authentication filters that it wants the servlet container to invoke during the authentication process.
To implement the Servlet Authentication Filter SSPI, provide an implementation for the following method:
getServletAuthenticationFilters
method returns an ordered list of the javax.servlet.Filters that are executed during the authentication process of the Servlet container. The container may call this method multiple times to get multiple instances of the Servlet Authentication Filter. On each call, this method should return a list of new instances of the filters.
To implement the Filter interface methods, provide implementations for the following methods. In typical use, you would call init()
once, doFilter() possibly many times, and destroy() once.
doFilter
method of the Filter is called by the container each time a request/response pair is passed through the chain due to a client request for a resource at the end of the chain. The FilterChain passed in to this method allows the Filter to pass on the request and response to the next entity in the chain.
A typical implementation of this method would follow the following pattern:
1. Examine the request.
2. Optionally, wrap the request object with a custom implementation to filter content or headers for input filtering.
3. Optionally, wrap the response object with a custom implementation to filter content or headers for output filtering.
4. Either invoke the next entity in the chain using the FilterChain object (chain.doFilter()), or do not pass on the request/response pair to the next entity in the filter chain to block the request processing.
5. Directly set headers on the response after invocation of the next entity in the filter chain.
init
method must complete successfully before the filter is asked to do any filtering work.
As described in Identity Assertion Providers, the Challenge Identity Assertion interface supports challenge response schemes in which multiple challenges, responses messages, and state are required. The Challenge Identity Asserter interface allows Identity Assertion providers to support authentication protocols such as Microsoft's Windows NT Challenge/Response (NTLM), Simple and Protected GSS-API Negotiation Mechanism (SPNEGO), and other challenge/response authentication mechanisms.
Servlet Authentication Filters allow you to implement a challenge/response protocol without being limited to the authentication mechanisms compatible with the Servlet container. However, because Servlet Authentication Filters operate outside of the authentication environment provided by the Security Framework, they cannot depend on the Security Framework to determine provider context, and require an API to drive the multiple-challenge Identity Assertion process.
The weblogic.security.services.Authentication
class has been extended to allow multiple challenge/response identity assertion from a Servlet Authentication Filter. The methods and interface provide a wrapper for the ChallengeIdentityAsserterV2
and ProviderChallengeContext
SSPI interfaces so that you can invoke them from a Servlet Authentication Filter.
There is no other documented way to perform a multiple challenge/response dialog from a Servlet Authentication Filter within the context of the Security Framework. Your Servlet Authentication Filter cannot directly invoke the ChallengeIdentityAsserterV2
and ProviderChallengeContext
interfaces.
Therefore, if you plan to implement multiple challenge/response identity assertion from a filter, you need to implement the ChallengeIdentityAsserterV2
and ProviderChallengeContext
interfaces, and then use the weblogic.security.services.Authentication
methods and AppChallengeContect
interface to invoke them from a Servlet Authentication Filter.
The steps to accomplish this process are described in Identity Assertion Providers, and are summarized here:
or
Implement the IdentityAsserterV2 SSPIWhen you generate the MBean type for your custom Authentication provider as described in Authentication Providers, you must also implement the MBean for your Servlet Authentication Filter.
The ServletAuthenticationFilter MBean extends the AuthenticationProvider MBean. The ServletAuthenticationFilter MBean is a marker interface and has no methods.
<?xml version="1.0" ?>
<!DOCTYPE MBeanType SYSTEM "commo.dtd">
<MBeanType
Name = "ServletAuthenticationFilter"
Package = "weblogic.management.security.authentication"
Extends = "weblogic.management.security.authentication.AuthenticationProvider"
PersistPolicy = "OnUpdate"
Abstract = "true"
Description = "The SSPI MBean that all Servlet Authentication Filter providers must extend.
This MBean is just a marker interface. It has no methods on it."
>
</MBeanType>
Once your have run your MDF through the WebLogic MBeanMaker to generate your intermediate files, and you have edited the MBean implementation file to supply implementations for the appropriate methods within it, you need to package the MBean files and the runtime classes for the custom Authentication provider, including the Servlet Authentication Filter, into an MBean JAR File (MJF).
These steps are described for the custom Authentication provider in Use the WebLogic MBeanMaker to Create the MBean JAR File (MJF).
Configuring a custom Authentication provider that implements a Servlet Authentication Filter means that you are adding the custom Authorization provider to your security realm, where it can be accessed by applications requiring authorization services.
Configuring custom security providers is an administrative task, but it is a task that may also be performed by developers of custom security providers.
The steps for configuring a custom Authorization provider using the WebLogic Server Administration Console are described under “Configuring WebLogic Security Providers” in Securing WebLogic Server.