{panel:borderStyle=solid|title=Tutorial Contents}
* [Background Information|#BACKGROUND]
* [Installation|#INSTALL]
** [installation details|#INSTALL_DETAILS]
* [Configuration|#CONFIG]
** [configuration details|#CONFIG_DETAILS]
* [Build your own|#BYO]
** [Cascading modules|#CASCADING]
** [Handling Error states|#ERROR_STATES]
** [Gotchas|#BYO-gotchas]
** [Examples|#examples]
{panel}
{column}

{section}
{anchor:BACKGROUND}

h2. Background Information

A common task in Blackboard is to integrate a custom theme. Blackboard supports LDAP, Blackboard Integrated and Shibolleth Authentication out of the box. The community has also developed a number of building blocks for common authentication schemes including:
* [CAS|http://code.google.com/p/blackboard-cas/]
* [Shared Secret|http://projects.oscelot.org/gf/project/sso-in-shared/]

And others (add yours here).

You can also customize the authentication screen using a simple html editing.

{anchor:INSTALL}

h2. Installing and Configuring custom authentication modules


----
{anchor:CONFIG_DETAILS}

h4. Configuration details
See the blackboard documentation for primary information on how to install and configure custom auth modules.

h4. Other required configuration
As well as updating bb-config.properties, and running PushConfigUpdates.sh push You must also set the path to your custom jar file in other locations.
# _/opt/blackboard/apps/collab-server/collabserverctl.sh_ To ensure the collabserver continues to function.
Add your jar to the list of jars in the classpath in this script.
e.g. Add the line. COLLAB_CLASSPATH="$COLLAB_CLASSPATH:$BASEDIR/systemlib/myauthmodule.jar"
# _/opt/blackboard/system/build/bin/launch-tool.sh_ To ensure command line tools continue to function.
Add your jar to the list of third party jars in this script.
e.g. add the line. THIRD_PARTY_CP=$THIRD_PARTY_CP:myauthmodule.jar
# Sending email from announcements. Check the [knowledge base article|http://kb.blackboard.com/display/KB/Email+Announcement+Feature+Fails+to+Send+an+Email+under+Custom+Authentication]
Read the article and modify the specified Perl Script(s)
{warning:title=Only tested on Blackboard version 8}
These script changes have only been tested on BB 8, and there may be other locations in your installation that require changes.
{warning}

----
{anchor:BYO}

h2. Build your own


----
{anchor:CASCADING}

h3. Cascading modules
The easiest way to get extra functionality in your authentication module is to extend a pre-existing one, though this isn't without its problems.
When extending the BaseAuthenticationModule or the LDAPAuthModule, you can simply use the properties that are already set on those modules to cascade the authentication. That is, if your custom authentication fails, it will try to authenticate the user against LDAP, and if that in turn fails, it will try and authenticate the user against the local database accounts.
{warning:title=Extending the LDAP Module}
If you choose to extend the LDAP module. You Can't change the auth type string. It must remain as "ldap", otherwise blackboard gets confused. Hopefully Blackboard will fix this at some point.
{warning}


----
{anchor:ERROR_STATES}
h3. Checking Login Error States
There are some cases where you want to check the blackboard error states, for example if a user enters the wrong password, the user doesn't exist, or the user is disabled. You can handle these error cases in requestAuthenticate(request, response) \{...\} by checking values in the "msg" request attribute.
Here are a couple of examples.

{code}
// If Password is wrong, redisplay standard login form
if (errMsg != null && errMsg.indexOf("Could not login. Valid authentication credentials were not provided.") != -1) {
super.requestAuthenticate(request, response);
return;
}

//If user doesn't exist. Redirect to a page explaining what's happened.
if (errMsg != null && errMsg.indexOf("Unable to retrieve user record from the database") != -1) {
try {
response.sendRedirect(URL_FOR_ERROR_PAGE);
} catch (Exception e) {
throw new BbSecurityException(e.getMessage());
}
return;
}
{code}


----
{anchor:BYO-gotchas}

h3. Gotchas

If your module isn't behaving the way you expect it to, check these things.
* You *must* implement the getAuthType() method, so that it returns the id of your module. For example, if your module is referenced in bb-config.properties like
{code:title=bb-config.properties|borderStyle=solid}
bbconfig.auth.type=my-module
{code}
your implementation of getAuthType() must return a string with the value "my-module".
* If you are extending BaseAuthenticationModule or LDAPAuthModule, you *must* set the use_challenge property to false. If you set this to true, your module _will not work_
your module's properties in authentication.properties will look something like this.
{code:title=authentication.properties|borderStyle=solid}
auth.type.gusso.impl=au.edu.griffith.blackboard.psauthmodule.PsSsoAuthModule
auth.type.gusso.use_challenge=false
{code}
* If you wish to extend the LDAPAuthModule, you *must keep the auth type as 'ldap'*. If you don't, it won't be able to load the ldap server properties.


----
{anchor:examples}

h3. Examples

* The blackboard Authentication Guide (the title in the file is Authentication Manual) has a lot of information and some examples.
* The university of Bristol has written a CAS authentication module. Details can be found at the [CASifying Blackboard|http://www.bris.ac.uk/ips-projects/portal/pilot/software/blackboard_cas/] page.
* An example of a [generalised cascading authentication system|http://www.edugarage.com/download/attachments/14058847/CustomAuthentication.jar] with source code.