This tutorial covers the installation, configuration, and development of custom authentication modules. Much of this information can also be found in the Blackboard Authentication Guide (latest release is 6.3) In addition to the custom authentication APIs that ship with the product, Blackboard has contributed an open source Building Block to OSCELOT that implements the AutoSignOn protocol for passing users into Blackboard without the need to reauthenticate. With the release of Blackboard Learn 9.1, Service Pack 8, a new, pluggable authentication framework is available, that can be written to by Building Blocks. A Source Code Example that connects to LDAP services, is available on Behind the Blackboard.

Tutorial Contents Background Information Installation installation details Configuration configuration details Build your own Cascading modules Handling Error states Gotchas Examples

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
• Shared Secret

And others (add yours here).

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

Installing and Configuring custom authentication modules

Configuration details

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

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.

1. /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"
2. /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
3. Sending email from announcements. Check the knowledge base article
   Read the article and modify the specified Perl Script(s)

   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.

Build your own

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.

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.

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.

// 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;
}

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
  bb-config.properties

  bbconfig.auth.type=my-module
  

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

  auth.type.gusso.impl=au.edu.griffith.blackboard.psauthmodule.PsSsoAuthModule
  auth.type.gusso.use_challenge=false
  

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

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 page.
• An example of a generalised cascading authentication system with source code.