org.apache.hadoop.security.authentication.server

## Class AuthenticationFilter

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

- All Implemented Interfaces:
    javax.servlet.Filter

      @InterfaceAudience.Private
       @InterfaceStability.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 and Description
    --- | ---
    `static String` | `AUTH_TOKEN_MAX_INACTIVE_INTERVAL` Constant for the configuration property that indicates the max inactive interval of the generated token.
    `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` | `COOKIE_PERSISTENT` Constant for the configuration property that indicates the persistence of the HTTP cookie.
    `static String` | `SIGNATURE_SECRET` Constant for the property that specifies the secret to use for signing the HTTP Cookies.
    `static String` | `SIGNATURE_SECRET_FILE`
    `static String` | `SIGNER_SECRET_PROVIDER` Constant for the configuration property that indicates the name of the SignerSecretProvider class to use.
    `static 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 and Description
    `AuthenticationFilter()`

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and 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 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

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

    - #### AuthenticationFilter

          public AuthenticationFilter()

  - ### Method Detail

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

Copyright © 2008–2022 Apache Software Foundation. All rights reserved.