Package org.silverpeas.sso.kerberos.spnego

## Class KerberosSpnegoFilter

- java.lang.Object
- - org.silverpeas.sso.kerberos.spnego.KerberosSpnegoFilter

- All Implemented Interfaces:
    `javax.servlet.Filter`

      public final class KerberosSpnegoFilter
      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`.

  - Wikipedia: SPNEGO
  - IETF RFC: 4178

  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>org.silverpeas.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>
        </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 | Description
    --- | --- | ---
    `static class` | `KerberosSpnegoFilter.Constants` | Defines constants and parameter names that are used in the web.xml file, and HTTP request headers, etc.

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `KerberosSpnegoFilter()` |

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `void` | `destroy()` |
    `void` | `doFilter​(javax.servlet.ServletRequest request, javax.servlet.ServletResponse response, javax.servlet.FilterChain chain)` |
    `void` | `init​(javax.servlet.FilterConfig filterConfig)` |

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### KerberosSpnegoFilter

          public KerberosSpnegoFilter()

  - ### 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`