## org.apache.hadoop.security.authentication.server
Class AuthenticationFilter

    java.lang.Object
      org.apache.hadoop.security.authentication.server.AuthenticationFilter

All Implemented Interfaces:
  javax.servlet.Filter

    public class AuthenticationFilter

extends Object
implements javax.servlet.Filter

The `AuthenticationFilter` enables protecting web application resources with different (pluggable) authentication mechanisms.

Out of the box it provides 2 authentication mechanisms: Pseudo and Kerberos SPNEGO.

Additional authentication mechanisms are supported via the `AuthenticationHandler` interface.

This filter delegates to the configured authentication handler for authentication and once it obtains an `AuthenticationToken` from it, sets a signed HTTP cookie with the token. For client requests that provide the signed HTTP cookie, it verifies the validity of the cookie, extracts the user information and lets the request proceed to the target resource.

The supported configuration properties are:

- config.prefix: indicates the prefix to be used by all other configuration properties, the default value is no prefix. See below for details on how/why this prefix is used.
- [#PREFIX#.]type: simple|kerberos|#CLASS#, 'simple' is short for the `PseudoAuthenticationHandler`, 'kerberos' is short for `KerberosAuthenticationHandler`, otherwise the full class name of the `AuthenticationHandler` must be specified.
- [#PREFIX#.]signature.secret: the secret used to sign the HTTP cookie value. The default value is a random value. Unless multiple webapp instances need to share the secret the random value is adequate.
- [#PREFIX#.]token.validity: time -in seconds- that the generated token is valid before a new authentication is triggered, default value is `3600` seconds.
- [#PREFIX#.]cookie.domain: domain to use for the HTTP cookie that stores the authentication token.
- [#PREFIX#.]cookie.path: path to use for the HTTP cookie that stores the authentication token.

The rest of the configuration properties are specific to the `AuthenticationHandler` implementation and the `AuthenticationFilter` will take all the properties that start with the prefix #PREFIX#, it will remove the prefix from it and it will pass them to the the authentication handler for initialization. Properties that do not start with the prefix will not be passed to the authentication handler initialization.

Field Summary
`static String` `AUTH_TOKEN_VALIDITY` Constant for the configuration property that indicates the validity of the generated token.
`static String` `AUTH_TYPE` Constant for the property that specifies the authentication handler to use.
`static String` `CONFIG_PREFIX` Constant for the property that specifies the configuration prefix.
`static String` `COOKIE_DOMAIN` Constant for the configuration property that indicates the domain to use in the HTTP cookie.
`static String` `COOKIE_PATH` Constant for the configuration property that indicates the path to use in the HTTP cookie.
`static String` `SIGNATURE_SECRET` Constant for the property that specifies the secret to use for signing the HTTP Cookies.

Constructor Summary
`AuthenticationFilter()`

Method Summary
`protected javax.servlet.http.Cookie` `createCookie(String token)` Creates the Hadoop authentiation HTTP cookie.
`void` `destroy()` Destroys the filter.
`void` `doFilter(javax.servlet.ServletRequest request, javax.servlet.ServletResponse response, javax.servlet.FilterChain filterChain)` If the request has a valid authentication token it allows the request to continue to the target resource, otherwise it triggers an authentication sequence using the configured `AuthenticationHandler`.
`protected AuthenticationHandler` `getAuthenticationHandler()` Returns the authentication handler being used.
`protected Properties` `getConfiguration(String configPrefix, javax.servlet.FilterConfig filterConfig)` Returns the filtered configuration (only properties starting with the specified prefix).
`protected String` `getCookieDomain()` Returns the cookie domain to use for the HTTP cookie.
`protected String` `getCookiePath()` Returns the cookie path to use for the HTTP cookie.
`protected String` `getRequestURL(javax.servlet.http.HttpServletRequest request)` Returns the full URL of the request including the query string.
`protected AuthenticationToken` `getToken(javax.servlet.http.HttpServletRequest request)` Returns the `AuthenticationToken` for the request.
`protected long` `getValidity()` Returns the validity time of the generated tokens.
`void` `init(javax.servlet.FilterConfig filterConfig)` Initializes the authentication filter.
`protected boolean` `isRandomSecret()` Returns if a random secret is being used.

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

Field Detail

### CONFIG_PREFIX

    public static final String CONFIG_PREFIX

  Constant for the property that specifies the configuration prefix.

  See Also:
    Constant Field Values

### AUTH_TYPE

    public static final String AUTH_TYPE

  Constant for the property that specifies the authentication handler to use.

  See Also:
    Constant Field Values

### SIGNATURE_SECRET

    public static final String SIGNATURE_SECRET

  Constant for the property that specifies the secret to use for signing the HTTP Cookies.

  See Also:
    Constant Field Values

### AUTH_TOKEN_VALIDITY

    public static final String AUTH_TOKEN_VALIDITY

  Constant for the configuration property that indicates the validity of the generated token.

  See Also:
    Constant Field Values

### COOKIE_DOMAIN

    public static final String COOKIE_DOMAIN

  Constant for the configuration property that indicates the domain to use in the HTTP cookie.

  See Also:
    Constant Field Values

### COOKIE_PATH

    public static final String COOKIE_PATH

  Constant for the configuration property that indicates the path to use in the HTTP cookie.

  See Also:
    Constant Field Values

Constructor Detail

### AuthenticationFilter

    public AuthenticationFilter()

Method Detail

### init

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

  Initializes the authentication filter.

  It instantiates and initializes the specified `AuthenticationHandler`.

  Specified by:
    `init` in interface `javax.servlet.Filter`
  Parameters:
    `filterConfig` - filter configuration.
  Throws:
    `javax.servlet.ServletException` - thrown if the filter or the authentication handler could not be initialized properly.

### getAuthenticationHandler

    protected AuthenticationHandler getAuthenticationHandler()

  Returns the authentication handler being used.

  Returns:
    the authentication handler being used.

### isRandomSecret

    protected boolean isRandomSecret()

  Returns if a random secret is being used.

  Returns:
    if a random secret is being used.

### getValidity

    protected long getValidity()

  Returns the validity time of the generated tokens.

  Returns:
    the validity time of the generated tokens, in seconds.

### getCookieDomain

    protected String getCookieDomain()

  Returns the cookie domain to use for the HTTP cookie.

  Returns:
    the cookie domain to use for the HTTP cookie.

### getCookiePath

    protected String getCookiePath()

  Returns the cookie path to use for the HTTP cookie.

  Returns:
    the cookie path to use for the HTTP cookie.

### destroy

    public void destroy()

  Destroys the filter.

  It invokes the `AuthenticationHandler.destroy()` method to release any resources it may hold.

  Specified by:
    `destroy` in interface `javax.servlet.Filter`

### getConfiguration

    protected Properties getConfiguration(String configPrefix,
                                          javax.servlet.FilterConfig filterConfig)
                                   throws javax.servlet.ServletException

  Returns the filtered configuration (only properties starting with the specified prefix). The property keys are also trimmed from the prefix. The returned `Properties` object is used to initialized the `AuthenticationHandler`.

  This method can be overriden by subclasses to obtain the configuration from other configuration source than the web.xml file.

  Parameters:
    `configPrefix` - configuration prefix to use for extracting configuration properties.
    `filterConfig` - filter configuration object
  Returns:
    the configuration to be used with the `AuthenticationHandler` instance.
  Throws:
    `javax.servlet.ServletException` - thrown if the configuration could not be created.

### getRequestURL

    protected String getRequestURL(javax.servlet.http.HttpServletRequest request)

  Returns the full URL of the request including the query string.

  Used as a convenience method for logging purposes.

  Parameters:
    `request` - the request object.
  Returns:
    the full URL of the request including the query string.

### getToken

    protected AuthenticationToken getToken(javax.servlet.http.HttpServletRequest request)
                                    throws IOException,
                                           AuthenticationException

  Returns the `AuthenticationToken` for the request.

  It looks at the received HTTP cookies and extracts the value of the `AuthenticatedURL.AUTH_COOKIE` if present. It verifies the signature and if correct it creates the `AuthenticationToken` and returns it.

  If this method returns `null` the filter will invoke the configured `AuthenticationHandler` to perform user authentication.

  Parameters:
    `request` - request object.
  Returns:
    the Authentication token if the request is authenticated, `null` otherwise.
  Throws:
    `IOException` - thrown if an IO error occurred.
    `AuthenticationException` - thrown if the token is invalid or if it has expired.

### doFilter

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

  If the request has a valid authentication token it allows the request to continue to the target resource, otherwise it triggers an authentication sequence using the configured `AuthenticationHandler`.

  Specified by:
    `doFilter` in interface `javax.servlet.Filter`
  Parameters:
    `request` - the request object.
    `response` - the response object.
    `filterChain` - the filter chain object.
  Throws:
    `IOException` - thrown if an IO error occurred.
    `javax.servlet.ServletException` - thrown if a processing error occurred.

### createCookie

    protected javax.servlet.http.Cookie createCookie(String token)

  Creates the Hadoop authentiation HTTP cookie.

  It sets the domain and path specified in the configuration.

  Parameters:
    `token` - authentication token for the cookie.
  Returns:
    the HTTP cookie.

Copyright © 2009 The Apache Software Foundation