SpnegoHttpFilter

java.lang.Object
- net.sourceforge.spnego.SpnegoHttpFilter

All Implemented Interfaces:: javax.servlet.Filter

public final class SpnegoHttpFilter
extends Object
implements javax.servlet.Filter

Http Servlet Filter that provides SPNEGO authentication. It allows servlet containers like Tomcat and JBoss to transparently/silently authenticate HTTP clients like Microsoft Internet Explorer (MSIE).

This feature in MSIE is sometimes referred to as single sign-on and/or Integrated Windows Authentication. In general, there are at least two authentication mechanisms that allow an HTTP server and an HTTP client to achieve single sign-on: NTLM and Kerberos/SPNEGO.

NTLM
MSIE has the ability to negotiate NTLM password hashes over an HTTP session using Base 64 encoded NTLMSSP messages. This is a staple feature of Microsoft's Internet Information Server (IIS). Open source libraries exists (ie. jCIFS) that provide NTLM-based authentication capabilities to Servlet Containers. jCIFS uses NTLM and Microsoft's Active Directory (AD) to authenticate MSIE clients.

SpnegoHttpFilter does NOT support NTLM (tokens).

Kerberos/SPNEGO
Kerberos is an authentication protocol that is implemented in AD. The protocol does not negotiate passwords between a client and a server but rather uses tokens to securely prove/authenticate to one another over an un-secure network.

SpnegoHttpFilter does support Kerberos but through the pseudo-mechanism SPNEGO.

Localhost Support
The Kerberos protocol requires that a service must have a Principal Name (SPN) specified. However, there are some use-cases where it may not be practical to specify an SPN (ie. Tomcat running on a developer's machine). The DNS http://localhost is supported but must be configured in the servlet filter's init params in the web.xml file.

Modifying the web.xml file

Here's an example configuration:

  <filter>
      <filter-name>SpnegoHttpFilter</filter-name>
      <filter-class>net.sourceforge.spnego.SpnegoHttpFilter</filter-class>
      
      <init-param>
          <param-name>spnego.allow.basic</param-name>
          <param-value>true</param-value>
      </init-param>
          
      <init-param>
          <param-name>spnego.allow.localhost</param-name>
          <param-value>true</param-value>
      </init-param>
          
      <init-param>
          <param-name>spnego.allow.unsecure.basic</param-name>
          <param-value>true</param-value>
      </init-param>
          
      <init-param>
          <param-name>spnego.login.client.module</param-name>
          <param-value>spnego-client</param-value>
      </init-param>
      
      <init-param>
          <param-name>spnego.krb5.conf</param-name>
          <param-value>krb5.conf</param-value>
      </init-param>
          
      <init-param>
          <param-name>spnego.login.conf</param-name>
          <param-value>login.conf</param-value>
      </init-param>
          
      <init-param>
          <param-name>spnego.preauth.username</param-name>
          <param-value>Zeus</param-value>
      </init-param>
          
      <init-param>
          <param-name>spnego.preauth.password</param-name>
          <param-value>Zeus_Password</param-value>
      </init-param>
          
      <init-param>
          <param-name>spnego.login.server.module</param-name>
          <param-value>spnego-server</param-value>
      </init-param>
          
      <init-param>
          <param-name>spnego.prompt.ntlm</param-name>
          <param-value>true</param-value>
      </init-param>
          
      <init-param>
          <param-name>spnego.logger.level</param-name>
          <param-value>1</param-value>
      </init-param>
  </filter>

Example usage on web page

  <html>
  <head>
      <title>Hello SPNEGO Example</title>
  </head>
  <body>
  Hello <%= request.getRemoteUser() %> !
  </body>
  </html>

Take a look at the reference docs for other configuration parameters.

See more usage examples at http://spnego.sourceforge.net

Author:: Darwin V. Felix

Nested Class Summary

Nested Classes
Modifier and Type	Class and Description
`static class`	`SpnegoHttpFilter.Constants` Defines constants and parameter names that are used in the web.xml file, and HTTP request headers, etc.

Field Summary

Fields
Modifier and Type	Field and Description
`private UserAccessControl`	`accessControl` Object for performing User Authorization.
`private SpnegoAuthenticator`	`authenticator` Object for performing Basic and SPNEGO authentication.
`private List<String>`	`excludeDirs` directories which should not be authenticated irrespective of filter-mapping.
`private static Logger`	`LOGGER`
`private String`	`page403` Landing page if user is denied authZ access.
`private String`	`sitewide` AuthZ required for every page.

Constructor Summary

Constructors
Constructor and Description

SpnegoHttpFilter()

Constructors
Constructor and Description
`SpnegoHttpFilter()`

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`destroy()`
`void`	`doFilter(javax.servlet.ServletRequest request, javax.servlet.ServletResponse response, javax.servlet.FilterChain chain)`
`private boolean`	`exclude(String contextPath, String servletPath)`
`void`	`init(javax.servlet.FilterConfig filterConfig)`
`private boolean`	`isAuthorized(javax.servlet.http.HttpServletRequest request)`
`private static Properties`	`toProperties(javax.servlet.FilterConfig filterConfig)`

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail
- LOGGER
```
private static final Logger LOGGER
```
- authenticator
```
private transient SpnegoAuthenticator authenticator
```
  Object for performing Basic and SPNEGO authentication.
- accessControl
```
private transient UserAccessControl accessControl
```
  Object for performing User Authorization.
- sitewide
```
private transient String sitewide
```
  AuthZ required for every page.
- page403
```
private transient String page403
```
  Landing page if user is denied authZ access.
- excludeDirs
```
private final transient List<String> excludeDirs
```
  directories which should not be authenticated irrespective of filter-mapping.

Constructor Detail
- SpnegoHttpFilter
```
public SpnegoHttpFilter()
```

Method Detail

init

public void init(javax.servlet.FilterConfig filterConfig)
          throws javax.servlet.ServletException

Specified by:: init in interface javax.servlet.Filter
Throws:: javax.servlet.ServletException

destroy
```
public void destroy()
```
Specified by:

destroy in interface javax.servlet.Filter

doFilter

public void doFilter(javax.servlet.ServletRequest request,
                     javax.servlet.ServletResponse response,
                     javax.servlet.FilterChain chain)
              throws IOException,
                     javax.servlet.ServletException

Specified by:: doFilter in interface javax.servlet.Filter
Throws:: IOException; javax.servlet.ServletException

isAuthorized

private boolean isAuthorized(javax.servlet.http.HttpServletRequest request)

exclude

private boolean exclude(String contextPath,
                        String servletPath)

toProperties

private static Properties toProperties(javax.servlet.FilterConfig filterConfig)

Class SpnegoHttpFilter

Nested Class Summary

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

LOGGER

authenticator

accessControl

sitewide

page403

excludeDirs

Constructor Detail