AuthenticationFilter (Apache Hadoop Auth 3.5.0 API)
Description: declaration: package: org.apache.hadoop.security.authentication.server, class: AuthenticationFilter

Package org.apache.hadoop.security.authentication.server

# Class AuthenticationFilter

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

All Implemented Interfaces:
  `javax.servlet.Filter`

@Private @Unstable public class AuthenticationFilter extends Object implements javax.servlet.Filter
The `AuthenticationFilter` enables protecting web application resources with different (pluggable) authentication mechanisms and signer secret providers.

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

Details of the configurations are listed on Configuration Page

The "zookeeper" implementation has additional configuration properties that must be specified; see `ZKSignerSecretProvider` for details.

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final String`
  `AUTH_TOKEN_MAX_INACTIVE_INTERVAL`
  Constant for the configuration property that indicates the max inactive interval of the generated token.
  `static final String`
  `AUTH_TOKEN_VALIDITY`
  Constant for the configuration property that indicates the validity of the generated token.
  `static final String`
  `AUTH_TYPE`
  Constant for the property that specifies the authentication handler to use.
  `static final String`
  `CONFIG_PREFIX`
  Constant for the property that specifies the configuration prefix.
  `static final String`
  `COOKIE_DOMAIN`
  Constant for the configuration property that indicates the domain to use in the HTTP cookie.
  `static final String`
  `COOKIE_PATH`
  Constant for the configuration property that indicates the path to use in the HTTP cookie.
  `static final String`
  `COOKIE_PERSISTENT`
  Constant for the configuration property that indicates the persistence of the HTTP cookie.
  `static final String`
  `SIGNATURE_SECRET`
  Constant for the property that specifies the secret to use for signing the HTTP Cookies.
  `static final String`
  `SIGNATURE_SECRET_FILE`
  `static final String`
  `SIGNER_SECRET_PROVIDER`
  Constant for the configuration property that indicates the name of the SignerSecretProvider class to use.
  `static final String`
  `SIGNER_SECRET_PROVIDER_ATTRIBUTE`
  Constant for the ServletContext attribute that can be used for providing a custom implementation of the SignerSecretProvider.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `AuthenticationFilter()`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static SignerSecretProvider`
  `constructSecretProvider(javax.servlet.ServletContext ctx, Properties config, boolean disallowFallbackToRandomSecretProvider)`
  `static void`
  `createAuthCookie(javax.servlet.http.HttpServletResponse resp, String token, String domain, String path, long expires, boolean isCookiePersistent, boolean isSecure)`
  Creates the Hadoop authentication HTTP cookie.
  `void`
  `destroy()`
  Destroys the filter.
  `protected void`
  `doFilter(javax.servlet.FilterChain filterChain, javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response)`
  Delegates call to the servlet filter chain.
  `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()`
  Returns the configuration properties of the `AuthenticationFilter` without the prefix.
  `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 long`
  `getMaxInactiveInterval()`
  Returns the max inactive interval time of the generated tokens.
  `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 and signer secret provider.
  `protected void`
  `initializeAuthHandler(String authHandlerClassName, javax.servlet.FilterConfig filterConfig)`
  `protected void`
  `initializeSecretProvider(javax.servlet.FilterConfig filterConfig)`
  `protected boolean`
  `isCookiePersistent()`
  Returns the cookie persistence to use for the HTTP cookie.
  `protected boolean`
  `isCustomSignerSecretProvider()`
  Returns if a custom implementation of a SignerSecretProvider is being used.
  `protected boolean`
  `isRandomSecret()`
  Returns if a random secret is being used.
  `protected boolean`
  `verifyTokenType(AuthenticationHandler handler, AuthenticationToken token)`
  This method verifies if the specified token type matches one of the the token types supported by a specified `AuthenticationHandler`.

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

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

- ## Field Details

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

  - ### SIGNATURE_SECRET_FILE

    public static final String SIGNATURE_SECRET_FILE
    See Also:
      - Constant Field Values

  - ### AUTH_TOKEN_MAX_INACTIVE_INTERVAL

    public static final String AUTH_TOKEN_MAX_INACTIVE_INTERVAL
    Constant for the configuration property that indicates the max inactive interval of the generated token.
    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

  - ### COOKIE_PERSISTENT

    public static final String COOKIE_PERSISTENT
    Constant for the configuration property that indicates the persistence of the HTTP cookie.
    See Also:
      - Constant Field Values

  - ### SIGNER_SECRET_PROVIDER

    public static final String SIGNER_SECRET_PROVIDER
    Constant for the configuration property that indicates the name of the SignerSecretProvider class to use. Possible values are: "file", "random", "zookeeper", or a classname. If not specified, the "file" implementation will be used with SIGNATURE_SECRET_FILE; and if that's not specified, the "random" implementation will be used.
    See Also:
      - Constant Field Values

  - ### SIGNER_SECRET_PROVIDER_ATTRIBUTE

    public static final String SIGNER_SECRET_PROVIDER_ATTRIBUTE
    Constant for the ServletContext attribute that can be used for providing a custom implementation of the SignerSecretProvider. Note that the class should already be initialized. If not specified, SIGNER_SECRET_PROVIDER will be used.
    See Also:
      - Constant Field Values

- ## Constructor Details

  - ### AuthenticationFilter

    public AuthenticationFilter()

- ## Method Details

  - ### init

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

    Initializes the authentication filter and signer secret provider.

    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.

  - ### initializeAuthHandler

    protected void initializeAuthHandler(String authHandlerClassName, javax.servlet.FilterConfig filterConfig) throws javax.servlet.ServletException
    Throws:
      `javax.servlet.ServletException`

  - ### initializeSecretProvider

    protected void initializeSecretProvider(javax.servlet.FilterConfig filterConfig) throws javax.servlet.ServletException
    Throws:
      `javax.servlet.ServletException`

  - ### constructSecretProvider

    public static SignerSecretProvider constructSecretProvider(javax.servlet.ServletContext ctx, Properties config, boolean disallowFallbackToRandomSecretProvider) throws Exception
    Throws:
      `Exception`

  - ### getConfiguration

    protected Properties getConfiguration()
    Returns the configuration properties of the `AuthenticationFilter` without the prefix. The returned properties are the same that the `getConfiguration(String, FilterConfig)` method returned.
    Returns:
      the configuration properties.

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

  - ### isCustomSignerSecretProvider

    protected boolean isCustomSignerSecretProvider()
    Returns if a custom implementation of a SignerSecretProvider is being used.
    Returns:
      if a custom implementation of a SignerSecretProvider is being used.

  - ### getMaxInactiveInterval

    protected long getMaxInactiveInterval()
    Returns the max inactive interval time of the generated tokens.
    Returns:
      the max inactive interval time of the generated tokens in seconds.

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

  - ### isCookiePersistent

    protected boolean isCookiePersistent()
    Returns the cookie persistence to use for the HTTP cookie.
    Returns:
      the cookie persistence 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.

  - ### verifyTokenType

    protected boolean verifyTokenType(AuthenticationHandler handler, AuthenticationToken token)
    This method verifies if the specified token type matches one of the the token types supported by a specified `AuthenticationHandler`. This method is specifically designed to work with `CompositeAuthenticationHandler` implementation which supports multiple authentication schemes while the `AuthenticationHandler` interface supports a single type via AuthenticationHandler.getType() method.
    Parameters:
      `handler` - The authentication handler whose supported token types should be used for verification.
      `token` - The token whose type needs to be verified.
    Returns:
      true If the token type matches one of the supported token types false Otherwise

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

  - ### doFilter

    protected void doFilter(javax.servlet.FilterChain filterChain, javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response) throws IOException, javax.servlet.ServletException
    Delegates call to the servlet filter chain. Sub-classes my override this method to perform pre and post tasks.
    Parameters:
      `filterChain` - the filter chain object.
      `request` - the request object.
      `response` - the response object.
    Throws:
      `IOException` - thrown if an IO error occurred.
      `javax.servlet.ServletException` - thrown if a processing error occurred.

  - ### createAuthCookie

    public static void createAuthCookie(javax.servlet.http.HttpServletResponse resp, String token, String domain, String path, long expires, boolean isCookiePersistent, boolean isSecure)
    Creates the Hadoop authentication HTTP cookie.
    Parameters:
      `resp` - the response object.
      `token` - authentication token for the cookie.
      `domain` - the cookie domain.
      `path` - the cookie path.
      `expires` - UNIX timestamp that indicates the expire date of the cookie. It has no effect if its value < 0.
      `isSecure` - is the cookie secure?
      `isCookiePersistent` - whether the cookie is persistent or not. XXX the following code duplicate some logic in Jetty / Servlet API, because of the fact that Hadoop is stuck at servlet 2.5 and jetty 6 right now.