blackboard.platform.security.authentication
Class BaseAuthenticationModule

java.lang.Object
  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