AuthenticationFilter (common-auth 1.0.0 API)

java.lang.Object
- com.hortonworks.registries.auth.server.AuthenticationFilter

All Implemented Interfaces:

javax.servlet.Filter

Direct Known Subclasses:

AuthTerminatorFilter
```
public class AuthenticationFilter
extends java.lang.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.file: when signer.secret.provider is set to "file" or not specified, this is the location of file including 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 36000 seconds. This is also used for the rollover interval for the "random" SignerSecretProvider.
- [#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 2 signer secret provider implementations: "file" and "random"
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 "file" implementation loads the secret from a specified file. The "random" implementation uses a randomly generated secret that rolls over at the interval specified by the [#PREFIX#.]token.validity mentioned above.
The relevant configuration properties are:
- signer.secret.provider: indicates the name of the SignerSecretProvider class to use. Possible values are: "file", "random", or a classname. If not specified, the "file" implementation will be used with [#PREFIX#.]signature.secret.file; and if that's not specified, the "random" implementation will be used.
- [#PREFIX#.]signature.secret.file: When the "file" implementation is specified, this content of this file is used as the secret.
- [#PREFIX#.]token.validity: When the "random" implementation is specified, this value is used as the rollover interval.
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

Fields
Modifier and Type	Field and Description
`static java.lang.String`	`ALLOWED_RESOURCES` Constant for the configuration property that indicates the resources to skip this filter for e.g.
`protected static java.lang.String`	`AUTH_FAILED` In case of composite filters, we will pass the state to the next filter.
`static java.lang.String`	`AUTH_TOKEN_VALIDITY` Constant for the configuration property that indicates the validity of the generated token.
`static java.lang.String`	`AUTH_TYPE` Constant for the property that specifies the authentication handler to use.
`static java.lang.String`	`CONFIG_PREFIX` Constant for the property that specifies the configuration prefix.
`static java.lang.String`	`COOKIE_DOMAIN` Constant for the configuration property that indicates the domain to use in the HTTP cookie.
`static java.lang.String`	`COOKIE_PATH` Constant for the configuration property that indicates the path to use in the HTTP cookie.
`static java.lang.String`	`IS_COMPOSITE` If true then the filter will expect there to be multiple filters in the line.
`static java.lang.String`	`SIGNATURE_SECRET` Constant for the property that specifies the secret to use for signing the HTTP Cookies.
`static java.lang.String`	`SIGNATURE_SECRET_FILE`
`static java.lang.String`	`SIGNER_SECRET_PROVIDER` Constant for the configuration property that indicates the name of the SignerSecretProvider class to use.
`static java.lang.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()

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, java.util.Properties config, boolean disallowFallbackToRandomSecretProvider)`
`static void`	`createAuthCookie(javax.servlet.http.HttpServletResponse resp, java.lang.String token, java.lang.String domain, java.lang.String path, long expires, boolean isSecure)` Creates the authentication 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 java.util.Properties`	`getConfiguration()` Returns the configuration properties of the `AuthenticationFilter` without the prefix.
`protected java.util.Properties`	`getConfiguration(java.lang.String configPrefix, javax.servlet.FilterConfig filterConfig)` Returns the filtered configuration (only properties starting with the specified prefix).
`protected java.lang.String`	`getCookieDomain()` Returns the cookie domain to use for the HTTP cookie.
`protected java.lang.String`	`getCookiePath()` Returns the cookie path to use for the HTTP cookie.
`protected java.lang.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(java.lang.String authHandlerClassName)`
`protected void`	`initializeSecretProvider(javax.servlet.FilterConfig filterConfig)`
`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 void`	`proceedToNextFilter(javax.servlet.FilterChain filterChain, javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response)` Delegates call to the servlet filter chain.
`protected void`	`respondWithUnauthorized(javax.servlet.ServletRequest request, javax.servlet.http.HttpServletResponse httpResponse, int errCode, AuthenticationException authenticationEx)`

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 java.lang.String CONFIG_PREFIX
```
    Constant for the property that specifies the configuration prefix.
    
    See Also:
    
    Constant Field Values
  - AUTH_TYPE
```
public static final java.lang.String AUTH_TYPE
```
    Constant for the property that specifies the authentication handler to use.
    
    See Also:
    
    Constant Field Values
  - IS_COMPOSITE
```
public static final java.lang.String IS_COMPOSITE
```
    If true then the filter will expect there to be multiple filters in the line. Instead of terminating the response in case of error, it will just pass to the next filter.
    
    See Also:
    
    Constant Field Values
  - SIGNATURE_SECRET
```
public static final java.lang.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 java.lang.String SIGNATURE_SECRET_FILE
```
    See Also:
    
    Constant Field Values
  - AUTH_TOKEN_VALIDITY
```
public static final java.lang.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 java.lang.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 java.lang.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 java.lang.String SIGNER_SECRET_PROVIDER
```
    Constant for the configuration property that indicates the name of the SignerSecretProvider class to use. Possible values are: "file", "random" 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 java.lang.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
  - ALLOWED_RESOURCES
```
public static final java.lang.String ALLOWED_RESOURCES
```
    Constant for the configuration property that indicates the resources to skip this filter for e.g. "abc.html, icon.png" to skip specific resources e.g. ".html, .png" to skip all html and png resources
    
    See Also:
    
    Constant Field Values
  - AUTH_FAILED
```
protected static final java.lang.String AUTH_FAILED
```
    In case of composite filters, we will pass the state to the next filter.
    
    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(java.lang.String authHandlerClassName)
                              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,
                                                           java.util.Properties config,
                                                           boolean disallowFallbackToRandomSecretProvider)
                                                    throws java.lang.Exception
```
    Throws:
    
    java.lang.Exception
  - getConfiguration
```
protected java.util.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 java.lang.String getCookieDomain()
```
    Returns the cookie domain to use for the HTTP cookie.
    
    Returns:
    
    the cookie domain to use for the HTTP cookie.
  - getCookiePath
```
protected java.lang.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 java.util.Properties getConfiguration(java.lang.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 java.lang.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 java.io.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:
    
    java.io.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 java.io.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:
    
    java.io.IOException - thrown if an IO error occurred.
    
    javax.servlet.ServletException - thrown if a processing error occurred.
  - respondWithUnauthorized
```
protected void respondWithUnauthorized(javax.servlet.ServletRequest request,
                                       javax.servlet.http.HttpServletResponse httpResponse,
                                       int errCode,
                                       AuthenticationException authenticationEx)
                                throws java.io.IOException
```
    Throws:
    
    java.io.IOException
  - proceedToNextFilter
```
protected void proceedToNextFilter(javax.servlet.FilterChain filterChain,
                                   javax.servlet.http.HttpServletRequest request,
                                   javax.servlet.http.HttpServletResponse response)
                            throws java.io.IOException,
                                   javax.servlet.ServletException
```
    Delegates call to the servlet filter chain. Sub-classes my override this method to perform pre and post tasks.
    
    Throws:
    
    java.io.IOException
    
    javax.servlet.ServletException
  - createAuthCookie
```
public static void createAuthCookie(javax.servlet.http.HttpServletResponse resp,
                                    java.lang.String token,
                                    java.lang.String domain,
                                    java.lang.String path,
                                    long expires,
                                    boolean isSecure)
```
    Creates the 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.

Class AuthenticationFilter

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

CONFIG_PREFIX

AUTH_TYPE

IS_COMPOSITE

SIGNATURE_SECRET

SIGNATURE_SECRET_FILE

AUTH_TOKEN_VALIDITY

COOKIE_DOMAIN

COOKIE_PATH

SIGNER_SECRET_PROVIDER

SIGNER_SECRET_PROVIDER_ATTRIBUTE

ALLOWED_RESOURCES

AUTH_FAILED

Constructor Detail

AuthenticationFilter

Method Detail

init

initializeAuthHandler

initializeSecretProvider

constructSecretProvider

getConfiguration

getAuthenticationHandler

isRandomSecret

isCustomSignerSecretProvider

getValidity

getCookieDomain

getCookiePath

destroy

getConfiguration

getRequestURL

getToken

doFilter

respondWithUnauthorized

proceedToNextFilter

createAuthCookie