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.

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: when signer.secret.provider is set to "string" or not specified, this is the value for the secret used to sign the HTTP cookie.
• [#PREFIX#.]token.validity: time -in seconds- that the generated token is valid before a new authentication is triggered, default value is 3600 seconds. This is also used for the rollover interval for the "random" and "zookeeper" SignerSecretProviders.
• [#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.

Out of the box it provides 3 signer secret provider implementations: "string", "random", and "zookeeper"

Additional signer secret providers are supported via the SignerSecretProvider class.

For the HTTP cookies mentioned above, the SignerSecretProvider is used to determine the secret to use for signing the cookies. Different implementations can have different behaviors. The "string" implementation simply uses the string set in the [#PREFIX#.]signature.secret property mentioned above. The "random" implementation uses a randomly generated secret that rolls over at the interval specified by the [#PREFIX#.]token.validity mentioned above. The "zookeeper" implementation is like the "random" one, except that it synchronizes the random secret and rollovers between multiple servers; it's meant for HA services.

The relevant configuration properties are:

• signer.secret.provider: indicates the name of the SignerSecretProvider class to use. Possible values are: "string", "random", "zookeeper", or a classname. If not specified, the "string" implementation will be used with [#PREFIX#.]signature.secret; and if that's not specified, the "random" implementation will be used.
• [#PREFIX#.]signature.secret: When the "string" implementation is specified, this value is used as the secret.
• [#PREFIX#.]token.validity: When the "random" or "zookeeper" implementations are specified, this value is used as the rollover interval.

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

For subclasses of AuthenticationFilter that want additional control over the SignerSecretProvider, they can use the following attribute set in the ServletContext:

• signer.secret.provider.object: A SignerSecretProvider implementation can be passed here that will be used instead of the signer.secret.provider configuration property. Note that the class should already be initialized.

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

AuthenticationFilter()

Method Summary

static void	createAuthCookie(javax.servlet.http.HttpServletResponse resp, String token, String domain, String path, long expires, 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 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 boolean	isCustomSignerSecretProvider() Returns if a custom implementation of a SignerSecretProvider is being used.
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

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: "string", "random", "zookeeper", or a classname. If not specified, the "string" implementation will be used with SIGNATURE_SECRET; 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.

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.

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.

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.

Throws:

IOException

javax.servlet.ServletException

createAuthCookie

public static void createAuthCookie(javax.servlet.http.HttpServletResponse resp,
                                    String token,
                                    String domain,
                                    String path,
                                    long expires,
                                    boolean isSecure)

Creates the Hadoop authentication HTTP cookie.

Parameters:

token - authentication token for the cookie.

expires - UNIX timestamp that indicates the expire date of the cookie. It has no effect if its value < 0. 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.