Servlet Authentication Filters

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:

Authentication Filter Concepts

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.

Why Filters are Needed

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.

Servlet Authentication Filter Design Considerations

You should consider the following design considerations when writing Servlet Authentication Filters:

Do you need to allow multiple filters to be specified? You might want to allow this so that administrative decisions can be made at configuration time.
Do you depend on a particular order of-execution? Servlet Authentication Filters must not be dependent on the order in which filters are executed.
Have you considered allowing each filter to process the request both before and after authentication? If so, the filter should not make any assumptions about when it is being invoked.
Consider allowing each filter to have the option of stopping the execution of the remaining filters and the Servlet’s authentication process by not calling the Filter doFilter method.
Do you need to allow a filter to cause the browser to redirect?
Consider allowing a filter to work for 1-way SSL, 2-way SSL, identity assertion, form authentication, and basic authentication. For example, Form authentication is a two-request process and the filter is called twice for form authentication.

How Filters Are Invoked

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 calls the Servlet Authentication Filters prior to authentication occurring.

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.

For each filter, the servlet container calls the Filter init method to indicate to a filter that it is being placed into service.
The servlet container calls the Filter 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.

If all Servlet Authentication Filters call the Filter 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.

Do Not Call Servlet Authentication Filters From Authentication Providers

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.

Example of a Provider that Implements a Filter

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.

How to Develop a Custom Servlet Authentication Filter

You can develop a custom Servlet Authentication Filter by following these steps:

Create Runtime Classes Using the Appropriate SSPIs

When you understand this information and have made your design decisions, create the runtime classes for your Servlet Authentication Filter by following these steps:

Implement the Servlet Authentication Filter SSPI

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:

get Servlet Authentication Filters

Implement the Filter Interface Methods

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.

destroy

The destroy method is called by the web container to indicate to a filter that it is being taken out of service. This method is only called once all threads within the filter's doFilter method have exited, or after a timeout period has passed. After the web container calls this method, it does not call the doFilter method again on this instance of the filter. This method gives the filter an opportunity to clean up any resources that are being held (for example, memory, file handles, threads) and make sure that any persistent state is synchronized with the filter's current state in memory

doFilter

The 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

Implementing Challenge Identity Assertion from a Filter

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.

Generate an MBean Type Using the WebLogic MBeanMaker

When 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."
>

Use the WebLogic MBeanMaker to Create the MBean JAR File (MJF)

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).

Configure the Authentication Provider Using Administration Console

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.

Developing Security Providers for WebLogic Server