blackboard.platform.security.authentication
Class BaseAuthenticationModule

java.lang.Object
  extended by blackboard.platform.security.authentication.BaseAuthenticationModule
All Implemented Interfaces:
HttpAuthModule
Direct Known Subclasses:
LDAPAuthModule

public class BaseAuthenticationModule
extends java.lang.Object
implements HttpAuthModule

Implementation class for the default authentication provider for Blackboard Learning System, also known as RDBMS Authentication. This class can be used as the base class for implementations that will use the Blackboard database as the user directory.

Since:
Bb 6.3

Nested Class Summary
static class BaseAuthenticationModule.ValidationSucceeded
          Results of password validation.
 
Field Summary
protected  HttpAuthConfig _config
          Member variable used to access HttpAuthConfig information.
protected  LogService _logger
          Member variable to write log message to the LogService.
static java.lang.String IMPL_CLASS_KEY
          Used internally by this module.
static java.lang.String USE_CHALLENGE_KEY
          Used internally by this module.
 
Constructor Summary
BaseAuthenticationModule()
          Simple default constructor.
 
Method Summary
protected  void assertRequestAuthenticate()
          Wrapper for any assertions that should be made before authentication request.
protected  java.lang.String authenticate(java.lang.String userName, java.lang.String userToken, SessionStub sessionStub, boolean useChallenge)
          Method to support native authentication.
protected  java.lang.String authenticate(java.lang.String userName, java.lang.String userToken, SessionStub sessionStub, boolean useChallenge, boolean isSecondary)
          Method to support native authentication.
 java.lang.String doAuthenticate(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response)
          Performs the work of authentication.
protected  java.lang.String doAuthenticate(java.util.Map<java.lang.String,java.lang.String> authenticateParams, SessionStub sessionStub, boolean useChallenge)
          Implementation specific version of doAuthenticate which does additional checking before calling authenticate.
protected  java.lang.String doAuthenticate(java.util.Map<java.lang.String,java.lang.String> authenticateParams, SessionStub sessionStub, boolean useChallenge, boolean isSecondary)
          Implementation specific version of doAuthenticate which does additional checking before calling authenticate.
 void doLogout(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response)
          Implementation method.
 void establishSession(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response, java.lang.String userName)
          Creates and associates an AS session with provided user information.
 java.lang.String getAuthType()
          Returns a String identifier for the authentication type for a given implementation of HttpAuthModule
protected  blackboard.platform.intl.BbResourceBundle getBundle()
           
protected  java.lang.String getConfigErrs()
          Collects errors from loading configuration properties for this authentication type.
 boolean getCreateAccountAllowed(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response)
          getCreateAccountAllowed() Determines based on configuration information, whether users may create new accounts.
static java.lang.String getDefaultAuthType()
          Return the default authentication type
protected  java.util.Map<java.lang.String,java.lang.String> getDoAuthenticateParams(javax.servlet.http.HttpServletRequest request)
          Gets the authentication parameters from the request object.
 java.lang.String[] getPropKeys()
          Returns a String array of the keys to this authentication module's configuration properties file.
protected  java.lang.String getRequestAuthenticateUri(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response)
          getRequestAuthenticateURI Indicates the target resource that should receive the current request.
protected  java.util.Map<java.lang.String,java.lang.String> getSecondaryDoAuthenticateParams(javax.servlet.http.HttpServletRequest request)
          Gets the authentication parameters from the request object.
protected  java.lang.String getSubConfigErrs()
          Collects errors from loading nested configuration properties for this authentication type.
 boolean getUseChallenge()
          Determines based on configuration information, whether to use challenge-response authentication.
 void init(ConfigurationService cfg)
          Initializes authentication module.
 boolean isExternalAuth()
          Can be used by subclasses to determine whether or not the authentication module is an external authentication module.
 void requestAuthenticate(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response)
          Implementation method.
protected static void setAuthTypeDisplayStr(java.lang.String authTypeDisplayStr)
           
 void setConfig(HttpAuthConfig config)
          Sets the configuration properties for this authentication type.
protected  void setGlobalKeys(javax.servlet.http.HttpServletRequest request)
          Set whatever key-value pairs need to be stored for the current session.
 boolean suppressFirstLoadError(javax.servlet.http.HttpServletRequest request)
          Used to determine if page "hit" is considered an intial load.
protected  void validateConfig()
          Validates that the configuration properties for this authentication type have been loaded correctly.
protected  BaseAuthenticationModule.ValidationSucceeded validatePassword(java.lang.String userToken, java.lang.String dbUserPass, boolean useChallenge, SessionStub sessionStub)
          Validates password.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

IMPL_CLASS_KEY

public static final java.lang.String IMPL_CLASS_KEY
Used internally by this module.

See Also:
Constant Field Values

USE_CHALLENGE_KEY

public static final java.lang.String USE_CHALLENGE_KEY
Used internally by this module.

See Also:
Constant Field Values

_logger

protected LogService _logger
Member variable to write log message to the LogService. Can be used by subclasses that need to write log messages.


_config

protected HttpAuthConfig _config
Member variable used to access HttpAuthConfig information. Can be used by subclasses that need information from this object.

Constructor Detail

BaseAuthenticationModule

public BaseAuthenticationModule()
Simple default constructor. This constructor must be public because HttpAuthManager calls Class.newInstance().

Method Detail

getBundle

protected blackboard.platform.intl.BbResourceBundle getBundle()

setAuthTypeDisplayStr

protected static void setAuthTypeDisplayStr(java.lang.String authTypeDisplayStr)

init

public void init(ConfigurationService cfg)
Initializes authentication module.

Specified by:
init in interface HttpAuthModule
Parameters:
cfg - The ConfigurationService for this installation.

setConfig

public void setConfig(HttpAuthConfig config)
Sets the configuration properties for this authentication type.

Specified by:
setConfig in interface HttpAuthModule
Parameters:
config - The HttpAuthConfig object containing all authentication properties for this authentication type.

validateConfig

protected void validateConfig()
                       throws blackboard.platform.security.authentication.BbInsufficientArgs
Validates that the configuration properties for this authentication type have been loaded correctly.

Throws:
blackboard.platform.security.authentication.BbInsufficientArgs

getConfigErrs

protected java.lang.String getConfigErrs()
Collects errors from loading configuration properties for this authentication type.


getSubConfigErrs

protected java.lang.String getSubConfigErrs()
Collects errors from loading nested configuration properties for this authentication type.


getPropKeys

public java.lang.String[] getPropKeys()
Returns a String array of the keys to this authentication module's configuration properties file.

Specified by:
getPropKeys in interface HttpAuthModule

isExternalAuth

public boolean isExternalAuth()
Can be used by subclasses to determine whether or not the authentication module is an external authentication module. This implementation returns false.


doAuthenticate

public java.lang.String doAuthenticate(javax.servlet.http.HttpServletRequest request,
                                       javax.servlet.http.HttpServletResponse response)
                                throws BbSecurityException,
                                       BbAuthenticationFailedException,
                                       BbCredentialsNotFoundException
Performs the work of authentication. Parses the Authorization string out of the request, calls doAuthenticate(Map, SessionStub, boolean) which submits username and password to the authenticate method.

Specified by:
doAuthenticate in interface HttpAuthModule
Parameters:
request - the request containing auth credentials
response - the response object associated with the current HTTP transaction. This object is not used in this implementation
Returns:
Current user key
Throws:
BbSecurityException - thrown if an external error prevents authentication from occurring.
BbAuthenticationFailedException - thrown if authentication failed (i.e., wrong password)
BbCredentialsNotFoundException - thrown if no credentials were found in the request

doAuthenticate

protected java.lang.String doAuthenticate(java.util.Map<java.lang.String,java.lang.String> authenticateParams,
                                          SessionStub sessionStub,
                                          boolean useChallenge)
                                   throws BbSecurityException,
                                          BbAuthenticationFailedException,
                                          BbCredentialsNotFoundException
Implementation specific version of doAuthenticate which does additional checking before calling authenticate.

Parameters:
authenticateParams - -- a Map of request parameter names and values
sessionStub - -- Session information
useChallenge - -- boolean to signify whether or not authentication is configured for challenge-response
Throws:
BbSecurityException
BbAuthenticationFailedException
BbCredentialsNotFoundException

doAuthenticate

protected java.lang.String doAuthenticate(java.util.Map<java.lang.String,java.lang.String> authenticateParams,
                                          SessionStub sessionStub,
                                          boolean useChallenge,
                                          boolean isSecondary)
                                   throws BbSecurityException,
                                          BbAuthenticationFailedException,
                                          BbCredentialsNotFoundException
Implementation specific version of doAuthenticate which does additional checking before calling authenticate.

Parameters:
authenticateParams - -- a Map of request parameter names and values
sessionStub - -- Session information
useChallenge - -- boolean to signify whether or not authentication is configured for challenge-response
isSecondary - -- whether this is the second attempt; used to handle non-Unicode encoded passwords
Throws:
BbSecurityException
BbAuthenticationFailedException
BbCredentialsNotFoundException

getDoAuthenticateParams

protected java.util.Map<java.lang.String,java.lang.String> getDoAuthenticateParams(javax.servlet.http.HttpServletRequest request)
Gets the authentication parameters from the request object.

Returns:
Map Returns authenticate parameters, extracted from the request object.

getSecondaryDoAuthenticateParams

protected java.util.Map<java.lang.String,java.lang.String> getSecondaryDoAuthenticateParams(javax.servlet.http.HttpServletRequest request)
Gets the authentication parameters from the request object.

Returns:
Map Returns authenticate parameters, extracted from the request object.

requestAuthenticate

public void requestAuthenticate(javax.servlet.http.HttpServletRequest request,
                                javax.servlet.http.HttpServletResponse response)
                         throws BbSecurityException
Implementation method. Stores the requested URL in session for the login JSP to forward. The request is typically redirected to the URI /webapps/login/login.jsp.

Specified by:
requestAuthenticate in interface HttpAuthModule
Parameters:
request - The current HTTP request object. Used to get the session object
response - The response on which to set SC_UNAUTHORIZED
Throws:
BbSecurityException - thrown if a run-time error prevents the method from completing.
See Also:
HttpServletResponse.SC_UNAUTHORIZED

assertRequestAuthenticate

protected void assertRequestAuthenticate()
                                  throws BbSecurityException
Wrapper for any assertions that should be made before authentication request. Checks to make sure the configuration has been set.

Throws:
BbSecurityException - if the configuration has not been set

getRequestAuthenticateUri

protected java.lang.String getRequestAuthenticateUri(javax.servlet.http.HttpServletRequest request,
                                                     javax.servlet.http.HttpServletResponse response)
                                              throws java.io.IOException,
                                                     java.lang.SecurityException,
                                                     java.io.FileNotFoundException,
                                                     PersistenceException
getRequestAuthenticateURI Indicates the target resource that should receive the current request. This implementation returns the default login URI for the installation.

Throws:
java.io.IOException
java.lang.SecurityException
java.io.FileNotFoundException
PersistenceException

doLogout

public void doLogout(javax.servlet.http.HttpServletRequest request,
                     javax.servlet.http.HttpServletResponse response)
              throws BbSecurityException
Implementation method. Clears the authentication token from the session.

Specified by:
doLogout in interface HttpAuthModule
Parameters:
request - the current HTTP request. Used to obtain a session handle.
response - the current HTTP response. Passed for completeness, not used.
Throws:
BbSecurityException - included for completeness. --This implementation will never throw this exception

authenticate

protected java.lang.String authenticate(java.lang.String userName,
                                        java.lang.String userToken,
                                        SessionStub sessionStub,
                                        boolean useChallenge)
                                 throws BbAuthenticationFailedException,
                                        BbSecurityException
Method to support native authentication. Uses credentials to look up a user's key in the database. If the system is configured to use the challenge-response protocol, the password provided by the caller is expected to be a hexadecimal string representing the message digest of the string M(M(password) + server token) where M is the hashing algorithm (MD5), password is the clear text password entered by the user, and server token is a digested string generated as a pseudo-random server variable. The comparison is done by taking all of the corresponding values stored on the server and re-generating the string. If the hashed version from the client matches the version calcualated by the server, the login is successful.

If challenge-response is not used, the processing is greatly simplified: the password is in clear text. The method digests it and compares it against the hashed value stored in the database.

Parameters:
userName - User name
userToken - this should be either clear text password or hash, depending on the result from RDBMSAuthUtil.useChallenge().
Returns:
User key used to load user.
Throws:
BbAuthenticationFailedException
BbSecurityException

authenticate

protected java.lang.String authenticate(java.lang.String userName,
                                        java.lang.String userToken,
                                        SessionStub sessionStub,
                                        boolean useChallenge,
                                        boolean isSecondary)
                                 throws BbAuthenticationFailedException,
                                        BbSecurityException
Method to support native authentication. Uses credentials to look up a user's key in the database. If the system is configured to use the challenge-response protocol, the password provided by the caller is expected to be a hexadecimal string representing the message digest of the string M(M(password) + server token) where M is the hashing algorithm (MD5), password is the clear text password entered by the user, and server token is a digested string generated as a pseudo-random server variable. The comparison is done by taking all of the corresponding values stored on the server and re-generating the string. If the hashed version from the client matches the version calcualated by the server, the login is successful.

If challenge-response is not used, the processing is greatly simplified: the password is in clear text. The method digests it and compares it against the hashed value stored in the database.

Parameters:
userName - User name
userToken - this should be either clear text password or hash, depending on the result from RDBMSAuthUtil.useChallenge().
Returns:
User key used to load user.
Throws:
BbAuthenticationFailedException
BbSecurityException

validatePassword

protected BaseAuthenticationModule.ValidationSucceeded validatePassword(java.lang.String userToken,
                                                                        java.lang.String dbUserPass,
                                                                        boolean useChallenge,
                                                                        SessionStub sessionStub)
                                                                 throws BbAuthenticationFailedException
Validates password.

Parameters:
userToken - Password provided by client
dbUserPass - Hashed database password
useChallenge - Use challenge-response mechanism to validate login
sessionStub - Session information (only needed when useChallenge is true)
Returns:
ValidationSucceeded object if password is valid
Throws:
BbAuthenticationFailedException - if password is not valid

getCreateAccountAllowed

public boolean getCreateAccountAllowed(javax.servlet.http.HttpServletRequest request,
                                       javax.servlet.http.HttpServletResponse response)
getCreateAccountAllowed() Determines based on configuration information, whether users may create new accounts.


getUseChallenge

public boolean getUseChallenge()
Determines based on configuration information, whether to use challenge-response authentication.


getAuthType

public java.lang.String getAuthType()
Returns a String identifier for the authentication type for a given implementation of HttpAuthModule

Specified by:
getAuthType in interface HttpAuthModule

getDefaultAuthType

public static java.lang.String getDefaultAuthType()
Return the default authentication type


suppressFirstLoadError

public boolean suppressFirstLoadError(javax.servlet.http.HttpServletRequest request)
Used to determine if page "hit" is considered an intial load. There is a potential "invalid credentials" error the first time that the page is presented. This handles the specific to workflow in place with the HttpAuthModule implementation.

Specified by:
suppressFirstLoadError in interface HttpAuthModule

setGlobalKeys

protected void setGlobalKeys(javax.servlet.http.HttpServletRequest request)
                      throws PersistenceException
Set whatever key-value pairs need to be stored for the current session. Subclasses should override this method only if needed. This module provides a null implementation of this method.

Throws:
PersistenceException

establishSession

public final void establishSession(javax.servlet.http.HttpServletRequest request,
                                   javax.servlet.http.HttpServletResponse response,
                                   java.lang.String userName)
                            throws BbSecurityException
Creates and associates an AS session with provided user information. This method cannot not be overriden by any sub-classes. It is meant primarily to be invoked by classes providing support for sessions for integrated users

Throws:
BbSecurityException


Copyright 2011 Blackboard, Inc. All Rights Reserved.